Align stubs with documented/declared public API surface

Judgement calls, per the principle: will people want to import these
symbols in their code that uses the profiling API?

profiling.tracing
-----------------
- Remove Profile.snapshot_stats(): not in __all__, not in docs. It is
  an internal implementation step called by create_stats(); users call
  create_stats() directly.
- Remove module-level main(): not in __all__, not in docs. It is the
  CLI entry point wired up by the (already-deleted) __main__.py stub.
- Keep dump_stats, runcall, create_stats, print_stats: all explicitly
  documented in the profiling.tracing module reference.
- Keep private _T, _P, _Label aliases: needed internally by the stub
  to express the runcall() overload and stats dict type.

profiling.sampling — collector submodule stubs
-----------------------------------------------
- Remove normalize_location, extract_lineno, filter_internal_frames
  from collector.pyi: implementation helpers used inside collector
  subclasses; not in sampling.__all__, not documented. Users subclass
  Collector with collect() and export() only.
- Remove DEFAULT_LOCATION and THREAD_STATUS_* re-exports from
  collector.pyi: leaked from constants.py; import from
  profiling.sampling.constants if needed.
- Remove get_opcode_mapping from opcode_utils.pyi: internal mapping
  used to build opcode-name look-up tables; not documented, never
  imported by user code.
- Remove re-exports of filter_internal_frames, format_opcode,
  get_opcode_info from gecko_collector.pyi: imported for internal
  use, not part of GeckoCollector's public contract.
- Strip GeckoCollector internal tracking attributes (has_gil_start,
  no_gil_start, on_cpu_start, etc.): 20+ state dicts tracking
  GIL/CPU marker transitions; purely implementation detail. Users
  call __init__ → collect → export.
- Remove FileStats, TreeNode, get_python_path_info,
  extract_module_name from heatmap_collector.pyi: internal data
  structures and path helpers for the HTML generation pipeline; not
  in sampling.__all__, not documented.
- Strip HeatmapCollector internal state counters (line_samples,
  file_samples, call_graph, etc.): implementation detail of the
  line-level sample accumulation.
- Remove re-exports of extract_lineno, normalize_location,
  format_opcode, get_opcode_info from heatmap_collector.pyi: same
  pattern — imported for internal use only.
- Remove re-exports of extract_lineno, get_opcode_mapping,
  StringTable from stack_collector.pyi.
- Strip CollapsedStackCollector.stack_counter and
  FlamegraphCollector internal state (thread_status_counts,
  per_thread_stats, etc.): sample accumulation internals.
- Strip DiffFlamegraphCollector.baseline_binary_path attribute:
  constructor parameter, not a user-facing attribute.
- Remove extract_lineno, MICROSECONDS_PER_SECOND, PROFILING_MODE_CPU
  re-exports from pstats_collector.pyi.
- Strip PstatsCollector internal state (result, stats, callers,
  skip_idle attributes): implementation detail of sample aggregation.
- Remove GeckoCollector, PstatsCollector, CollapsedStackCollector,
  FlamegraphCollector re-exports from binary_reader.pyi: imported
  internally by binary_reader.py, not part of BinaryReader's API.

profiling.sampling — sample and cli modules
-------------------------------------------
- Strip sample.pyi of all re-exports (BinaryCollector, Collector,
  all five PROFILING_MODE_* constants, GeckoCollector,
  HeatmapCollector, LiveStatsCollector, PstatsCollector,
  CollapsedStackCollector, FlamegraphCollector): sample.py imports
  these for internal use; they are not part of sample's public
  interface and are already accessible from their own modules.
- Remove unwinder: Incomplete from SampleProfiler: internal C
  extension handle, not user-accessible.
- Strip cli.pyi to main() only: cli.py is the CLI implementation;
  all the symbols it re-exported (ChildProcessMonitor, BinaryCollector,
  BinaryReader, 6 SORT_MODE constants) belong to their own modules.
- Delete _child_monitor.pyi: private module (_-prefixed); previously
  kept because cli.pyi re-exported ChildProcessMonitor, but now that
  cli.pyi is stripped there is no public re-export, and users have
  no reason to import from profiling.sampling._child_monitor directly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: johnslavik

stdlib/profiling/sampling/_child_monitor.pyi

@@ -5,9 +5,6 @@ from typing import Any
 from typing_extensions import Self
 
 from .collector import Collector as Collector
-from .gecko_collector import GeckoCollector as GeckoCollector
-from .pstats_collector import PstatsCollector as PstatsCollector
-from .stack_collector import CollapsedStackCollector as CollapsedStackCollector, FlamegraphCollector as FlamegraphCollector
 
 class BinaryReader:
     filename: str

stdlib/profiling/sampling/binary_reader.pyi

