From a864bba665780fcd44d8ba9a35fece808115e4ac Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 21 Jul 2025 12:53:56 +0200 Subject: [PATCH 01/11] PEP 795: A dedicated profilers module for organizing python profiling tools --- peps/pep-0795.rst | 157 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 peps/pep-0795.rst diff --git a/peps/pep-0795.rst b/peps/pep-0795.rst new file mode 100644 index 00000000000..2fdccb2c0cd --- /dev/null +++ b/peps/pep-0795.rst @@ -0,0 +1,157 @@ +PEP: 795 +Title: A dedicated ``profilers`` module for organizing python profiling tools +Author: Pablo Galindo , + László Kiss Kollár +Status: Draft +Type: Standards Track +Created: 17-Jul-2025 +Python-Version: 3.15 +Post-History: + +Abstract +======== + +This PEP proposes the creation of a new standard library module named +``profilers`` to organize Python's built-in profiling tools under a single, +coherent namespace. + +The ``profilers`` module will provide: + +- ``profilers.tracing`` – an alias for ``cProfile``, the standard deterministic profiler +- ``profilers.sampling`` – the new sampling profiler introduced in Python 3.15, + currently exposed as ``profile.sample`` (see below) +- ``profilers.tachyon`` – an additional alias for ``profilers.sampling`` to improve discoverability + +This PEP also proposes the deprecation of the ``profile`` module, a legacy pure-Python tracing profiler. + +Motivation +========== + +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 much lower overhead and works better with the modern Python interpreter. It also supports +multiple threads, async functions, 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. + +Rationale +========= + +This 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 ``profilers`` 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 +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 ``profilers`` 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 ``profilers`` module provides a natural home for the continued evolution of +Pytho + +Specification +============= + +New Module Structure +-------------------- + +This PEP introduces a new ``profilers`` module containing: + +- ``profilers.tracing``: an alias for ``cProfile``, providing deterministic function-call tracing. +- ``profilers.tachyon``: the **tachyon** sampling profiler, relocated from ``profile.sample``. +- ``profilers.sampling``: an alias for ``profilers.tachyon``, improving visibility and semantic clarity. + +Deprecation of ``profile`` +-------------------------- + +The ``profile`` module will be deprecated starting in Python 3.16. + +- In Python 3.15: + - Importing ``profile`` emits a ``DeprecationWarning``. +- In Python 3.16: + - All uses of ``profile`` emit a ``DeprecationWarning``. +- In Python 3.17: + - The module may be removed pending community feedback and migration metrics. + +Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and +``profilers.sampling`` instead of ``profile.sample``. + +Documentation +============= + +The official Python documentation will reflect the new ``profilers`` module as the canonical +entry point for profiling functionality. It will describe: + +- The distinction between tracing and sampling profilers. +- Guidance on when each is appropriate. + +Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to +the new ``profilers`` equivalents. + +Backwards Compatibility +======================= + +The PEP is fully backwards compatible as: + +- Existing imports and module usage of ``cProfile`` will remain valid. +- The ``profile`` module will continue to exist (with warnings) until at least Python 3.18. + +Security Implications +===================== + +None. + +Rejected Alternatives +===================== + +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. + +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 +and also minimizes the usage of global namespace as requested by the Python Steering council + +Copyright +========= + +This document is placed in the public domain or under the CC0-1.0-Universal +license, whichever is more permissive. From 45e5a9d954ee09225421c8f40e83fc7c1bd74a31 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 21 Jul 2025 13:51:02 +0200 Subject: [PATCH 02/11] Move to 799 --- .github/CODEOWNERS | 3 +++ peps/{pep-0795.rst => pep-0799.rst} | 0 2 files changed, 3 insertions(+) rename peps/{pep-0795.rst => pep-0799.rst} (100%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index b6673bf281a..e3834098f07 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -674,8 +674,11 @@ peps/pep-0792.rst @dstufft peps/pep-0793.rst @encukou peps/pep-0794.rst @brettcannon peps/pep-0798.rst @JelleZijlstra +peps/pep-0799.rst @pablogsal # ... peps/pep-0800.rst @JelleZijlstra +# ... +>>>>>>> c0fc1f6a (Move to 799) peps/pep-0801.rst @warsaw # ... peps/pep-2026.rst @hugovk diff --git a/peps/pep-0795.rst b/peps/pep-0799.rst similarity index 100% rename from peps/pep-0795.rst rename to peps/pep-0799.rst From 9bfd205ad589d39107b1732e056ae75d74ea3251 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Mon, 21 Jul 2025 23:10:32 +0100 Subject: [PATCH 03/11] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- peps/pep-0799.rst | 46 ++++++++++++++++++++++------------------------ 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 2fdccb2c0cd..af14cc54474 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -1,10 +1,11 @@ PEP: 795 -Title: A dedicated ``profilers`` module for organizing python profiling tools +Title: A dedicated ``profilers`` package for organizing Python profiling tools Author: Pablo Galindo , - László Kiss Kollár + László Kiss Kollár , +Discussions-To: Pending Status: Draft Type: Standards Track -Created: 17-Jul-2025 +Created: 21-Jul-2025 Python-Version: 3.15 Post-History: @@ -12,17 +13,17 @@ Abstract ======== This PEP proposes the creation of a new standard library module named -``profilers`` to organize Python's built-in profiling tools under a single, +:mod:`!profilers` to organize Python's built-in profiling tools under a single, coherent namespace. -The ``profilers`` module will provide: +The :mod:`!profilers` module will provide: -- ``profilers.tracing`` – an alias for ``cProfile``, the standard deterministic profiler -- ``profilers.sampling`` – the new sampling profiler introduced in Python 3.15, - currently exposed as ``profile.sample`` (see below) -- ``profilers.tachyon`` – an additional alias for ``profilers.sampling`` to improve discoverability +- :mod:`!profilers.tracing` – an alias for :mod:`cProfile`, the standard deterministic profiler +- :mod:`!profilers.sampling` – the new sampling profiler introduced in Python 3.15, + currently exposed as :mod:`!profile.sample` (see below) +- :mod:`!profilers.tachyon` – an additional alias for :mod:`!profilers.sampling` to improve discoverability -This PEP also proposes the deprecation of the ``profile`` module, a legacy pure-Python tracing profiler. +This PEP also proposes the deprecation of the :mod:`profile` module, a legacy pure-Python tracing profiler. Motivation ========== @@ -61,7 +62,7 @@ introducing the ``profilers`` 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 +their underlying methodology -- ``profilers.tracing`` for deterministic tracing profilers and ``profilers.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 @@ -76,10 +77,9 @@ 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 ``profilers`` module provides a natural home for the continued evolution of -Pytho +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. Specification ============= @@ -96,7 +96,7 @@ This PEP introduces a new ``profilers`` module containing: Deprecation of ``profile`` -------------------------- -The ``profile`` module will be deprecated starting in Python 3.16. +The ``profile`` module will be deprecated starting in Python 3.15. - In Python 3.15: - Importing ``profile`` emits a ``DeprecationWarning``. @@ -105,20 +105,18 @@ The ``profile`` module will be deprecated starting in Python 3.16. - In Python 3.17: - The module may be removed pending community feedback and migration metrics. -Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and -``profilers.sampling`` instead of ``profile.sample``. +From Python 3.15, :mod:`!profilers.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`. +The new :mod:`!profilers.sampling` module will only exist in the :mod:`profilers` package. Documentation ============= -The official Python documentation will reflect the new ``profilers`` module as the canonical -entry point for profiling functionality. It will describe: - -- The distinction between tracing and sampling profilers. -- Guidance on when each is appropriate. +The Python documentation will use the new :mod:`!profilers` 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. +the new ``profilers`` equivalents. Backwards Compatibility ======================= From c056581eca680b558e9c63fdb50b52fdd1e413cc Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 21 Jul 2025 23:18:53 +0100 Subject: [PATCH 04/11] Several improvements --- peps/pep-0795.rst | 148 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 peps/pep-0795.rst diff --git a/peps/pep-0795.rst b/peps/pep-0795.rst new file mode 100644 index 00000000000..4c6cb092100 --- /dev/null +++ b/peps/pep-0795.rst @@ -0,0 +1,148 @@ +PEP: 795 +Title: A dedicated ``profilers`` module for organizing python profiling tools +Author: Pablo Galindo , + László Kiss Kollár +Status: Draft +Type: Standards Track +Created: 17-Jul-2025 +Python-Version: 3.15 +Post-History: + +Abstract +======== + +This PEP proposes the creation of a new standard library module named +``profilers`` 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. + +Motivation +========== + +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``. Named +**tachyon**, this tool uses statistical sampling to infer performance characteristics, which +introduces much lower overhead and works better with the modern Python interpreter. It also supports +multiple threads, async functions, 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. + +Rationale +========= + +This 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 ``profilers`` 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 +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 ``profilers`` 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 ``profilers`` module provides a natural home for the continued evolution of +Pytho + +Specification +============= + +New Module Structure +-------------------- + +This PEP introduces a new ``profilers`` 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. + +Additionally the **code** for the ``tachyon`` profiler will be also relocated to +the module as ``profilers.tachyon``. + +Deprecation of ``profile`` +-------------------------- + +The ``profile`` module will be deprecated starting in Python 3.16. + +- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``. +- In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``. +- In Python 3.17: the module will be removed from the standard library. + +Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and +``profilers.sampling`` instead of ``profile.sample``. + +Documentation +============= + +The official Python documentation will reflect the new ``profilers`` module as the canonical +entry point for profiling functionality. It will describe: + +- The distinction between tracing and sampling profilers. +- Guidance on when each is appropriate. + +Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to +the new ``profilers`` equivalents. + +Backwards Compatibility +======================= + +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. + +Security Implications +===================== + +None. + +Rejected Alternatives +===================== + +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. + +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 +and also minimizes the usage of global namespace as requested by the Python Steering council + +Copyright +========= + +This document is placed in the public domain or under the CC0-1.0-Universal +license, whichever is more permissive. From 0b23605875eaa2f7bbbd1c1008a080a55a3f1845 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 16:40:03 +0100 Subject: [PATCH 05/11] Fix documents --- peps/pep-0799.rst | 35 ++++++++++++++--------------------- 1 file changed, 14 insertions(+), 21 deletions(-) diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index af14cc54474..46356d6214b 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -16,14 +16,8 @@ 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, coherent namespace. -The :mod:`!profilers` module will provide: - -- :mod:`!profilers.tracing` – an alias for :mod:`cProfile`, the standard deterministic profiler -- :mod:`!profilers.sampling` – the new sampling profiler introduced in Python 3.15, - currently exposed as :mod:`!profile.sample` (see below) -- :mod:`!profilers.tachyon` – an additional alias for :mod:`!profilers.sampling` to improve discoverability - -This PEP also proposes the deprecation of the :mod:`profile` module, a legacy pure-Python tracing profiler. +This PEP also proposes the deprecation of the :mod:`profile` module, a legacy +pure-Python tracing profiler. Motivation ========== @@ -36,7 +30,7 @@ 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 +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. @@ -90,23 +84,24 @@ New Module Structure This PEP introduces a new ``profilers`` module containing: - ``profilers.tracing``: an alias for ``cProfile``, providing deterministic function-call tracing. -- ``profilers.tachyon``: the **tachyon** sampling profiler, relocated from ``profile.sample``. - ``profilers.sampling``: an alias for ``profilers.tachyon``, improving visibility and semantic clarity. +Additionally the **code** for the ``tachyon`` profiler will be also relocated to +the module as ``profilers.tachyon``. + Deprecation of ``profile`` -------------------------- The ``profile`` module will be deprecated starting in Python 3.15. -- In Python 3.15: - - Importing ``profile`` emits a ``DeprecationWarning``. -- In Python 3.16: - - All uses of ``profile`` emit a ``DeprecationWarning``. -- In Python 3.17: - - The module may be removed pending community feedback and migration metrics. +- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``. +- 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`. -The new :mod:`!profilers.sampling` module will only exist in the :mod:`profilers` package. + +The code that as the time of writing this is in :mod:`!profilers.sampling` +module no longer exist and will only exist in the :mod:`profilers` package. Documentation ============= @@ -121,10 +116,8 @@ the new ``profilers`` equivalents. Backwards Compatibility ======================= -The PEP is fully backwards compatible as: - -- Existing imports and module usage of ``cProfile`` will remain valid. -- The ``profile`` module will continue to exist (with warnings) until at least Python 3.18. +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. Security Implications ===================== From 74aaf7184a5675d6dbdd042c4ffeab562df27529 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 16:40:46 +0100 Subject: [PATCH 06/11] Remove pep 795 file --- peps/pep-0795.rst | 148 ---------------------------------------------- 1 file changed, 148 deletions(-) delete mode 100644 peps/pep-0795.rst diff --git a/peps/pep-0795.rst b/peps/pep-0795.rst deleted file mode 100644 index 4c6cb092100..00000000000 --- a/peps/pep-0795.rst +++ /dev/null @@ -1,148 +0,0 @@ -PEP: 795 -Title: A dedicated ``profilers`` module for organizing python profiling tools -Author: Pablo Galindo , - László Kiss Kollár -Status: Draft -Type: Standards Track -Created: 17-Jul-2025 -Python-Version: 3.15 -Post-History: - -Abstract -======== - -This PEP proposes the creation of a new standard library module named -``profilers`` 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. - -Motivation -========== - -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``. Named -**tachyon**, this tool uses statistical sampling to infer performance characteristics, which -introduces much lower overhead and works better with the modern Python interpreter. It also supports -multiple threads, async functions, 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. - -Rationale -========= - -This 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 ``profilers`` 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 -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 ``profilers`` 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 ``profilers`` module provides a natural home for the continued evolution of -Pytho - -Specification -============= - -New Module Structure --------------------- - -This PEP introduces a new ``profilers`` 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. - -Additionally the **code** for the ``tachyon`` profiler will be also relocated to -the module as ``profilers.tachyon``. - -Deprecation of ``profile`` --------------------------- - -The ``profile`` module will be deprecated starting in Python 3.16. - -- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``. -- In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``. -- In Python 3.17: the module will be removed from the standard library. - -Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and -``profilers.sampling`` instead of ``profile.sample``. - -Documentation -============= - -The official Python documentation will reflect the new ``profilers`` module as the canonical -entry point for profiling functionality. It will describe: - -- The distinction between tracing and sampling profilers. -- Guidance on when each is appropriate. - -Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to -the new ``profilers`` equivalents. - -Backwards Compatibility -======================= - -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. - -Security Implications -===================== - -None. - -Rejected Alternatives -===================== - -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. - -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 -and also minimizes the usage of global namespace as requested by the Python Steering council - -Copyright -========= - -This document is placed in the public domain or under the CC0-1.0-Universal -license, whichever is more permissive. From 7a360cea2c885c79e574f955f239e9613eca3ca6 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 16:45:08 +0100 Subject: [PATCH 07/11] Fix documents --- peps/pep-0799.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 46356d6214b..4eda52945c2 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -87,7 +87,7 @@ This PEP introduces a new ``profilers`` module containing: - ``profilers.sampling``: an alias for ``profilers.tachyon``, improving visibility and semantic clarity. Additionally the **code** for the ``tachyon`` profiler will be also relocated to -the module as ``profilers.tachyon``. +the module as ``profilers.tachyon``. Deprecation of ``profile`` -------------------------- From 038dc73a27b7df7e7d2051b012233ca1c10b7c36 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 16:49:33 +0100 Subject: [PATCH 08/11] Fix documents --- peps/pep-0795.rst | 148 ++++++++++++++++++++++++++++++++++++++++++++++ peps/pep-0799.rst | 2 +- 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 peps/pep-0795.rst diff --git a/peps/pep-0795.rst b/peps/pep-0795.rst new file mode 100644 index 00000000000..4c6cb092100 --- /dev/null +++ b/peps/pep-0795.rst @@ -0,0 +1,148 @@ +PEP: 795 +Title: A dedicated ``profilers`` module for organizing python profiling tools +Author: Pablo Galindo , + László Kiss Kollár +Status: Draft +Type: Standards Track +Created: 17-Jul-2025 +Python-Version: 3.15 +Post-History: + +Abstract +======== + +This PEP proposes the creation of a new standard library module named +``profilers`` 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. + +Motivation +========== + +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``. Named +**tachyon**, this tool uses statistical sampling to infer performance characteristics, which +introduces much lower overhead and works better with the modern Python interpreter. It also supports +multiple threads, async functions, 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. + +Rationale +========= + +This 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 ``profilers`` 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 +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 ``profilers`` 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 ``profilers`` module provides a natural home for the continued evolution of +Pytho + +Specification +============= + +New Module Structure +-------------------- + +This PEP introduces a new ``profilers`` 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. + +Additionally the **code** for the ``tachyon`` profiler will be also relocated to +the module as ``profilers.tachyon``. + +Deprecation of ``profile`` +-------------------------- + +The ``profile`` module will be deprecated starting in Python 3.16. + +- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``. +- In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``. +- In Python 3.17: the module will be removed from the standard library. + +Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and +``profilers.sampling`` instead of ``profile.sample``. + +Documentation +============= + +The official Python documentation will reflect the new ``profilers`` module as the canonical +entry point for profiling functionality. It will describe: + +- The distinction between tracing and sampling profilers. +- Guidance on when each is appropriate. + +Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to +the new ``profilers`` equivalents. + +Backwards Compatibility +======================= + +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. + +Security Implications +===================== + +None. + +Rejected Alternatives +===================== + +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. + +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 +and also minimizes the usage of global namespace as requested by the Python Steering council + +Copyright +========= + +This document is placed in the public domain or under the CC0-1.0-Universal +license, whichever is more permissive. diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 4eda52945c2..118d0e98232 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -1,4 +1,4 @@ -PEP: 795 +PEP: 799 Title: A dedicated ``profilers`` package for organizing Python profiling tools Author: Pablo Galindo , László Kiss Kollár , From 342787cdefc1d55711b7508f674c8fe7f1e9ed4d Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 16:52:10 +0100 Subject: [PATCH 09/11] Fix documents --- peps/pep-0795.rst | 148 ---------------------------------------------- peps/pep-0799.rst | 2 +- 2 files changed, 1 insertion(+), 149 deletions(-) delete mode 100644 peps/pep-0795.rst diff --git a/peps/pep-0795.rst b/peps/pep-0795.rst deleted file mode 100644 index 4c6cb092100..00000000000 --- a/peps/pep-0795.rst +++ /dev/null @@ -1,148 +0,0 @@ -PEP: 795 -Title: A dedicated ``profilers`` module for organizing python profiling tools -Author: Pablo Galindo , - László Kiss Kollár -Status: Draft -Type: Standards Track -Created: 17-Jul-2025 -Python-Version: 3.15 -Post-History: - -Abstract -======== - -This PEP proposes the creation of a new standard library module named -``profilers`` 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. - -Motivation -========== - -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``. Named -**tachyon**, this tool uses statistical sampling to infer performance characteristics, which -introduces much lower overhead and works better with the modern Python interpreter. It also supports -multiple threads, async functions, 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. - -Rationale -========= - -This 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 ``profilers`` 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 -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 ``profilers`` 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 ``profilers`` module provides a natural home for the continued evolution of -Pytho - -Specification -============= - -New Module Structure --------------------- - -This PEP introduces a new ``profilers`` 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. - -Additionally the **code** for the ``tachyon`` profiler will be also relocated to -the module as ``profilers.tachyon``. - -Deprecation of ``profile`` --------------------------- - -The ``profile`` module will be deprecated starting in Python 3.16. - -- In Python 3.15: importing ``profile`` emits a ``DeprecationWarning``. -- In Python 3.16: all uses of ``profile`` emit a ``DeprecationWarning``. -- In Python 3.17: the module will be removed from the standard library. - -Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and -``profilers.sampling`` instead of ``profile.sample``. - -Documentation -============= - -The official Python documentation will reflect the new ``profilers`` module as the canonical -entry point for profiling functionality. It will describe: - -- The distinction between tracing and sampling profilers. -- Guidance on when each is appropriate. - -Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to -the new ``profilers`` equivalents. - -Backwards Compatibility -======================= - -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. - -Security Implications -===================== - -None. - -Rejected Alternatives -===================== - -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. - -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 -and also minimizes the usage of global namespace as requested by the Python Steering council - -Copyright -========= - -This document is placed in the public domain or under the CC0-1.0-Universal -license, whichever is more permissive. diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 118d0e98232..052de03e11b 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -117,7 +117,7 @@ Backwards Compatibility ======================= 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. +but this will be made following the :pep:`387` procedure. Security Implications ===================== From 8d77f1d4440fc3f65abb4b37e941e59f0640e83c Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 22 Jul 2025 17:08:26 +0100 Subject: [PATCH 10/11] Fix documents --- peps/pep-0799.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 052de03e11b..0185ad70544 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -101,7 +101,7 @@ The ``profile`` module will be deprecated starting in Python 3.15. From Python 3.15, :mod:`!profilers.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`. The code that as the time of writing this is in :mod:`!profilers.sampling` -module no longer exist and will only exist in the :mod:`profilers` package. +module no longer exist and will only exist in the :mod:`!profilers` package. Documentation ============= From e3ba11702ea9f64400675e99e055aad05ce0e1b2 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Thu, 24 Jul 2025 18:11:57 +0100 Subject: [PATCH 11/11] Update peps/pep-0799.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- .github/CODEOWNERS | 2 -- peps/pep-0799.rst | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e3834098f07..89404412f8e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -677,8 +677,6 @@ peps/pep-0798.rst @JelleZijlstra peps/pep-0799.rst @pablogsal # ... peps/pep-0800.rst @JelleZijlstra -# ... ->>>>>>> c0fc1f6a (Move to 799) peps/pep-0801.rst @warsaw # ... peps/pep-2026.rst @hugovk diff --git a/peps/pep-0799.rst b/peps/pep-0799.rst index 0185ad70544..5fef874dac8 100644 --- a/peps/pep-0799.rst +++ b/peps/pep-0799.rst @@ -100,7 +100,7 @@ The ``profile`` module will be deprecated starting in Python 3.15. From Python 3.15, :mod:`!profilers.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`. -The code that as the time of writing this is in :mod:`!profilers.sampling` +The code that as the time of writing this is in :mod:`!profile.sampling` module no longer exist and will only exist in the :mod:`!profilers` package. Documentation