gh-138122: Refactor the CLI of profile.sampling into subcommands

Author: pablogsal

Doc/library/profile.rst

@@ -353,74 +353,9 @@ The statistical profiler produces output similar to deterministic profilers but
 .. module:: profiling.sampling
    :synopsis: Python statistical profiler.
 
-This section documents the programmatic interface for the :mod:`!profiling.sampling` module.
 For command-line usage, see :ref:`sampling-profiler-cli`. For conceptual information
 about statistical profiling, see :ref:`statistical-profiling`
 
-.. function:: sample(pid, *, sort=2, sample_interval_usec=100, duration_sec=10, filename=None, all_threads=False, limit=None, show_summary=True, output_format="pstats", realtime_stats=False, native=False, gc=True)
-
-   Sample a Python process and generate profiling data.
-
-   This is the main entry point for statistical profiling. It creates a
-   :class:`SampleProfiler`, collects stack traces from the target process, and
-   outputs the results in the specified format.
-
-   :param int pid: Process ID of the target Python process
-   :param int sort: Sort order for pstats output (default: 2 for cumulative time)
-   :param int sample_interval_usec: Sampling interval in microseconds (default: 100)
-   :param int duration_sec: Duration to sample in seconds (default: 10)
-   :param str filename: Output filename (None for stdout/default naming)
-   :param bool all_threads: Whether to sample all threads (default: False)
-   :param int limit: Maximum number of functions to display (default: None)
-   :param bool show_summary: Whether to show summary statistics (default: True)
-   :param str output_format: Output format - 'pstats' or 'collapsed' (default: 'pstats')
-   :param bool realtime_stats: Whether to display real-time statistics (default: False)
-   :param bool native: Whether to include ``<native>`` frames (default: False)
-   :param bool gc: Whether to include ``<GC>`` frames (default: True)
-
-   :raises ValueError: If output_format is not 'pstats' or 'collapsed'
-
-   Examples::
-
-       # Basic usage - profile process 1234 for 10 seconds
-       import profiling.sampling
-       profiling.sampling.sample(1234)
-
-       # Profile with custom settings
-       profiling.sampling.sample(1234, duration_sec=30, sample_interval_usec=50, all_threads=True)
-
-       # Generate collapsed stack traces for flamegraph.pl
-       profiling.sampling.sample(1234, output_format='collapsed', filename='profile.collapsed')
-
-.. class:: SampleProfiler(pid, sample_interval_usec, all_threads)
-
-   Low-level API for the statistical profiler.
-
-   This profiler uses periodic stack sampling to collect performance data
-   from running Python processes with minimal overhead. It can attach to
-   any Python process by PID and collect stack traces at regular intervals.
-
-   :param int pid: Process ID of the target Python process
-   :param int sample_interval_usec: Sampling interval in microseconds
-   :param bool all_threads: Whether to sample all threads or just the main thread
-
-   .. method:: sample(collector, duration_sec=10)
-
-      Sample the target process for the specified duration.
-
-      Collects stack traces from the target process at regular intervals
-      and passes them to the provided collector for processing.
-
-      :param collector: Object that implements ``collect()`` method to process stack traces
-      :param int duration_sec: Duration to sample in seconds (default: 10)
-
-      The method tracks sampling statistics and can display real-time
-      information if realtime_stats is enabled.
-
-.. seealso::
-
-   :ref:`sampling-profiler-cli`
-      Command-line interface documentation for the statistical profiler.
 
 Deterministic Profiler Command Line Interface
 =============================================

Lib/profiling/sampling/__main__.py

@@ -45,7 +45,7 @@
 system restrictions or missing privileges.
 """
 
-from .sample import main
+from .cli import main
 
 def handle_permission_error():
     """Handle PermissionError by displaying appropriate error message."""