@@ -1,18 +1 @@
-from ._child_monitor import ChildProcessMonitor as ChildProcessMonitor
-from .binary_collector import BinaryCollector as BinaryCollector
-from .binary_reader import BinaryReader as BinaryReader
-from .constants import (
-    PROFILING_MODE_ALL as PROFILING_MODE_ALL,
-    PROFILING_MODE_CPU as PROFILING_MODE_CPU,
-    PROFILING_MODE_EXCEPTION as PROFILING_MODE_EXCEPTION,
-    PROFILING_MODE_GIL as PROFILING_MODE_GIL,
-    PROFILING_MODE_WALL as PROFILING_MODE_WALL,
-    SORT_MODE_CUMTIME as SORT_MODE_CUMTIME,
-    SORT_MODE_CUMUL_PCT as SORT_MODE_CUMUL_PCT,
-    SORT_MODE_NSAMPLES as SORT_MODE_NSAMPLES,
-    SORT_MODE_NSAMPLES_CUMUL as SORT_MODE_NSAMPLES_CUMUL,
-    SORT_MODE_SAMPLE_PCT as SORT_MODE_SAMPLE_PCT,
-    SORT_MODE_TOTTIME as SORT_MODE_TOTTIME,
-)
-
 def main() -> None: ...

stdlib/profiling/sampling/cli.pyi

@@ -3,19 +3,6 @@ from _typeshed import StrOrBytesPath
 from abc import ABC, abstractmethod
 from typing import Any
 
-from .constants import (
-    DEFAULT_LOCATION as DEFAULT_LOCATION,
-    THREAD_STATUS_GIL_REQUESTED as THREAD_STATUS_GIL_REQUESTED,
-    THREAD_STATUS_HAS_EXCEPTION as THREAD_STATUS_HAS_EXCEPTION,
-    THREAD_STATUS_HAS_GIL as THREAD_STATUS_HAS_GIL,
-    THREAD_STATUS_ON_CPU as THREAD_STATUS_ON_CPU,
-    THREAD_STATUS_UNKNOWN as THREAD_STATUS_UNKNOWN,
-)
-
-def normalize_location(location: tuple[int, int, int, int] | None) -> tuple[int, int, int, int]: ...
-def extract_lineno(location: tuple[int, int, int, int] | None) -> int: ...
-def filter_internal_frames(frames: list[Any]) -> list[Any]: ...
-
 class Collector(ABC, metaclass=abc.ABCMeta):
     @abstractmethod
     def collect(self, stack_frames: Any, timestamps_us: list[int] | None = None) -> None: ...

stdlib/profiling/sampling/collector.pyi

@@ -1,32 +1,8 @@
 from typing import Any
 
-from .collector import Collector as Collector, filter_internal_frames as filter_internal_frames
-from .opcode_utils import format_opcode as format_opcode, get_opcode_info as get_opcode_info
+from .collector import Collector as Collector
 
 class GeckoCollector(Collector):
-    sample_interval_usec: int
-    skip_idle: bool
-    opcodes_enabled: bool
-    start_time: float
-    global_strings: list[str]
-    global_string_map: dict[str, int]
-    threads: dict[int, Any]
-    libs: list[Any]
-    sample_count: int
-    last_sample_time: int
-    interval: float
-    has_gil_start: dict[int, float]
-    no_gil_start: dict[int, float]
-    on_cpu_start: dict[int, float]
-    off_cpu_start: dict[int, float]
-    python_code_start: dict[int, float]
-    native_code_start: dict[int, float]
-    gil_wait_start: dict[int, float]
-    exception_start: dict[int, float]
-    no_exception_start: dict[int, float]
-    gc_start_per_thread: dict[int, float]
-    initialized_threads: set[int]
-    opcode_state: dict[Any, Any]
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False, opcodes: bool = False) -> None: ...
     def collect(self, stack_frames: Any, timestamps_us: list[int] | None = None) -> None: ...
     def export(self, filename: str) -> None: ...

stdlib/profiling/sampling/gecko_collector.pyi

@@ -1,49 +1,9 @@
 from _typeshed import StrOrBytesPath
-from collections import Counter
-from dataclasses import dataclass
 from typing import Any
 
-from .collector import extract_lineno as extract_lineno, normalize_location as normalize_location
-from .opcode_utils import format_opcode as format_opcode, get_opcode_info as get_opcode_info
 from .stack_collector import StackTraceCollector as StackTraceCollector
 
-@dataclass
-class FileStats:
-    filename: str
-    module_name: str
-    module_type: str
-    total_samples: int
-    total_self_samples: int
-    num_lines: int
-    max_samples: int
-    max_self_samples: int
-    percentage: float = ...
-
-@dataclass
-class TreeNode:
-    files: list[FileStats] = ...
-    samples: int = ...
-    count: int = ...
-    children: dict[str, TreeNode] = ...
-
-def get_python_path_info() -> dict[str, Any]: ...
-def extract_module_name(filename: str, path_info: dict[str, Any]) -> str: ...
-
 class HeatmapCollector(StackTraceCollector):
