Refine remote debugging profiling stubs

Author: JelleZijlstra

stdlib/_remote_debugging.pyi

@@ -3,9 +3,8 @@ from collections.abc import Callable, Sequence
 from typing import Final, TypeAlias, final
 from typing_extensions import Self
 
-_Location: TypeAlias = int | LocationInfo | None
+_Location: TypeAlias = LocationInfo | None
 _Frame: TypeAlias = tuple[str, _Location, str, int | None] | FrameInfo
-_StackFrames: TypeAlias = Sequence[InterpreterInfo]
 _Stats: TypeAlias = dict[str, int | float]
 
 PROCESS_VM_READV_SUPPORTED: Final[int]
@@ -149,11 +148,12 @@ class GCMonitor:
 
 @final
 class BinaryWriter:
-    total_samples: int
     def __init__(
         self, filename: StrOrBytesPath, sample_interval_us: int, start_time_us: int, *, compression: int = 0
     ) -> None: ...
-    def write_sample(self, stack_frames: _StackFrames, timestamp_us: int) -> None: ...
+    @property
+    def total_samples(self) -> int: ...
+    def write_sample(self, stack_frames: Sequence[InterpreterInfo], timestamp_us: int) -> None: ...
     def finalize(self) -> None: ...
     def close(self) -> None: ...
     def __enter__(self) -> Self: ...
@@ -162,9 +162,11 @@ class BinaryWriter:
 
 @final
 class BinaryReader:
-    sample_count: int
-    sample_interval_us: int
     def __init__(self, filename: StrOrBytesPath) -> None: ...
+    @property
+    def sample_count(self) -> int: ...
+    @property
+    def sample_interval_us(self) -> int: ...
     def replay(self, collector: object, progress_callback: Callable[[int, int], object] | None = None) -> int: ...
     def get_info(self) -> dict[str, object]: ...
     def get_stats(self) -> _Stats: ...

stdlib/profiling/sampling/collector.pyi

@@ -5,10 +5,9 @@ from typing import TypeAlias
 
 from _remote_debugging import AwaitedInfo, FrameInfo, InterpreterInfo, LocationInfo
 
-_Location: TypeAlias = int | tuple[int, int, int, int] | LocationInfo | None
+_Location: TypeAlias = tuple[int, int, int, int] | LocationInfo | None
 _Frame: TypeAlias = FrameInfo | tuple[str, _Location, str, int | None]
 _Timestamps: TypeAlias = Sequence[int] | None
-_StackFrames: TypeAlias = Sequence[InterpreterInfo] | Sequence[AwaitedInfo]
 
 def normalize_location(location: _Location) -> tuple[int, int, int, int]: ...
 def extract_lineno(location: _Location) -> int: ...
@@ -17,7 +16,9 @@ def iter_async_frames(awaited_info_list: Sequence[AwaitedInfo]) -> object: ...
 
 class Collector(ABC):
     @abstractmethod
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def collect_failed_sample(self) -> None: ...
     @abstractmethod
     def export(self, filename: StrOrBytesPath) -> None: ...

stdlib/profiling/sampling/gecko_collector.pyi

@@ -1,8 +1,13 @@
 from _typeshed import StrOrBytesPath
+from collections.abc import Sequence
 
-from .collector import Collector, _StackFrames, _Timestamps
+from _remote_debugging import AwaitedInfo, InterpreterInfo
+
+from .collector import Collector, _Timestamps
 
 class GeckoCollector(Collector):
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False, opcodes: bool = False) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...

stdlib/profiling/sampling/heatmap_collector.pyi

@@ -1,12 +1,16 @@
 from _typeshed import StrOrBytesPath
 from collections.abc import Sequence
 
-from .collector import Collector, _Frame, _StackFrames, _Timestamps
+from _remote_debugging import AwaitedInfo, InterpreterInfo
+
+from .collector import Collector, _Frame, _Timestamps
 
 class HeatmapCollector(Collector):
     FILE_INDEX_FORMAT: str
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def export(self, output_path: StrOrBytesPath) -> None: ...
     def process_frames(self, frames: Sequence[_Frame], thread_id: int, weight: int = 1) -> None: ...
     def set_stats(

stdlib/profiling/sampling/jsonl_collector.pyi

@@ -1,11 +1,15 @@
 from _typeshed import StrOrBytesPath
 from collections.abc import Sequence
 
-from .collector import _Frame, _StackFrames, _Timestamps
+from _remote_debugging import AwaitedInfo, InterpreterInfo
+
+from .collector import _Frame, _Timestamps
 from .stack_collector import StackTraceCollector
 
 class JsonlCollector(StackTraceCollector):
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False, mode: int | None = None) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...
     def process_frames(self, frames: Sequence[_Frame], _thread_id: int, weight: int = 1) -> None: ...

stdlib/profiling/sampling/pstats_collector.pyi

@@ -1,10 +1,15 @@
 from _typeshed import StrOrBytesPath
+from collections.abc import Sequence
 
-from .collector import Collector, _StackFrames, _Timestamps
+from _remote_debugging import AwaitedInfo, InterpreterInfo
+
+from .collector import Collector, _Timestamps
 
 class PstatsCollector(Collector):
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...
     def create_stats(self) -> None: ...
     def print_stats(

stdlib/profiling/sampling/stack_collector.pyi

@@ -2,11 +2,15 @@ from _typeshed import StrOrBytesPath
 from abc import ABCMeta
 from collections.abc import Sequence
 
-from .collector import Collector, _Frame, _StackFrames, _Timestamps
+from _remote_debugging import AwaitedInfo, InterpreterInfo
+
+from .collector import Collector, _Frame, _Timestamps
 
 class StackTraceCollector(Collector, metaclass=ABCMeta):
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def process_frames(self, frames: Sequence[_Frame], thread_id: int, weight: int = 1) -> None: ...
 
 class CollapsedStackCollector(StackTraceCollector):
@@ -16,7 +20,9 @@ class CollapsedStackCollector(StackTraceCollector):
 
 class FlamegraphCollector(StackTraceCollector):
     def __init__(self, sample_interval_usec: int, *, skip_idle: bool = False) -> None: ...
-    def collect(self, stack_frames: _StackFrames, timestamps_us: _Timestamps = None) -> None: ...
+    def collect(
+        self, stack_frames: Sequence[InterpreterInfo] | Sequence[AwaitedInfo], timestamps_us: _Timestamps = None
+    ) -> None: ...
     def set_stats(
         self,
         sample_interval_usec: int,