📝 Update performance measurements section

* Add tprof

Author: veit

docs/performance/index.rst

@@ -64,7 +64,19 @@ 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.
+: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 `cProfile
+   <https://docs.python.org/3.14/library/profile.html#module-cProfile>`__ 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.
+
+:mod:`sys.monitoring` in Python 3.12 simplified the monitoring of certain
+functions.  :doc:`tprof` uses this, so that in the last step, only the profile
+for the optimised function needs to be created.
 
 .. versionadded:: Python3.15
    :pep:`799` will provide a special profiling module that organises the
@@ -93,6 +105,7 @@ more closely. `cProfile
 
     ipython-profiler.ipynb
     scalene.ipynb
+    tprof
     tachyon
 
 Search for existing implementations

docs/performance/tprof.rst

@@ -0,0 +1,69 @@
+.. SPDX-FileCopyrightText: 2026 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+``tprof``
+=========
+
+`tprof <https://github.com/adamchainz/tprof>`_ measures 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>`_ or :doc:`decorator
+    <python-basics:functions/decorators>`_ 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