profiling package for organizing Python profiling tools
This PEP proposes the creation of a new standard library module named profiling to organize Python’s built-in profiling tools under a single, coherent namespace.
This PEP also proposes the deprecation of the profile module, a legacy pure-Python tracing profiler.
Python currently ships with two tracing profilers: profile and cProfile. The profile module is implemented in pure Python and is largely educational or useful for subclassing, but too slow for realistic use. cProfile, by contrast, is implemented in C and more suitable for practical profiling scenarios, although it is not a drop-in replacement for profile due to some behavioral differences.
Both of these are tracing profilers, meaning they instrument every function call and return. This methodology introduces significant runtime overhead and can disable certain interpreter optimizations, such as those introduced by PEP 659. Moreover, cProfile only observes the main thread, making it less useful in modern concurrent Python programs. Confusingly, the naming of these modules implies that profile is canonical, when in fact it is largely obsolete.
With Python 3.15, a new sampling profiler was introduced under profile.sample. Known as tachyon, this tool uses statistical sampling to infer performance characteristics, which introduces zero overhead profiling and works better with the modern Python interpreter. It also supports multiple threads, async functions, free threading builds and attaching to running processes. Despite these strengths, the placement of tachyon under profile.sample is misleading and obscures its importance.
Currently, the organization of profiling tools lacks a consistent, discoverable structure. The proposed reorganization is meant to guide users more effectively toward appropriate tools, clarify methodological distinctions between profilers, and lay the groundwork for future extensions.
RationaleThis reorganization addresses several long-standing issues with Python’s profiling tools.
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 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 – 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.
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 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.
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 profiling module provides a natural home for this.
This PEP introduces a new profiling module containing:
profiling.tracing: deterministic function-call tracing (relocated from cProfile).profiling.sampling: the statistical sampling profiler (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.
profile
The profile module will be deprecated starting in Python 3.15.
profile emits a DeprecationWarning.profile emit a DeprecationWarning.From Python 3.15, profiling.tracing will be preferred to cProfile & profile.
The code that, at the time of writing, is in the profile.sampling module will be moved to the profiling package.
The Python documentation will use the new 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 will remain available but will link to the new profiling equivalents.
The only backwards incompatible aspect of this PEP is the future removal of the profile module but this will be made following the PEP 387 procedure.
None.
Rejected Alternatives RenamingcProfile
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 profiling.tracing strikes a balance between compatibility and clarity.
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.
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.
tachyon Module
Introducing import tachyon as a new top-level module was rejected. Grouping tachyon under 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.
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4