📝 Update performance measurements section

* Add tprof

Author: veit

docs/performance/index.rst

@@ -68,7 +68,20 @@ Performance-Messungen
 Wenn ihr erst einmal mit eurem Code gearbeitet habt, kann es nützlich sein, die
 Effizienz genauer zu untersuchen. Hierfür kann :abbr:`z. B. (zum Beispiel)`
 `cProfile <https://docs.python.org/3.14/library/profile.html#module-cProfile>`_,
-:doc:`ipython-profiler` oder :doc:`scalene` genutzt werden.
+:doc:`ipython-profiler`, :doc:`scalene` oder :doc:`tprof` genutzt werden.
+Bisher führe ich meist die folgenden Schritte aus:
+
+#. Ich profilierte das gesamte Programm mit `cProfile
+   <https://docs.python.org/3.14/library/profile.html#module-cProfile>`__ oder
+   `py-spy <https://github.com/benfred/py-spy>`_, um langsame Funktionen zu
+   finden.
+#. Anschließend optimiertee ich eine langsame Funktion.
+#. Schließlich erstellte ich ein neues Profil und filterte das Ergebnis meiner
+   optimierten Version heraus um die Ergebnisse vergleichen zu können.
+
+:mod:`sys.monitoring` in Python 3.12 vereinfachte das Monitoring bestimmter
+Funktionen. :doc:`tprof` nutzt dies, sodass im letzten Schritt nur noch das
+Profil für die optimierte Funktion erstellt werden muss.
 
 .. versionadded:: Python3.15
    Mit :pep:`799` wird ein spezielles Profiling-Modul zur Verfügung stehen, das
@@ -98,6 +111,7 @@ Effizienz genauer zu untersuchen. Hierfür kann :abbr:`z. B. (zum Beispiel)`
 
     ipython-profiler.ipynb
     scalene.ipynb
+    tprof
     tachyon
 
 Suche nach bestehenden Implementierungen

docs/performance/tprof.rst

@@ -0,0 +1,72 @@
+.. SPDX-FileCopyrightText: 2026 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+``tprof``
+=========
+
+`tprof <https://github.com/adamchainz/tprof>`_ misst die Zeit, die beim
+Ausführen eines Moduls in bestimmten Funktionen verbracht wird. Im Gegensatz zu
+anderen Profilern verfolgt es nur die angegebenen Funktionen mit
+:mod:`sys.monitoring`, wodurch man sich das Filtern sparen kann.
+
+``tprof`` unterstützt die Verwendung als Befehlszeilenprogramm und mit einer
+Python-Schnittstelle:
+
+:samp:`uv run tprof -t {MODUL}:{FUNKTION} (-m {MODUL} | {PATH/TO/SCRIPT})`
+    Angenommen, ihr habt festgestellt, dass die Erstellung von
+    :class:`pathlib.Path`-Objekten im :mod:`main`-Modul euren Code verlangsamt.
+    So könnt ihr dies mit ``tprof`` messen:
+
+    .. code-block:: console
+
+       $ uv run tprof -t pathlib:Path.open  -m main
+       🎯 tprof results:
+        function            calls total mean ± σ  min … max
+        pathlib:Path.open()     1  93μs 93μs     93μs … 93μs
+
+    Mit der ``-x``-Option könnt ihr auch zwei Funktionen miteinander
+    vergleichen:
+
+    .. code-block:: console
+
+       $ uv run tprof -x -t old -m main -t new -m main
+       🎯 tprof results:
+        function   calls total mean ± σ  min … max  delta
+        main:old()     1  41μs 41μs     41μs … 41μs -
+        main:new()     1  20μs 20μs     20μs … 20μs -50.67%
+
+``tprof(*targets, label: str | None = None, compare: bool = False)``
+    verwendet diesen Code als :doc:`Kontextmanager
+    <python-basics:control-flow/with>` oder :doc:`Dekorator
+    <python-basics:functions/decorators>` in eurem Code, um ein Profiling in
+    einem bestimmten Block durchzuführen. Der Bericht wird jedes Mal ausgegeben,
+    wenn der Block durchlaufen wurde.
+
+    ``*targets``
+        sind aufrufbare Elemente zum Profiling oder Referenzen zu Elementen, die
+        mit :func:`pkgutil.resolve_name` aufgelöst werden.
+    ``label``
+        ist eine optionale Zeichenfolge, die als Kopfzeile dem Bericht
+        hinzugefügt werden kann.
+    ``compare``
+        auf ``True`` gesetzt, wird der Vergleichsmodus aktiviert.
+
+    Beispiel:
+
+    .. code-block:: Python
+
+       from pathlib import Path
+
+       from tprof import tprof
+
+       with tprof(Path.open):
+           p = Path("docs", "save-data", "myfile.txt")
+           f = p.open()
+
+    .. code-block:: console
+
+       $ uv run python main.py
+       🎯 tprof results:
+        function            calls total mean ± σ  min … max
+        pathlib:Path.open()     1  82μs 82μs     82μs … 82μs