Strip live_collector to its user-facing API surface

Guiding principle: stubs should only contain what users of the profiling
API would actually import or tab-complete. The live_collector subpackage
is primarily a TUI display component; its internal widget/display
architecture is not part of any user-facing API.

Judgement calls — removed:

- live_collector/widgets.pyi: deleted — Widget, ProgressBarWidget,
  HeaderWidget, TableWidget, FooterWidget, HelpWidget, OpcodePanel are
  internal TUI rendering components; nobody writing code against the
  profiling API would import them
- live_collector/trend_tracker.pyi: deleted — TrendTracker is an internal
  widget state helper used only inside the TUI rendering loop
- live_collector/constants.pyi: deleted — TUI layout dimensions and curses
  color pair IDs (COLOR_PAIR_*, WIDTH_THRESHOLD_*, MIN_TERMINAL_*, etc.)
  have no meaning outside the live_collector implementation
- live_collector/display.pyi: removed CursesDisplay (internal curses
  wrapper) and MockDisplay (test helper only referenced in tests, not
  production API); kept DisplayInterface because it is the type of the
  display= parameter on LiveStatsCollector.__init__
- live_collector/collector.pyi: removed all constant imports (COLOR_PAIR_*,
  MICROSECONDS_PER_SECOND, MIN_TERMINAL_*, etc.) that were leaked
  implementation imports not used in any type annotations; removed widget
  imports (HeaderWidget, TableWidget, etc.) and TrendTracker; removed
  ThreadData dataclass (internal per-sample accumulator); stripped
  LiveStatsCollector of TUI-state attributes (stdscr, selected_row,
  scroll_offset, paused, show_help, filter_*, view_mode,
  current_thread_index, per_thread_data, *_widget, display_update_interval_sec,
  thread_status_counts, gc_frame_samples, opcode_stats) and internal
  methods (simplify_path, process_frames, init_curses, cleanup_curses)
- live_collector/__init__.pyi: stripped __all__ and re-exports to just
  LiveStatsCollector and DisplayInterface

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

Author: johnslavik

stdlib/profiling/sampling/live_collector/__init__.pyi

@@ -1,23 +1,4 @@
 from .collector import LiveStatsCollector as LiveStatsCollector
-from .display import CursesDisplay as CursesDisplay, DisplayInterface as DisplayInterface, MockDisplay as MockDisplay
-from .widgets import (
-    FooterWidget as FooterWidget,
-    HeaderWidget as HeaderWidget,
-    HelpWidget as HelpWidget,
-    ProgressBarWidget as ProgressBarWidget,
-    TableWidget as TableWidget,
-    Widget as Widget,
-)
+from .display import DisplayInterface as DisplayInterface
 
-__all__ = [
-    "LiveStatsCollector",
-    "DisplayInterface",
-    "CursesDisplay",
-    "MockDisplay",
-    "Widget",
-    "ProgressBarWidget",
-    "HeaderWidget",
-    "TableWidget",
-    "FooterWidget",
-    "HelpWidget",
-]
+__all__ = ["LiveStatsCollector", "DisplayInterface"]

stdlib/profiling/sampling/live_collector/collector.pyi

@@ -1,66 +1,8 @@
-import curses
 from _typeshed import StrOrBytesPath
-from dataclasses import dataclass
 from typing import Any
 
-from ..collector import Collector as Collector, extract_lineno as extract_lineno
-from ..constants import (
-    PROFILING_MODE_CPU as PROFILING_MODE_CPU,
-    PROFILING_MODE_GIL as PROFILING_MODE_GIL,
-    PROFILING_MODE_WALL as PROFILING_MODE_WALL,
-    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,
-)
-from .constants import (
-    COLOR_PAIR_CYAN as COLOR_PAIR_CYAN,
-    COLOR_PAIR_FILE as COLOR_PAIR_FILE,
-    COLOR_PAIR_FUNC as COLOR_PAIR_FUNC,
-    COLOR_PAIR_GREEN as COLOR_PAIR_GREEN,
-    COLOR_PAIR_HEADER_BG as COLOR_PAIR_HEADER_BG,
-    COLOR_PAIR_MAGENTA as COLOR_PAIR_MAGENTA,
-    COLOR_PAIR_RED as COLOR_PAIR_RED,
-    COLOR_PAIR_SAMPLES as COLOR_PAIR_SAMPLES,
-    COLOR_PAIR_SORTED_HEADER as COLOR_PAIR_SORTED_HEADER,
-    COLOR_PAIR_YELLOW as COLOR_PAIR_YELLOW,
-    DEFAULT_DISPLAY_LIMIT as DEFAULT_DISPLAY_LIMIT,
-    DEFAULT_SORT_BY as DEFAULT_SORT_BY,
-    DISPLAY_UPDATE_INTERVAL_SEC as DISPLAY_UPDATE_INTERVAL_SEC,
-    FINISHED_BANNER_EXTRA_LINES as FINISHED_BANNER_EXTRA_LINES,
-    FOOTER_LINES as FOOTER_LINES,
-    HEADER_LINES as HEADER_LINES,
-    MICROSECONDS_PER_SECOND as MICROSECONDS_PER_SECOND,
-    MIN_TERMINAL_HEIGHT as MIN_TERMINAL_HEIGHT,
-    MIN_TERMINAL_WIDTH as MIN_TERMINAL_WIDTH,
-    SAFETY_MARGIN as SAFETY_MARGIN,
-)
-from .display import CursesDisplay as CursesDisplay, DisplayInterface as DisplayInterface
-from .trend_tracker import TrendTracker as TrendTracker
-from .widgets import (
-    FooterWidget as FooterWidget,
-    HeaderWidget as HeaderWidget,
-    HelpWidget as HelpWidget,
-    OpcodePanel as OpcodePanel,
-    TableWidget as TableWidget,
-)
-
-@dataclass
-class ThreadData:
-    thread_id: int
-    result: dict[Any, Any] = ...
-    has_gil: int = ...
-    on_cpu: int = ...
-    gil_requested: int = ...
-    unknown: int = ...
-    has_exception: int = ...
-    total: int = ...
-    sample_count: int = ...
-    gc_frame_samples: int = ...
-    opcode_stats: dict[Any, Any] = ...
-    def increment_status_flag(self, status_flags: int) -> None: ...
-    def as_status_dict(self) -> dict[str, int]: ...
+from ..collector import Collector as Collector
+from .display import DisplayInterface as DisplayInterface
 
 class LiveStatsCollector(Collector):
     result: dict[Any, Any]
