PEP 799: Address discussion feedback and add link to discussion thread (#4520)

pablogsal · web-flow · commit a9d6759e4920 · 2025-08-03T00:29:52.000+01:00
diff --git 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 <pablogsal@python.org>,
-        László Kiss Kollár <kiss.kollar.laszlo@gmail.com>,
-Discussions-To: Pending
+        László Kiss Kollár <kiss.kollar.laszlo@gmail.com>
+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,42 +54,43 @@ 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.
 
 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.
 
 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
 =============
 
 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
