Metadata-Version: 2.4
Name: pytest-perf
Version: 0.17.0
Summary: Run performance tests against the mainline code.
Author-email: "Jason R. Coombs" <jaraco@jaraco.com>
License-Expression: MIT
Project-URL: Source, https://github.com/jaraco/pytest-perf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pip-run>=8.5
Requires-Dist: tempora>=5.12
Requires-Dist: jaraco.functools>=4.6
Requires-Dist: more_itertools
Requires-Dist: jaraco.context
Requires-Dist: packaging
Requires-Dist: jaraco.compat>=4.1
Requires-Dist: jaraco.text>=4.3
Provides-Extra: test
Requires-Dist: pytest!=8.1.*,>=6; extra == "test"
Requires-Dist: pytest-subprocess; extra == "test"
Requires-Dist: jaraco.test>=5.7; extra == "test"
Provides-Extra: doc
Requires-Dist: sphinx>=3.5; extra == "doc"
Requires-Dist: jaraco.packaging>=9.3; extra == "doc"
Requires-Dist: rst.linker>=1.9; extra == "doc"
Requires-Dist: furo; extra == "doc"
Requires-Dist: sphinx-lint; extra == "doc"
Provides-Extra: check
Requires-Dist: pytest-checkdocs>=2.14; extra == "check"
Requires-Dist: pytest-ruff>=0.2.1; sys_platform != "cygwin" and extra == "check"
Provides-Extra: cover
Requires-Dist: pytest-cov; extra == "cover"
Provides-Extra: enabler
Requires-Dist: pytest-enabler>=3.4; extra == "enabler"
Provides-Extra: type
Requires-Dist: pytest-mypy>=1.0.1; platform_python_implementation != "PyPy" and extra == "type"
Requires-Dist: jaraco.compat>=4.2.2; extra == "type"
Dynamic: license-file

.. image:: https://img.shields.io/pypi/v/pytest-perf.svg
   :target: https://pypi.org/project/pytest-perf

.. image:: https://img.shields.io/pypi/pyversions/pytest-perf.svg

.. image:: https://github.com/jaraco/pytest-perf/actions/workflows/main.yml/badge.svg
   :target: https://github.com/jaraco/pytest-perf/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

.. .. image:: https://readthedocs.org/projects/PROJECT_RTD/badge/?version=latest
..    :target: https://PROJECT_RTD.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2026-informational
   :target: https://blog.jaraco.com/skeleton

Run performance tests against the mainline code.

Usage
=====

To use it, include pytest-perf in the test dependencies for your project, then create some Python module in your package. The plugin will include any module that contains the text "pytest_perf" and will run performance tests on each function containing "perf" (or "import_time") in the name.

Tests don't execute the module directly, but instead parse out the code of the function in two parts, the warmup and the test, separated by a "# end warmup" comment, and then passes those to the ``timeit`` module.

See the ``exercises.py`` module for example usage.

Import latency
==============

``timeit`` cannot measure the cost of importing a module, because after the
first loop the module is cached in ``sys.modules`` and subsequent loops only
measure the cache lookup. To measure import latency instead, name the function
with ``import_time`` (in place of ``perf``) and let its body perform the
import::

    def check_import_time():
        import importlib_metadata

Such a function is traced with ``python -X importtime`` in a fresh interpreter
(sampled a few times, reporting the fastest) rather than timed with ``timeit``,
capturing the real cold-import cost against both the control and the experiment.

Design
======

``pytest-perf`` works by creating two installs, the control and the experiment, and measuring the performance of some python code against each.

Under the hood, it uses ``pip-run`` to install from the upstream main branch (e.g. https://github.com/jaraco/pytest-perf) for the control and from ``.`` for the experiment. It then runs each of the experiments against each of the enviroments.