@@ -70,40 +12,19 @@ class LiveStatsCollector(Collector):
     sort_by: str
     limit: int
     total_samples: int
+    successful_samples: int
+    failed_samples: int
     start_time: float | None
-    stdscr: curses.window | None
-    display: DisplayInterface | None
     running: bool
+    finished: bool
+    finish_timestamp: float | None
+    finish_wall_time: float | None
     pid: int | None
     mode: int | None
     async_aware: str | bool | None
     max_sample_rate: int
-    successful_samples: int
-    failed_samples: int
-    display_update_interval_sec: float
-    thread_status_counts: dict[str, int]
-    gc_frame_samples: int
-    opcode_stats: dict[Any, Any]
-    show_opcodes: bool
-    selected_row: int
-    scroll_offset: int
-    paused: bool
-    show_help: bool
-    filter_pattern: str | None
-    filter_input_mode: bool
-    filter_input_buffer: str
-    finished: bool
-    finish_timestamp: float | None
-    finish_wall_time: float | None
+    display: DisplayInterface | None
     thread_ids: list[int]
-    view_mode: str
-    current_thread_index: int
-    per_thread_data: dict[int, ThreadData]
-    header_widget: HeaderWidget | None
-    table_widget: TableWidget | None
-    footer_widget: FooterWidget | None
-    help_widget: HelpWidget | None
-    opcode_panel: OpcodePanel | None
     def __init__(
         self,
         sample_interval_usec: int,
@@ -121,13 +42,9 @@ class LiveStatsCollector(Collector):
     def elapsed_time(self) -> float: ...
     @property
     def current_time_display(self) -> str: ...
-    def simplify_path(self, filepath: str) -> str: ...
-    def process_frames(self, frames: Any, thread_id: int | None = None) -> None: ...
     def collect_failed_sample(self) -> None: ...
     def collect(self, stack_frames: Any, timestamp_us: int | None = None) -> None: ...
     def build_stats_list(self) -> list[Any]: ...
     def reset_stats(self) -> None: ...
     def mark_finished(self) -> None: ...
-    def init_curses(self, stdscr: curses.window) -> None: ...
-    def cleanup_curses(self) -> None: ...
     def export(self, filename: StrOrBytesPath) -> None: ...

stdlib/profiling/sampling/live_collector/constants.pyi

@@ -1,5 +1,4 @@
 import abc
-import curses
 from abc import ABC, abstractmethod
 
 class DisplayInterface(ABC, metaclass=abc.ABCMeta):
@@ -25,47 +24,3 @@ class DisplayInterface(ABC, metaclass=abc.ABCMeta):
     def get_color_pair(self, pair_id: int) -> int: ...
     @abstractmethod
     def get_attr(self, name: str) -> int: ...
-
-class CursesDisplay(DisplayInterface):
-    stdscr: curses.window
-    def __init__(self, stdscr: curses.window) -> None: ...
-    def get_dimensions(self) -> tuple[int, int]: ...
-    def clear(self) -> None: ...
-    def refresh(self) -> None: ...
-    def redraw(self) -> None: ...
-    def add_str(self, line: int, col: int, text: str, attr: int = 0) -> None: ...
-    def get_input(self) -> int: ...
-    def set_nodelay(self, flag: bool) -> None: ...
-    def has_colors(self) -> bool: ...
-    def init_color_pair(self, pair_id: int, fg: int, bg: int) -> None: ...
-    def get_color_pair(self, pair_id: int) -> int: ...
-    def get_attr(self, name: str) -> int: ...
-
-class MockDisplay(DisplayInterface):
-    height: int
-    width: int
-    buffer: dict[tuple[int, int], tuple[str, int]]
-    cleared: bool
-    refreshed: bool
-    redrawn: bool
-    input_queue: list[int]
-    nodelay_flag: bool
-    colors_supported: bool
-    color_pairs: dict[int, int]
-    def __init__(self, height: int = 40, width: int = 160) -> None: ...
-    def get_dimensions(self) -> tuple[int, int]: ...
-    def clear(self) -> None: ...
-    def refresh(self) -> None: ...
-    def redraw(self) -> None: ...
-    def add_str(self, line: int, col: int, text: str, attr: int = 0) -> None: ...
-    def get_input(self) -> int: ...
-    def set_nodelay(self, flag: bool) -> None: ...
-    def has_colors(self) -> bool: ...
-    def init_color_pair(self, pair_id: int, fg: int, bg: int) -> None: ...
-    def get_color_pair(self, pair_id: int) -> int: ...
-    def get_attr(self, name: str) -> int: ...
-    def simulate_input(self, char: int) -> None: ...
-    def get_text_at(self, line: int, col: int) -> str | None: ...
-    def get_all_lines(self) -> list[str]: ...
-    def find_text(self, pattern: str) -> tuple[int, int] | None: ...
-    def contains_text(self, text: str) -> bool: ...