📝 Update performance measurements section

* Add cProfile/profiling.tracing
* Add tprof

Author: veit

docs/performance/index.rst

@@ -67,18 +67,28 @@ 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:`cProfile <tracing>`, :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 :doc:`cProfile <tracing>` 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
    die in Python integrierten Profiling-Tools unter einem einheitlichen
    Namespace organisiert. Dieses Modul enthält:
 
    :mod:`profiling.tracing`
-       deterministische Funktionsaufrufverfolgung, die aus `cProfile
-       <https://docs.python.org/3.14/library/profile.html#module-cProfile>`_
-       verschoben wurde.
+       deterministische Funktionsaufrufverfolgung, die aus :doc:`cProfile
+       <tracing>` verschoben wurde.
    :mod:`profiling.sampling`
        der neue statistische Sampling-Profiler :doc:`tachyon`.
 
@@ -96,8 +106,10 @@ Effizienz genauer zu untersuchen. Hierfür kann :abbr:`z. B. (zum Beispiel)`
     :titlesonly:
     :maxdepth: 0
 
+    tracing
     ipython-profiler.ipynb
     scalene.ipynb
+    tprof
     tachyon
 
 Suche nach bestehenden Implementierungen

docs/performance/tprof.rst

@@ -0,0 +1,71 @@
+.. 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 {MODULE}:{FUNCTION} (-m {MODULE} | {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>` in eurem Code, um ein Profil in einem
+    bestimmten Block zu erstellen. 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

docs/performance/tracing.rst

@@ -0,0 +1,48 @@
+.. SPDX-FileCopyrightText: 2026 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+cProfile/profiling.tracing
+==========================
+
+Üblicherweise wird in der Kommandozeile mit `cProfile
+<https://docs.python.org/3.14/library/profile.html#module-cProfile>`_ oder ab
+Python 3.15 mit :mod:`profiling.tracing` ein Profil erstellt, das anschließend
+dessen Profilstatistiken anzeigt. Dies kann jedoch schnell sehr mühsam sein,
+insbesondere beim Lesen umfangreicher Profile oder beim Sortieren der Daten.
+Flexibler ist, die Profildaten stattdessen in einer Datei zu speichern, die dann
+mit dem :mod:`pstats`-Modul gelesen werden kann:
+
+#. :samp:`uv run python -m cProfile -o {PROFILE} ({SCRIPT} | {-m {MODULE})`
+   führt `cProfile
+   <https://docs.python.org/3.14/library/profile.html#module-cProfile>`_ zum
+   Profilerstellung eures Script oder eures Moduls aus und speichert die
+   Ergebnisse in einer Datei, die durch die Option ``-o`` angegeben wird.
+
+#. :samp:`uv run python -m (cProfile | profiling.tracing) -o profile ({SCRIPT} |
+   -m {MODULE}) <<< $'sort cumtime\nstats 100' | less` übergibt die folgenden
+   beiden Befehle an das :mod:`pstats`-Modul, wobei die ``$``-Syntax verwendet
+   wird.
+
+   ``sort cumtime``
+       sortiert die Ausgabe nach kumulativer Zeit, beginnend mit der größten.
+
+       Um nach anderen Metriken zu sortieren, könnt ihr ``cumtime`` einfach
+       durch einen Wert aus :meth:`pstats.Stats.sort_stats` ersetzen.
+
+   ``stats 100``
+       zeigt die ersten 100 Zeilen des Profils an.
+
+   Die Ausgabe wird an ``less`` übergeben, sodass ihr euch die Ergebnisse
+   anschauen könnt. Drückt :kbd:`q`, um den Vorgang zu beenden, wenn ihr fertig
+   seid.
+
+#. Vor und nach der Optimierung lassen sich einfach vergleichen, :abbr:`z. B.
+   (zum Beispiel)` mit:
+
+   .. code-block:: console
+
+      $ uv run python -m cProfile -o before.profile main.py
+      $ git switch -c main_optimisation
+      ...
+      $ uv run python -m cProfile -o after.profile main.py