Add typed stubs for the profiling stdlib package

- Complete type annotations for profiling.tracing and profiling.sampling
- Replace all Incomplete usages with proper types throughout
- Add return types, parameter types, and attribute types to all stubs
- Only exception: unwinder: Incomplete in sample.pyi (_remote_debugging C ext)

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

Author: johnslavik

stdlib/VERSIONS

@@ -107,7 +107,7 @@ binhex: 3.0-3.10
 bisect: 3.0-
 builtins: 3.0-
 bz2: 3.0-
-cProfile: 3.0-
+cProfile: 3.0-3.17
 calendar: 3.0-
 cgi: 3.0-3.12
 cgitb: 3.0-3.12
@@ -245,7 +245,8 @@ poplib: 3.0-
 posix: 3.0-
 posixpath: 3.0-
 pprint: 3.0-
-profile: 3.0-
+profile: 3.0-3.17
+profiling: 3.15-
 pstats: 3.0-
 pty: 3.0-
 pwd: 3.0-

stdlib/profiling/__init__.pyi

@@ -0,0 +1,8 @@
+from .collector import Collector as Collector
+from .gecko_collector import GeckoCollector as GeckoCollector
+from .heatmap_collector import HeatmapCollector as HeatmapCollector
+from .pstats_collector import PstatsCollector as PstatsCollector
+from .stack_collector import CollapsedStackCollector as CollapsedStackCollector
+from .string_table import StringTable as StringTable
+
+__all__ = ["Collector", "PstatsCollector", "CollapsedStackCollector", "HeatmapCollector", "GeckoCollector", "StringTable"]

stdlib/profiling/sampling/__init__.pyi

@@ -0,0 +1,13 @@
+from .cli import main as main
+from .errors import (
+    SamplingModuleNotFoundError as SamplingModuleNotFoundError,
+    SamplingScriptNotFoundError as SamplingScriptNotFoundError,
+    SamplingUnknownProcessError as SamplingUnknownProcessError,
+)
+
+MACOS_PERMISSION_ERROR: str
+LINUX_PERMISSION_ERROR: str
+WINDOWS_PERMISSION_ERROR: str
+GENERIC_PERMISSION_ERROR: str
+
+def handle_permission_error() -> None: ...

stdlib/profiling/sampling/__main__.pyi

@@ -0,0 +1,19 @@
+import types
+from typing import Any
+from typing_extensions import Self
+
+def get_child_pids(pid: int, recursive: bool = True) -> list[int]: ...
+def is_python_process(pid: int) -> bool: ...
+
+class ChildProcessMonitor:
+    parent_pid: int
+    cli_args: list[str]
+    output_pattern: str
+    def __init__(self, pid: int, cli_args: list[str], output_pattern: str) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+    ) -> None: ...
+    @property
+    def spawned_profilers(self) -> list[Any]: ...
+    def wait_for_profilers(self, timeout: float = ...) -> None: ...

stdlib/profiling/sampling/_child_monitor.pyi

@@ -0,0 +1 @@
+def get_combined_css(component: str) -> str: ...

stdlib/profiling/sampling/_css_utils.pyi

@@ -0,0 +1 @@
+def fmt(value: float, decimals: int = 1) -> str: ...

stdlib/profiling/sampling/_format_utils.pyi

@@ -0,0 +1,8 @@
+from typing import Never
+
+class CoordinatorError(Exception): ...
+class ArgumentError(CoordinatorError): ...
+class SyncError(CoordinatorError): ...
+class TargetError(CoordinatorError): ...
+
+def main() -> Never: ...

stdlib/profiling/sampling/_sync_coordinator.pyi

@@ -0,0 +1,25 @@
+import types
+from _typeshed import StrOrBytesPath
+from typing import Any
+from typing_extensions import Self
+
+from .collector import Collector as Collector
+
+COMPRESSION_NONE: int
+COMPRESSION_ZSTD: int
+
+class BinaryCollector(Collector):
+    filename: str
+    sample_interval_usec: int
+    skip_idle: bool
+    def __init__(self, filename: str, sample_interval_usec: int, *, skip_idle: bool = False, compression: str = "auto") -> None: ...
+    def collect(self, stack_frames: Any, timestamp_us: int | None = None) -> None: ...
+    def collect_failed_sample(self) -> None: ...
+    def export(self, filename: StrOrBytesPath | None = None) -> None: ...
+    @property
+    def total_samples(self) -> int: ...
+    def get_stats(self) -> dict[str, Any]: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+    ) -> None: ...

stdlib/profiling/sampling/binary_collector.pyi

@@ -0,0 +1,31 @@
+import types
+from _typeshed import StrOrBytesPath
+from collections.abc import Callable
+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
+    def __init__(self, filename: str) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+    ) -> None: ...
+    def get_info(self) -> dict[str, Any]: ...
+    def replay_samples(self, collector: Collector, progress_callback: Callable[[int, int], None] | None = None) -> int: ...
+    @property
+    def sample_count(self) -> int: ...
+    def get_stats(self) -> dict[str, Any]: ...
+
+def convert_binary_to_format(
+    input_file: StrOrBytesPath,
+    output_file: StrOrBytesPath,
+    output_format: str,
+    sample_interval_usec: int | None = None,
+    progress_callback: Callable[[int, int], None] | None = None,
+) -> None: ...