📝 Update performance measurements section

* Add cProfile/profiling.tracing
* Add tprof

Author: veit

docs/performance/index.rst

@@ -62,18 +62,24 @@ Performance measurements
 ------------------------
 
 Once you have worked with your code, it can be useful to examine its efficiency
-more closely. `cProfile
-<https://docs.python.org/3.14/library/profile.html#module-cProfile>`_,
-:doc:`ipython-profiler` or :doc:`scalene` can be used for this.
+more closely. :doc:`cProfile <tracing>`, :doc:`ipython-profiler`, :doc:`scalene`
+or :doc:`tprof` can be used for this. So far, I usually carry out the following
+steps:
+
+#. I profile the entire programme with :doc:`cProfile <tracing>` or `py-spy
+   <https://github.com/benfred/py-spy>`_ to find slow functions.
+#. Then I optimise a slow function.
+#. Finally, I create a new profile and filter out the result of my optimised
+   version so that I can compare the results.
 
 .. versionadded:: Python3.15
    :pep:`799` will provide a special profiling module that organises the
    profiling tools integrated in Python under a uniform namespace. This module
    contains:
 
    :mod:`profiling.tracing`
-       deterministic function call tracing, which has been moved from `cProfile
-       <https://docs.python.org/3.14/library/profile.html#module-cProfile>`_.
+       deterministic function call tracing, which has been moved from
+       :doc:`cProfile <tracing>`.
    :mod:`profiling.sampling`
        the new statistical sampling profiler :doc:`tachyon`.
 
@@ -91,8 +97,10 @@ more closely. `cProfile
     :titlesonly:
     :maxdepth: 0
 
+    tracing
     ipython-profiler.ipynb
     scalene.ipynb
+    tprof
     tachyon
 
 Search for existing implementations

docs/performance/tprof.rst

@@ -0,0 +1,67 @@
+.. SPDX-FileCopyrightText: 2026 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+``tprof``
+=========
+
+`tprof <https://github.com/adamchainz/tprof>`_ measures from Python 3.12 onwards
+the time spent executing a module in specific functions. Unlike other profilers,
+it only tracks the specified functions with :mod:`sys.monitoring`, eliminating
+the need for filtering.
+
+``tprof`` supports use as a command line programme and with a Python interface:
+
+:samp:`uv run tprof -t {MODULE}:{FUNCTION} (-m {MODULE} | {PATH/TO/SCRIPT})`
+    Suppose you have determined that creating :class:`pathlib.Path` objects in
+    the :mod:`main` module is slowing down your code. Here’s how you can measure
+    this with ``tprof``:
+
+    .. 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
+
+    With the ``-x`` option, you can also compare two functions with each other:
+
+    .. 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)``
+    uses this code as a :doc:`context manager <python-basics:control-flow/with>`
+    in your code to perform profiling in a specific block. The report is
+    generated each time the block is run through.
+
+    ``*targets``
+        are callable elements for profiling or references to elements that are
+        resolved with :func:`pkgutil.resolve_name`.
+    ``label``
+        is an optional string that can be added to the report as a header.
+    ``compare``
+        set to ``True`` activates comparison mode.
+
+    Example:
+
+    .. 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,45 @@
+.. SPDX-FileCopyrightText: 2026 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+cProfile/profiling.tracing
+==========================
+
+Usually, a profile is created in the command line with `cProfile
+<https://docs.python.org/3.14/library/profile.html#module-cProfile>`_ or, from
+Python 3.15 onwards, with :mod:`profiling.tracing`, which then displays its
+profile statistics. However, this can quickly become very tedious, especially
+when reading extensive profiles or sorting the data. A more flexible approach is
+to save the profile data in a file instead, which can then be read with the
+:mod:`pstats` module:
+
+#. :samp:`uv run python -m cProfile -o {PROFILE} ({SCRIPT} | {-m {MODULE})`
+   runs `cProfile
+   <https://docs.python.org/3.14/library/profile.html#module-cProfile>`_ to
+   profile your script or module and saves the results in a file specified by
+   the ``-o`` option.
+
+#. :samp:`uv run python -m (cProfile | profiling.tracing) -o profile ({SCRIPT} |
+   -m {MODULE}) <<< $'sort cumtime\nstats 100' | less` passes the following two
+   commands to the :mod:`pstats` module using the ``$`` syntax.
+
+   ``sort cumtime``
+       sorts the output by cumulative time, starting with the largest.
+
+       To sort by other metrics, simply replace ``cumtime`` with a value from
+       :meth:`pstats.Stats.sort_stats`.
+
+   ``stats 100``
+       displays the first 100 lines of the profile.
+
+   The output is passed to ``less`` so you can view the results. Press :kbd:`q`
+   to exit when you are finished.
+
+#. Before and after optimisation can be easily compared, for example with:
+
+   .. 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