tprof 1.0.0__tar.gz

tprof-1.0.0/CHANGELOG.rst

@@ -0,0 +1,8 @@
+=========
+Changelog
+=========
+
+1.0.0 (2026-01-14)
+------------------
+
+* Initial release.

tprof-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adam Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tprof-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+prune tests
+include CHANGELOG.rst
+include LICENSE
+include pyproject.toml
+include README.rst
+include src/*/py.typed

tprof-1.0.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: tprof
+Version: 1.0.0
+Summary: A targeting profiler.
+Author-email: Adam Johnson <me@adamj.eu>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/adamchainz/tprof/blob/main/CHANGELOG.rst
+Project-URL: Funding, https://adamj.eu/books/
+Project-URL: Repository, https://github.com/adamchainz/tprof
+Keywords: performance,profiler,profiling,target
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: rich>=14.2
+Dynamic: license-file
+
+=========
+🎯 tprof
+=========
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/tprof/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/tprof/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/tprof/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/tprof.svg?style=for-the-badge
+   :target: https://pypi.org/project/tprof/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+A targeting profiler.
+
+.. figure:: https://raw.githubusercontent.com/adamchainz/tprof/main/screenshot.svg
+   :alt: tprof in action.
+
+----
+
+**Get better at command line Git** with my book `Boost Your Git DX <https://adamchainz.gumroad.com/l/bygdx>`__.
+
+----
+
+Requirements
+------------
+
+Python 3.12 to 3.14 supported.
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install tprof
+
+Usage
+-----
+
+tprof measures the time spent in specified target functions when running a script or module.
+Unlike a full program profiler, it only tracks the specified functions using |sys.monitoring|__ (new in Python 3.12), reducing overhead and helping you focus on the bits you’re changing.
+Timing is done in C to further reduce overhead.
+
+.. |sys.monitoring| replace:: ``sys.monitoring``
+__ https://docs.python.org/3/library/sys.html#sys.monitoring
+
+tprof supports usage as a CLI and with a Python API.
+
+CLI
+---
+
+Specify one or more target functions with ``-t``, then what to run: a script file by filename, or a module with ``-m`` then its name.
+Any unrecognized arguments are passed to the script or module.
+
+Use the format ``<module>:<function>`` to specify target functions.
+When using ``-m`` with a module, you can skip the ``<module>`` part and it will be inferred from the module name.
+
+.. code-block:: console
+
+    $ tprof -t lib:maths ./example.py
+    ...
+    🎯 tprof results:
+     function    calls total  mean ± σ     min … max
+     lib:maths()     2 610ms 305ms ± 2ms 304ms … 307ms
+
+Full help:
+
+.. [[[cog
+.. import cog
+.. import subprocess
+.. import sys
+.. result = subprocess.run(
+..     [sys.executable, "-m", "tprof", "--help"],
+..     capture_output=True,
+..     text=True,
+.. )
+.. cog.outl("")
+.. cog.outl(".. code-block:: console")
+.. cog.outl("")
+.. for line in result.stdout.splitlines():
+..     if line.strip() == "":
+..         cog.outl("")
+..     else:
+..         cog.outl("   " + line.rstrip())
+.. cog.outl("")
+.. ]]]
+
+.. code-block:: console
+
+   usage: tprof [-h] -t target [-x] (-m module | script) ...
+
+   positional arguments:
+     script         Python script to run
+     args           Arguments to pass to the script or module
+
+   options:
+     -h, --help     show this help message and exit
+     -t target      Target callable to profile (format: module:function).
+     -x, --compare  Compare performance of targets, with the first as baseline.
+     -m module      Run library module as a script (like python -m)
+
+.. [[[end]]]
+
+Comparison mode
+^^^^^^^^^^^^^^^
+
+Pass ``-x`` (``--compare``) to compare the performance of multiple target functions, with the first as the baseline, in an extra “delta” column.
+For example, given this code:
+
+.. code-block:: python
+
+    def before():
+        total = 0
+        for i in range(100_000):
+            total += i
+        return total
+
+
+    def after():
+        return sum(range(100_000))
+
+
+    for _ in range(100):
+        before()
+        after()
+
+…you can run tprof like this to compare the two functions:
+
+.. code-block:: console
+
+    $ tprof -x -t before -t after -m example
+    🎯 tprof results:
+     function         calls total  mean ± σ      min … max   delta
+     example:before()   100 227ms   2ms ± 34μs   2ms … 2ms   -
+     example:after()    100  86ms 856μs ± 15μs 835μs … 910μs -62.27%
+
+API
+---
+
+``tprof(*targets, label: str | None = None, compare: bool = False)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this context manager / decorator within your code to perform profiling in a specific block.
+The report is printed when the block ends, each time it ends.
+
+Each item in ``targets`` may be a callable to profile, or a string reference to one that will be resolved with |pkgutil.resolve_name()|__.
+
+.. |pkgutil.resolve_name()| replace:: ``pkgutil.resolve_name()``
+__ https://docs.python.org/3.14/library/pkgutil.html#pkgutil.resolve_name
+
+``label`` is an optional string to add to the report heading to distinguish multiple reports.
+
+Set ``compare`` to ``True`` to enable comparison mode, as documented above in the CLI section.
+
+For example, given this code:
+
+.. code-block:: python
+
+    from lib import maths
+
+    from tprof import tprof
+
+    print("Doing the maths…")
+    with tprof(maths):
+        maths()
+    print("The maths has been done!")
+
+…running it would produce output like:
+
+.. code-block:: console
+
+    $ python example.py
+    Doing the maths…
+    🎯 tprof results:
+     function    calls total  mean ± σ   min … max
+     lib:maths()     1 305ms 305ms     305ms … 305ms
+    The maths has been done!
+
+Another example using comparison mode:
+
+.. code-block:: python
+
+    from tprof import tprof
+
+
+    def before():
+        total = 0
+        for i in range(100_000):
+            total += i
+        return total
+
+
+    def after():
+        return sum(range(100_000))
+
+
+    with tprof(before, after, compare=True):
+        for _ in range(100):
+            before()
+            after()
+
+…which produces output like:
+
+.. code-block:: console
+
+    $ python example.py
+    🎯 tprof results:
+     function          calls total  mean ± σ      min … max delta
+     __main__:before()   100 227ms   2ms ± 83μs   2ms … 3ms -
+     __main__:after()    100  85ms 853μs ± 22μs 835μs … 1ms -62.35%
+
+History
+-------
+
+When optimizing Python code, I found I was using this workflow:
+
+1. Profile the whole program with a tool like `cProfile <https://docs.python.org/3.14/library/profile.html>`__ or `py-spy <https://github.com/benfred/py-spy>`__ to find slow functions.
+2. Pick a function to optimize.
+3. Make a change.
+4. Re-profile the whole program to see if the changes helped.
+
+This works fined but profiling the whole program again adds overhead, and picking out the one function’s stats from the report is extra work.
+When I saw that Python 3.12’s |sys.monitoring2|__ allows tracking specific functions with low overhead, I created tprof to streamline this workflow, allowing the final step to re-profile just the target function.
+
+.. |sys.monitoring2| replace:: ``sys.monitoring``
+__ https://docs.python.org/3/library/sys.html#sys.monitoring
+
+It also seemed a natural extension that tprof could compare multiple functions, supporting a nice microbenchmarking workflow.
+
+Output inspired by `poop <https://github.com/andrewrk/poop>`__.

tprof-1.0.0/README.rst

@@ -0,0 +1,241 @@
+=========
+🎯 tprof
+=========
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/tprof/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/tprof/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/tprof/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/tprof.svg?style=for-the-badge
+   :target: https://pypi.org/project/tprof/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+A targeting profiler.
+
+.. figure:: https://raw.githubusercontent.com/adamchainz/tprof/main/screenshot.svg
+   :alt: tprof in action.
+
+----
+
+**Get better at command line Git** with my book `Boost Your Git DX <https://adamchainz.gumroad.com/l/bygdx>`__.
+
+----
+
+Requirements
+------------
+
+Python 3.12 to 3.14 supported.
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install tprof
+
+Usage
+-----
+
+tprof measures the time spent in specified target functions when running a script or module.
+Unlike a full program profiler, it only tracks the specified functions using |sys.monitoring|__ (new in Python 3.12), reducing overhead and helping you focus on the bits you’re changing.
+Timing is done in C to further reduce overhead.
+
+.. |sys.monitoring| replace:: ``sys.monitoring``
+__ https://docs.python.org/3/library/sys.html#sys.monitoring
+
+tprof supports usage as a CLI and with a Python API.
+
+CLI
+---
+
+Specify one or more target functions with ``-t``, then what to run: a script file by filename, or a module with ``-m`` then its name.
+Any unrecognized arguments are passed to the script or module.
+
+Use the format ``<module>:<function>`` to specify target functions.
+When using ``-m`` with a module, you can skip the ``<module>`` part and it will be inferred from the module name.
+
+.. code-block:: console
+
+    $ tprof -t lib:maths ./example.py
+    ...
+    🎯 tprof results:
+     function    calls total  mean ± σ     min … max
+     lib:maths()     2 610ms 305ms ± 2ms 304ms … 307ms
+
+Full help:
+
+.. [[[cog
+.. import cog
+.. import subprocess
+.. import sys
+.. result = subprocess.run(
+..     [sys.executable, "-m", "tprof", "--help"],
+..     capture_output=True,
+..     text=True,
+.. )
+.. cog.outl("")
+.. cog.outl(".. code-block:: console")
+.. cog.outl("")
+.. for line in result.stdout.splitlines():
+..     if line.strip() == "":
+..         cog.outl("")
+..     else:
+..         cog.outl("   " + line.rstrip())
+.. cog.outl("")
+.. ]]]
+
+.. code-block:: console
+
+   usage: tprof [-h] -t target [-x] (-m module | script) ...
+
+   positional arguments:
+     script         Python script to run
+     args           Arguments to pass to the script or module
+
+   options:
+     -h, --help     show this help message and exit
+     -t target      Target callable to profile (format: module:function).
+     -x, --compare  Compare performance of targets, with the first as baseline.
+     -m module      Run library module as a script (like python -m)
+
+.. [[[end]]]
+
+Comparison mode
+^^^^^^^^^^^^^^^
+
+Pass ``-x`` (``--compare``) to compare the performance of multiple target functions, with the first as the baseline, in an extra “delta” column.
+For example, given this code:
+
+.. code-block:: python
+
+    def before():
+        total = 0
+        for i in range(100_000):
+            total += i
+        return total
+
+
+    def after():
+        return sum(range(100_000))
+
+
+    for _ in range(100):
+        before()
+        after()
+
+…you can run tprof like this to compare the two functions:
+
+.. code-block:: console
+
+    $ tprof -x -t before -t after -m example
+    🎯 tprof results:
+     function         calls total  mean ± σ      min … max   delta
+     example:before()   100 227ms   2ms ± 34μs   2ms … 2ms   -
+     example:after()    100  86ms 856μs ± 15μs 835μs … 910μs -62.27%
+
+API
+---
+
+``tprof(*targets, label: str | None = None, compare: bool = False)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this context manager / decorator within your code to perform profiling in a specific block.
+The report is printed when the block ends, each time it ends.
+
+Each item in ``targets`` may be a callable to profile, or a string reference to one that will be resolved with |pkgutil.resolve_name()|__.
+
+.. |pkgutil.resolve_name()| replace:: ``pkgutil.resolve_name()``
+__ https://docs.python.org/3.14/library/pkgutil.html#pkgutil.resolve_name
+
+``label`` is an optional string to add to the report heading to distinguish multiple reports.
+
+Set ``compare`` to ``True`` to enable comparison mode, as documented above in the CLI section.
+
+For example, given this code:
+
+.. code-block:: python
+
+    from lib import maths
+
+    from tprof import tprof
+
+    print("Doing the maths…")
+    with tprof(maths):
+        maths()
+    print("The maths has been done!")
+
+…running it would produce output like:
+
+.. code-block:: console
+
+    $ python example.py
+    Doing the maths…
+    🎯 tprof results:
+     function    calls total  mean ± σ   min … max
+     lib:maths()     1 305ms 305ms     305ms … 305ms
+    The maths has been done!
+
+Another example using comparison mode:
+
+.. code-block:: python
+
+    from tprof import tprof
+
+
+    def before():
+        total = 0
+        for i in range(100_000):
+            total += i
+        return total
+
+
+    def after():
+        return sum(range(100_000))
+
+
+    with tprof(before, after, compare=True):
+        for _ in range(100):
+            before()
+            after()
+
+…which produces output like:
+
+.. code-block:: console
+
+    $ python example.py
+    🎯 tprof results:
+     function          calls total  mean ± σ      min … max delta
+     __main__:before()   100 227ms   2ms ± 83μs   2ms … 3ms -
+     __main__:after()    100  85ms 853μs ± 22μs 835μs … 1ms -62.35%
+
+History
+-------
+
+When optimizing Python code, I found I was using this workflow:
+
+1. Profile the whole program with a tool like `cProfile <https://docs.python.org/3.14/library/profile.html>`__ or `py-spy <https://github.com/benfred/py-spy>`__ to find slow functions.
+2. Pick a function to optimize.
+3. Make a change.
+4. Re-profile the whole program to see if the changes helped.
+
+This works fined but profiling the whole program again adds overhead, and picking out the one function’s stats from the report is extra work.
+When I saw that Python 3.12’s |sys.monitoring2|__ allows tracking specific functions with low overhead, I created tprof to streamline this workflow, allowing the final step to re-profile just the target function.
+
+.. |sys.monitoring2| replace:: ``sys.monitoring``
+__ https://docs.python.org/3/library/sys.html#sys.monitoring
+
+It also seemed a natural extension that tprof could compare multiple functions, supporting a nice microbenchmarking workflow.
+
+Output inspired by `poop <https://github.com/andrewrk/poop>`__.

tprof-1.0.0/pyproject.toml

@@ -0,0 +1,149 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=77",
+]
+
+[project]
+name = "tprof"
+version = "1.0.0"
+description = "A targeting profiler."
+readme = "README.rst"
+keywords = [
+  "performance",
+  "profiler",
+  "profiling",
+  "target",
+]
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+  { name = "Adam Johnson", email = "me@adamj.eu" },
+]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "rich>=14.2",
+]
+urls.Changelog = "https://github.com/adamchainz/tprof/blob/main/CHANGELOG.rst"
+urls.Funding = "https://adamj.eu/books/"
+urls.Repository = "https://github.com/adamchainz/tprof"
+scripts.tprof = "tprof.main:main"
+
+[dependency-groups]
+test = [
+  "cogapp>=3.6",
+  "coverage[toml]",
+  "pytest",
+  "pytest-randomly",
+]
+
+[tool.cibuildwheel]
+build = [
+  "cp314-*",
+  "cp314t-*",
+  "cp313-*",
+  "cp313t-*",
+  "cp312-*",
+  "cp311-*",
+  "cp310-*",
+]
+enable = [
+  # Enable free-threaded wheels on Python 3.13 (where it was experimental)
+  "cpython-freethreading",
+]
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.14"
+
+[tool.pytest.ini_options]
+addopts = """\
+    --strict-config
+    --strict-markers
+    """
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+parallel = true
+source = [
+  "tprof",
+  "tests",
+]
+
+[tool.coverage.paths]
+source = [
+  "src",
+  ".tox/**/site-packages",
+]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+  "if TYPE_CHECKING:",
+]
+
+[tool.mypy]
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+mypy_path = "src/"
+namespace_packages = false
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+allow_untyped_defs = true
+
+[tool.rstcheck]
+report_level = "ERROR"

tprof-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+