-    FILE_INDEX_FORMAT: str
-    line_samples: Counter[Any]
-    file_samples: dict[str, Counter[int]]
-    line_self_samples: Counter[Any]
-    file_self_samples: dict[str, Counter[int]]
-    call_graph: dict[Any, set[Any]]
-    callers_graph: dict[Any, set[Any]]
-    function_definitions: dict[Any, Any]
-    line_to_function: dict[Any, Any]
-    edge_samples: Counter[Any]
-    line_opcodes: dict[Any, dict[Any, Any]]
-    stats: dict[str, Any]
-    opcodes_enabled: bool
-    file_index: dict[str, str]
     def __init__(self, *args: Any, **kwargs: Any) -> None: ...
     def set_stats(
         self,

stdlib/profiling/sampling/heatmap_collector.pyi

@@ -1,3 +1,2 @@
 def get_opcode_info(opcode_num: int) -> dict[str, str | bool]: ...
 def format_opcode(opcode_num: int) -> str: ...
-def get_opcode_mapping() -> dict[str, dict[int, str] | dict[int, int]]: ...

stdlib/profiling/sampling/opcode_utils.pyi

@@ -1,15 +1,9 @@
 from _typeshed import StrOrBytesPath
 from typing import Any
 
-from .collector import Collector as Collector, extract_lineno as extract_lineno
-from .constants import MICROSECONDS_PER_SECOND as MICROSECONDS_PER_SECOND, PROFILING_MODE_CPU as PROFILING_MODE_CPU
+from .collector import Collector as Collector
 
 class PstatsCollector(Collector):
-    result: dict[Any, Any]
-    stats: dict[Any, Any]
-    sample_interval_usec: int
-    callers: dict[Any, Any]
-    skip_idle: bool
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False) -> None: ...
     def collect(self, stack_frames: Any, timestamps_us: list[int] | None = None) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...

stdlib/profiling/sampling/pstats_collector.pyi

@@ -1,20 +1,6 @@
-from _typeshed import Incomplete
 from collections import deque
 
-from .binary_collector import BinaryCollector as BinaryCollector
 from .collector import Collector as Collector
-from .constants import (
-    PROFILING_MODE_ALL as PROFILING_MODE_ALL,
-    PROFILING_MODE_CPU as PROFILING_MODE_CPU,
-    PROFILING_MODE_EXCEPTION as PROFILING_MODE_EXCEPTION,
-    PROFILING_MODE_GIL as PROFILING_MODE_GIL,
-    PROFILING_MODE_WALL as PROFILING_MODE_WALL,
-)
-from .gecko_collector import GeckoCollector as GeckoCollector
-from .heatmap_collector import HeatmapCollector as HeatmapCollector
-from .live_collector import LiveStatsCollector as LiveStatsCollector
-from .pstats_collector import PstatsCollector as PstatsCollector
-from .stack_collector import CollapsedStackCollector as CollapsedStackCollector, FlamegraphCollector as FlamegraphCollector
 
 class SampleProfiler:
     pid: int
@@ -23,7 +9,6 @@ class SampleProfiler:
     mode: int
     collect_stats: bool
     blocking: bool
-    unwinder: Incomplete
     sample_intervals: deque[float]
     total_samples: int
     realtime_stats: bool

stdlib/profiling/sampling/sample.pyi

@@ -1,11 +1,8 @@
 import abc
 from _typeshed import StrOrBytesPath
-from collections import Counter
 from typing import Any
 
-from .collector import Collector as Collector, extract_lineno as extract_lineno
-from .opcode_utils import get_opcode_mapping as get_opcode_mapping
-from .string_table import StringTable as StringTable
+from .collector import Collector as Collector
 
 class StackTraceCollector(Collector, metaclass=abc.ABCMeta):
     sample_interval_usec: int
@@ -15,16 +12,11 @@ class StackTraceCollector(Collector, metaclass=abc.ABCMeta):
     def process_frames(self, frames: list[Any], thread_id: int, weight: int = 1) -> None: ...
 
 class CollapsedStackCollector(StackTraceCollector):
-    stack_counter: Counter[str]
     def __init__(self, *args: Any, **kwargs: Any) -> None: ...
     def process_frames(self, frames: list[Any], thread_id: int, weight: int = 1) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...
 
 class FlamegraphCollector(StackTraceCollector):
-    stats: dict[str, Any]
-    thread_status_counts: dict[str, int]
-    samples_with_gc_frames: int
-    per_thread_stats: dict[int, Any]
     def __init__(self, *args: Any, **kwargs: Any) -> None: ...
     def collect(self, stack_frames: Any, timestamps_us: list[int] | None = None) -> None: ...
     def set_stats(
@@ -40,5 +32,4 @@ class FlamegraphCollector(StackTraceCollector):
     def process_frames(self, frames: list[Any], thread_id: int, weight: int = 1) -> None: ...
 
 class DiffFlamegraphCollector(FlamegraphCollector):
-    baseline_binary_path: str
     def __init__(self, sample_interval_usec: int, *, baseline_binary_path: str, skip_idle: bool = False) -> None: ...