diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index a2c7e7ec2e3..1290e552e36 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -1,8 +1,8 @@ PEP: 799 -Title: A dedicated ``profilers`` package for organizing Python profiling tools +Title: A dedicated ``profiling`` package for organizing Python profiling tools Author: Pablo Galindo , - László Kiss Kollár , -Discussions-To: Pending + László Kiss Kollár +Discussions-To: https://discuss.python.org/t/pep-799-a-dedicated-profilers-package-for-organizing-python-profiling-tool/100898 Status: Draft Type: Standards Track Created: 21-Jul-2025 @@ -13,7 +13,7 @@ Abstract ======== This PEP proposes the creation of a new standard library module named -:mod:`!profilers` to organize Python's built-in profiling tools under a single, +:mod:`!profiling` to organize Python's built-in profiling tools under a single, coherent namespace. This PEP also proposes the deprecation of the :mod:`profile` module, a legacy @@ -54,12 +54,12 @@ This reorganization addresses several long-standing issues with Python’s profi First, it improves **discoverability** by collecting all built-in profilers under a single, clearly named namespace. Currently, profiling tools are scattered across modules with inconsistent naming and unclear relationships. By -introducing the ``profilers`` module, users will have a well-defined and +introducing the ``profiling`` module, users will have a well-defined and intuitive location to explore and access profiling functionality. Second, the proposal enhances **clarity** by naming the submodules according to -their underlying methodology -- ``profilers.tracing`` for deterministic tracing -profilers and ``profilers.sampling`` for statistical sampling profilers. This +their underlying methodology -- ``profiling.tracing`` for deterministic tracing +profilers and ``profiling.sampling`` for statistical sampling profilers. This explicit categorization makes it easier to understand the behavior and limitations of each tool and aligns the API with the mental model users are encouraged to adopt. @@ -67,7 +67,7 @@ encouraged to adopt. Third, it provides **guidance** to developers by making the recommended tools easier to find and use. The current structure can mislead users into relying on outdated or less performant modules like ``profile``, simply because of naming -precedence. With the ``profilers`` namespace and its clearer semantics, users +precedence. With the ``profiling`` namespace and its clearer semantics, users are more likely to choose the appropriate profiler for their specific use case, whether it involves low-overhead sampling or detailed tracing. @@ -75,7 +75,7 @@ Finally, this structure promotes **extensibility**. By consolidating profiling tools under a unified namespace, it becomes straightforward to introduce future profiling capabilities -- such as memory profilers, I/O profilers, or hybrid tools -- without overloading unrelated modules or adding redundant top-level names. -The ``profilers`` module provides a natural home for this. +The ``profiling`` module provides a natural home for this. Specification ============= @@ -83,13 +83,14 @@ Specification New Module Structure -------------------- -This PEP introduces a new ``profilers`` module containing: +This PEP introduces a new ``profiling`` module containing: -- ``profilers.tracing``: an alias for ``cProfile``, providing deterministic function-call tracing. -- ``profilers.sampling``: an alias for ``profilers.tachyon``, improving visibility and semantic clarity. +- ``profiling.tracing``: deterministic function-call tracing (relocated from ``cProfile``). +- ``profiling.sampling``: the statistical sampling profiler (tachyon). -Additionally the **code** for the ``tachyon`` profiler will be also relocated to -the module as ``profilers.tachyon``. +The ``cProfile`` implementation will be relocated to ``profiling.tracing``, with ``cProfile`` +remaining as an alias for backwards compatibility. The tachyon sampling profiler will be +available at ``profiling.sampling``. Deprecation of ``profile`` -------------------------- @@ -100,20 +101,20 @@ The ``profile`` module will be deprecated starting in Python 3.15. - In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``. - In Python 3.17: the module will be removed from the standard library. -From Python 3.15, :mod:`!profilers.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`. +From Python 3.15, :mod:`!profiling.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`. The code that, at the time of writing, is in the :mod:`!profile.sampling` -module will be moved to the :mod:`!profilers` package. +module will be moved to the :mod:`!profiling` package. Documentation ============= -The Python documentation will use the new :mod:`!profilers` module as the canonical +The Python documentation will use the new :mod:`!profiling` module as the canonical entry point for profiling functionality. It will also describe the distinction between tracing and sampling profilers, and include guidance on when each type is most appropriate. -Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to -the new ``profilers`` equivalents. +Documentation for ``cProfile`` will remain available but will link to +the new ``profiling`` equivalents. Backwards Compatibility ======================= @@ -134,13 +135,30 @@ Renaming ``cProfile`` Renaming ``cProfile`` to ``profile.tracing`` was considered, but this change would impact a large amount of existing code. Maintaining the original name while aliasing it under -``profilers.tracing`` strikes a balance between compatibility and clarity. +``profiling.tracing`` strikes a balance between compatibility and clarity. + +Using ``profilers`` as the Module Name +--------------------------------------- + +The module was initially proposed as ``profilers`` (plural) but was changed to ``profiling`` +(gerund form) based on community feedback. The gerund form is more consistent with other +Python standard library modules that represent categories of functionality. + +Multiple Names for the Sampling Profiler +----------------------------------------- + +An earlier version of this PEP proposed having the sampling profiler available under two names: +``profiling.sampling`` and ``profiling.tachyon``. This was rejected to avoid confusion - when +introducing new functionality, it's better to have a single, clear path to access it rather than +multiple aliases. The name ``profiling.sampling`` was chosen as it clearly describes the +profiling methodology, while "tachyon" remains as an internal codename that may be mentioned +in documentation. Top-Level ``tachyon`` Module ---------------------------- Introducing ``import tachyon`` as a new top-level module was rejected. Grouping tachyon under -``profilers`` helps establish a logical structure and prevents proliferation of top-level modules +``profiling`` helps establish a logical structure and prevents proliferation of top-level modules and also minimizes the usage of global namespace as requested by the Python Steering Council. Copyright