[gdb] Complete stubs for gdb.dap (#14269)

Author: brianschubert

stubs/gdb/@tests/stubtest_allowlist.txt

@@ -73,6 +73,3 @@ gdb.Progspace.xmethods
 
 # stubtest thinks this can't be sub-classed at runtime, but it is
 gdb.disassembler.DisassemblerPart
-
-# incomplete modules
-gdb\.dap\.[a-z_]+\.[A-Za-z_]+

stubs/gdb/gdb/__init__.pyi

@@ -7,7 +7,7 @@ import threading
 from _typeshed import Incomplete
 from collections.abc import Callable, Iterator, Mapping, Sequence
 from contextlib import AbstractContextManager
-from typing import Any, Final, Generic, Literal, Protocol, TypeVar, final, overload, type_check_only
+from typing import Any, Final, Generic, Literal, Protocol, TypedDict, TypeVar, final, overload, type_check_only
 from typing_extensions import TypeAlias, deprecated
 
 import gdb.FrameDecorator
@@ -860,10 +860,16 @@ class LazyString:
 
 # Architectures
 
+@type_check_only
+class _Instruction(TypedDict):
+    addr: int
+    asm: str
+    length: int
+
 @final
 class Architecture:
     def name(self) -> str: ...
-    def disassemble(self, start_pc: int, end_pc: int = ..., count: int = ...) -> list[dict[str, object]]: ...
+    def disassemble(self, start_pc: int, end_pc: int = ..., count: int = ...) -> list[_Instruction]: ...
     def integer_type(self, size: int, signed: bool = ...) -> Type: ...
     def registers(self, reggroup: str = ...) -> RegisterDescriptorIterator: ...
     def register_groups(self) -> RegisterGroupsIterator: ...

stubs/gdb/gdb/dap/__init__.pyi

@@ -1,11 +1,19 @@
-from typing import Any
-
-class Server:
-    def __init__(self, in_stream, out_stream, child_stream) -> None: ...
-    def main_loop(self) -> None: ...
-    def send_event(self, event: str, body: Any | None = None) -> None: ...  # body is an arbitrary object
-    def send_event_later(self, event: str, body: Any | None = None) -> None: ...  # body is an arbitrary object
-    def shutdown(self) -> None: ...
+from . import (
+    breakpoint as breakpoint,
+    bt as bt,
+    evaluate as evaluate,
+    launch as launch,
+    locations as locations,
+    memory as memory,
+    modules as modules,
+    next as next,
+    pause as pause,
+    scopes as scopes,
+    sources as sources,
+    startup as startup,
+    threads as threads,
+)
+from .server import Server as Server
 
 def pre_command_loop() -> None: ...
 def run() -> None: ...

stubs/gdb/gdb/dap/breakpoint.pyi

@@ -1 +1,49 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Incomplete, Unused
+from collections.abc import Sequence
+from contextlib import AbstractContextManager
+from typing import TypedDict, type_check_only
+from typing_extensions import NotRequired
+
+import gdb
+
+from .sources import Source
+
+@type_check_only
+class _SourceBreakpoint(TypedDict):
+    source: str
+    line: int
+    condition: NotRequired[str | None]
+    hitCondition: NotRequired[str | None]
+    logMessage: NotRequired[str | None]
+
+@type_check_only
+class _ExceptionFilterOptions(TypedDict):
+    filderId: str
+    condition: NotRequired[str | None]
+
+@type_check_only
+class _BreakpointDescriptor(TypedDict):
+    id: int
+    verified: bool
+    reason: NotRequired[str]  # only present when verified is False. Possibly only literal "pending" or "failed"
+    message: NotRequired[str]  # only present when reason == "failed"
+    source: NotRequired[Source]
+    line: NotRequired[int]
+    instructionReference: NotRequired[str]
+
+@type_check_only
+class _SetBreakpointResult(TypedDict):
+    breakpoints: list[_BreakpointDescriptor]
+
+# frozenset entries are tuples from _SourceBreakpoint.items() or _ExceptionFilterOptions.items()
+breakpoint_map: dict[str, dict[frozenset[Incomplete], gdb.Breakpoint]]
+
+def suppress_new_breakpoint_event() -> AbstractContextManager[None]: ...
+def set_breakpoint(*, source: Source, breakpoints: Sequence[_SourceBreakpoint] = (), **args: Unused) -> _SetBreakpointResult: ...
+def set_fn_breakpoint(*, breakpoints: Sequence[_SourceBreakpoint], **args: Unused) -> _SetBreakpointResult: ...
+def set_insn_breakpoints(
+    *, breakpoints: Sequence[_SourceBreakpoint], offset: int | None = None, **args: Unused
+) -> _SetBreakpointResult: ...
+def set_exception_breakpoints(
+    *, filters: Sequence[str], filterOptions: Sequence[_ExceptionFilterOptions] = (), **args: Unused
+) -> _SetBreakpointResult: ...

stubs/gdb/gdb/dap/bt.pyi

@@ -1 +1,49 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Unused
+from typing import TypedDict, type_check_only
+from typing_extensions import NotRequired
+
+from .sources import Source
+from .varref import _ValueFormat
+
+@type_check_only
+class _StackFrameFormat(_ValueFormat, total=False):
+    parameters: bool
+    parameterTypes: bool
+    parameterNames: bool
+    parameterValues: bool
+    line: bool
+    module: bool
+    includeAll: bool
+
+@type_check_only
+class _StackFrame(TypedDict):
+    id: int
+    name: str
+    line: int
+    column: int
+    instructionPointerReference: str
+    moduleId: NotRequired[str | None]
+    source: NotRequired[Source]
+
+@type_check_only
+class _StackTraceResult(TypedDict):
+    stackFrames: list[_StackFrame]
+
+def check_stack_frame(
+    *,
+    # From source:
+    #   Note that StackFrameFormat extends ValueFormat, which is why
+    #   "hex" appears here.
+    hex: bool = False,
+    parameters: bool = False,
+    parameterTypes: bool = False,
+    parameterNames: bool = False,
+    parameterValues: bool = False,
+    line: bool = False,
+    module: bool = False,
+    includeAll: bool = False,
+    **rest: Unused,
+) -> _StackFrameFormat: ...
+def stacktrace(
+    *, levels: int = 0, startFrame: int = 0, threadId: int, format: _StackFrameFormat | None = None, **extra: Unused
+) -> _StackTraceResult: ...

stubs/gdb/gdb/dap/disassemble.pyi

@@ -1 +1,22 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Unused
+from typing import TypedDict, type_check_only
+from typing_extensions import NotRequired
+
+from .sources import Source
+
+@type_check_only
+class _Instruction(TypedDict):
+    address: str
+    instruction: str
+    instructionBytes: str
+    symbol: NotRequired[str]  # only set if there's a corresponding label
+    line: NotRequired[int]  # only set if source is available
+    location: NotRequired[Source]  # only set if source is available
+
+@type_check_only
+class _DisassembleResult(TypedDict):
+    instructions: list[_Instruction]
+
+def disassemble(
+    *, memoryReference: str, offset: int = 0, instructionOffset: int = 0, instructionCount: int, **extra: Unused
+) -> _DisassembleResult: ...

stubs/gdb/gdb/dap/evaluate.pyi

@@ -1 +1,31 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Unused
+from typing import Literal, TypedDict, type_check_only
+
+import gdb
+
+from .varref import VariableReference, _ValueFormat, _VariableReferenceDescriptor
+
+class EvaluateResult(VariableReference):
+    def __init__(self, value: gdb.Value) -> None: ...
+
+@type_check_only
+class _VariablesResult(TypedDict):
+    variables: list[_VariableReferenceDescriptor]
+
+def eval_request(
+    *,
+    expression: str,
+    frameId: int | None = None,
+    context: Literal["watch", "variables", "hover", "repl"] = "variables",
+    format: _ValueFormat | None = None,
+    **args: Unused,
+) -> _VariableReferenceDescriptor: ...
+def variables(
+    *, variablesReference: int, start: int = 0, count: int = 0, format: _ValueFormat | None = None, **args: Unused
+) -> _VariablesResult: ...
+def set_expression(
+    *, expression: str, value: str, frameId: int | None = None, format: _ValueFormat | None = None, **args: Unused
+) -> _VariableReferenceDescriptor: ...
+def set_variable(
+    *, variablesReference: int, name: str, value: str, format: _ValueFormat | None = None, **args: Unused
+) -> _VariableReferenceDescriptor: ...

stubs/gdb/gdb/dap/events.pyi

@@ -1 +1,12 @@
-def __getattr__(name: str): ...  # incomplete module
+import gdb
+
+inferior_running: bool
+
+def send_process_event_once() -> None: ...
+def expect_process(reason: str) -> None: ...
+def thread_event(event: gdb.ThreadEvent, reason: str) -> None: ...
+def expect_stop(reason: str) -> None: ...
+def exec_and_expect_stop(cmd: str, expected_pause: bool = False) -> None: ...
+
+# Map from gdb stop reasons to DAP stop reasons.
+stop_reason_map: dict[str, str]

stubs/gdb/gdb/dap/frames.pyi

@@ -1 +1,7 @@
-def __getattr__(name: str): ...  # incomplete module
+from collections.abc import Generator
+
+import gdb
+
+def frame_for_id(id: int) -> gdb.Frame: ...
+def select_frame(id: int) -> None: ...
+def dap_frame_generator(frame_low: int, levels: int, include_all: bool) -> Generator[tuple[int, gdb.Frame]]: ...

stubs/gdb/gdb/dap/io.pyi

@@ -1 +1,16 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import SupportsFlush, SupportsRead, SupportsReadline, SupportsWrite
+from typing import Any, type_check_only
+
+import gdb
+
+from .server import _JSONValue
+from .startup import DAPQueue
+
+@type_check_only
+class _SupportsReadAndReadlineBytes(SupportsRead[bytes], SupportsReadline[bytes]): ...
+
+@type_check_only
+class _SupportsWriteAndFlushBytes(SupportsWrite[bytes], SupportsFlush): ...
+
+def read_json(stream: _SupportsReadAndReadlineBytes) -> Any: ...  # returns result of json.loads
+def start_json_writer(stream: _SupportsWriteAndFlushBytes, queue: DAPQueue[_JSONValue]) -> gdb.Thread: ...