basedpyright 1.40.1 → 1.40.2

package/dist/typeshed-fallback/stdlib/_json.pyi

@@ -74,22 +74,26 @@ class make_scanner:
         ...
 
 def encode_basestring(s: str, /) -> str:
-    """
-    encode_basestring(string) -> string
-
-    Return a JSON representation of a Python string
-    """
+    """Return a JSON representation of a Python string"""
     ...
 def encode_basestring_ascii(s: str, /) -> str:
-    """
-    encode_basestring_ascii(string) -> string
-
-    Return an ASCII-only JSON representation of a Python string
-    """
+    """Return an ASCII-only JSON representation of a Python string"""
     ...
 
 if sys.version_info >= (3, 15):
-    def scanstring(pystr: str, end: int, strict: bool = True, /) -> tuple[str, int]: ...
+    def scanstring(pystr: str, end: int, strict: bool = True, /) -> tuple[str, int]:
+        """
+        Scan the string s for a JSON string.
+
+        End is the index of the character in s after the quote that started the
+        JSON string. Unescapes all valid JSON string escape sequences and raises
+        ValueError on attempt to decode an invalid string. If strict is False
+        then literal control characters are allowed in the string.
+
+        Returns a tuple of the decoded string and the index of the character in
+        s after the end quote.
+        """
+        ...
 
 else:
     def scanstring(string: str, end: int, strict: bool = True) -> tuple[str, int]:

package/dist/typeshed-fallback/stdlib/_remote_debugging.pyi

@@ -17,15 +17,24 @@ THREAD_STATUS_UNKNOWN: Final[int]
 
 @final
 class LocationInfo(structseq[int], tuple[int, int, int, int]):
+    """Source location information: (lineno, end_lineno, col_offset, end_col_offset)"""
     __match_args__: Final = ("lineno", "end_lineno", "col_offset", "end_col_offset")
     @property
-    def lineno(self) -> int: ...
+    def lineno(self) -> int:
+        """Line number"""
+        ...
     @property
-    def end_lineno(self) -> int: ...
+    def end_lineno(self) -> int:
+        """End line number"""
+        ...
     @property
-    def col_offset(self) -> int: ...
+    def col_offset(self) -> int:
+        """Column offset"""
+        ...
     @property
-    def end_col_offset(self) -> int: ...
+    def end_col_offset(self) -> int:
+        """End column offset"""
+        ...
 
 @final
 class FrameInfo(structseq[object], tuple[str, _Location, str, int | None]):
@@ -36,13 +45,17 @@ class FrameInfo(structseq[object], tuple[str, _Location, str, int | None]):
         """Source code filename"""
         ...
     @property
-    def location(self) -> _Location: ...
+    def location(self) -> _Location:
+        """LocationInfo structseq or None for synthetic frames"""
+        ...
     @property
     def funcname(self) -> str:
         """Function name"""
         ...
     @property
-    def opcode(self) -> int | None: ...
+    def opcode(self) -> int | None:
+        """Opcode being executed (None if not gathered)"""
+        ...
 
 @final
 class CoroInfo(structseq[object], tuple[list[_Frame], int | str]):
@@ -87,7 +100,9 @@ class ThreadInfo(structseq[object], tuple[int, int, list[_Frame]]):
         """Thread ID"""
         ...
     @property
-    def status(self) -> int: ...
+    def status(self) -> int:
+        """Thread status (flags: HAS_GIL, ON_CPU, UNKNOWN or legacy enum)"""
+        ...
     @property
     def frame_info(self) -> list[_Frame]:
         """Frame information"""
@@ -95,11 +110,16 @@ class ThreadInfo(structseq[object], tuple[int, int, list[_Frame]]):
 
 @final
 class InterpreterInfo(structseq[object], tuple[int, list[ThreadInfo]]):
+    """Information about an interpreter"""
     __match_args__: Final = ("interpreter_id", "threads")
     @property
-    def interpreter_id(self) -> int: ...
+    def interpreter_id(self) -> int:
+        """Interpreter ID"""
+        ...
     @property
-    def threads(self) -> list[ThreadInfo]: ...
+    def threads(self) -> list[ThreadInfo]:
+        """List of threads in this interpreter"""
+        ...
 
 @final
 class AwaitedInfo(structseq[object], tuple[int, list[TaskInfo]]):
@@ -116,6 +136,7 @@ class AwaitedInfo(structseq[object], tuple[int, list[TaskInfo]]):
 
 @final
 class GCStatsInfo(structseq[object], tuple[int, int, int, int, int, int, int, int, int, float]):
+    """Information about a garbage collector stats sample"""
     __match_args__: Final = (
         "gen",
         "iid",
@@ -129,25 +150,45 @@ class GCStatsInfo(structseq[object], tuple[int, int, int, int, int, int, int, in
         "duration",
     )
     @property
-    def gen(self) -> int: ...
+    def gen(self) -> int:
+        """GC generation number"""
+        ...
     @property
-    def iid(self) -> int: ...
+    def iid(self) -> int:
+        """Interpreter ID"""
+        ...
     @property
-    def ts_start(self) -> int: ...
+    def ts_start(self) -> int:
+        """Raw timestamp at collection start"""
+        ...
     @property
-    def ts_stop(self) -> int: ...
+    def ts_stop(self) -> int:
+        """Raw timestamp at collection stop"""
+        ...
     @property
-    def collections(self) -> int: ...
+    def collections(self) -> int:
+        """Total number of collections"""
+        ...
     @property
-    def collected(self) -> int: ...
+    def collected(self) -> int:
+        """Total number of collected objects"""
+        ...
     @property
-    def uncollectable(self) -> int: ...
+    def uncollectable(self) -> int:
+        """Total number of uncollectable objects"""
+        ...
     @property
-    def candidates(self) -> int: ...
+    def candidates(self) -> int:
+        """Total objects considered and traversed"""
+        ...
     @property
-    def heap_size(self) -> int: ...
+    def heap_size(self) -> int:
+        """Number of live objects"""
+        ...
     @property
-    def duration(self) -> float: ...
+    def duration(self) -> float:
+        """Total collection time, in seconds"""
+        ...
 
 @final
 class RemoteUnwinder:
@@ -169,56 +210,77 @@ class RemoteUnwinder:
     ) -> None: ...
     def get_stack_trace(self) -> list[InterpreterInfo]:
         """
-        Returns a list of stack traces for threads in the target process.
+        Returns stack traces for all interpreters and threads in process.
 
-        Each element in the returned list is a tuple of (thread_id, frame_list), where:
-        - thread_id is the OS thread identifier
-        - frame_list is a list of tuples (function_name, filename, line_number) representing
-          the Python stack frames for that thread, ordered from most recent to oldest
+        Each element in the returned list is a tuple of (interpreter_id,
+        thread_list), where:
+        - interpreter_id is the interpreter identifier
+        - thread_list is a list of tuples (thread_id, frame_list) for
+          threads in that interpreter
+          - thread_id is the OS thread identifier
+          - frame_list is a list of tuples (function_name, filename,
+            line_number) representing the Python stack frames for that
+            thread, ordered from most recent to oldest
 
         The threads returned depend on the initialization parameters:
-        - If only_active_thread was True: returns only the thread holding the GIL
-        - If all_threads was True: returns all threads
-        - Otherwise: returns only the main thread
+        - If only_active_thread was True: returns only the thread holding
+          the GIL across all interpreters
+        - If all_threads was True: returns all threads across all
+          interpreters
+        - Otherwise: returns only the main thread of each interpreter
 
         Example:
             [
-                (1234, [
-                    ('process_data', 'worker.py', 127),
-                    ('run_worker', 'worker.py', 45),
-                    ('main', 'app.py', 23)
+                (0, [  # Main interpreter
+                    (1234, [
+                        ('process_data', 'worker.py', 127),
+                        ('run_worker', 'worker.py', 45),
+                        ('main', 'app.py', 23)
+                    ]),
+                    (1235, [
+                        ('handle_request', 'server.py', 89),
+                        ('serve_forever', 'server.py', 52)
+                    ])
                 ]),
-                (1235, [
-                    ('handle_request', 'server.py', 89),
-                    ('serve_forever', 'server.py', 52)
+                (1, [  # Sub-interpreter
+                    (1236, [
+                        ('sub_worker', 'sub.py', 15)
+                    ])
                 ])
             ]
 
         Raises:
-            RuntimeError: If there is an error copying memory from the target process
+            RuntimeError: If there is an error copying memory from the
+                target process
             OSError: If there is an error accessing the target process
             PermissionError: If access to the target process is denied
-            UnicodeDecodeError: If there is an error decoding strings from the target process
+            UnicodeDecodeError: If there is an error decoding strings from
+                the target process
         """
         ...
     def get_all_awaited_by(self) -> list[AwaitedInfo]:
         """
         Get all tasks and their awaited_by relationships from the remote process.
 
-        This provides a tree structure showing which tasks are waiting for other tasks.
+        This provides a tree structure showing which tasks are waiting for
+        other tasks.
 
         For each task, returns:
-        1. The call stack frames leading to where the task is currently executing
+        1. The call stack frames leading to where the task is currently
+           executing
         2. The name of the task
-        3. A list of tasks that this task is waiting for, with their own frames/names/etc
+        3. A list of tasks that this task is waiting for, with their own
+           frames/names/etc
 
         Returns a list of [frames, task_name, subtasks] where:
-        - frames: List of (func_name, filename, lineno) showing the call stack
+        - frames: List of (func_name, filename, lineno) showing the call
+          stack
         - task_name: String identifier for the task
         - subtasks: List of tasks being awaited by this task, in same format
 
         Raises:
-            RuntimeError: If AsyncioDebug section is not available in the remote process
+            RuntimeError: If AsyncioDebug section is not available in the
+                remote process
             MemoryError: If memory allocation fails
             OSError: If reading from the remote process fails
 
@@ -243,14 +305,16 @@ class RemoteUnwinder:
         """
         Get the currently running async tasks and their dependency graphs from the remote process.
 
-        This returns information about running tasks and all tasks that are waiting for them,
-        forming a complete dependency graph for each thread's active task.
+        This returns information about running tasks and all tasks that are
+        waiting for them, forming a complete dependency graph for each
+        thread's active task.
 
-        For each thread with a running task, returns the running task plus all tasks that
-        transitively depend on it (tasks waiting for the running task, tasks waiting for
-        those tasks, etc.).
+        For each thread with a running task, returns the running task plus
+        all tasks that transitively depend on it (tasks waiting for the
+        running task, tasks waiting for those tasks, etc.).
 
-        Returns a list of per-thread results, where each thread result contains:
+        Returns a list of per-thread results, where each thread result
+        contains:
         - Thread ID
         - List of task information for the running task and all its waiters
 
@@ -261,11 +325,13 @@ class RemoteUnwinder:
         - List of tasks waiting for this task (recursive structure)
 
         Raises:
-            RuntimeError: If AsyncioDebug section is not available in the target process
+            RuntimeError: If AsyncioDebug section is not available in the
+                target process
             MemoryError: If memory allocation fails
             OSError: If reading from the remote process fails
 
-        Example output (similar structure to get_all_awaited_by but only for running tasks):
+        Example output (similar structure to get_all_awaited_by but only for
+        running tasks):
         [
             (140234, [
                 (4345585712, 'main_task',
@@ -278,14 +344,111 @@ class RemoteUnwinder:
         ]
         """
         ...
-    def get_stats(self) -> _Stats: ...
-    def pause_threads(self) -> bool: ...
-    def resume_threads(self) -> bool: ...
+    def get_stats(self) -> _Stats:
+        """
+        Get collected statistics about profiling performance.
+
+        Returns a dictionary containing statistics about cache performance,
+        memory reads, and other profiling metrics. Only available if the
+        RemoteUnwinder was created with stats=True.
+
+        Returns:
+            dict: A dictionary containing:
+                - total_samples: Total number of get_stack_trace calls
+                - frame_cache_hits: Full cache hits (entire stack unchanged)
+                - frame_cache_misses: Cache misses requiring full walk
+                - frame_cache_partial_hits: Partial hits (stopped at cached
+                  frame)
+                - frames_read_from_cache: Total frames retrieved from cache
+                - frames_read_from_memory: Total frames read from remote
+                  memory
+                - memory_reads: Total remote memory read operations
+                - memory_bytes_read: Total bytes read from remote memory
+                - code_object_cache_hits: Code object cache hits
+                - code_object_cache_misses: Code object cache misses
+                - stale_cache_invalidations: Times stale cache entries were
+                  cleared
+                - batched_read_attempts: Batched remote-read attempts
+                - batched_read_successes: Attempts that read all requested
+                  segments
+                - batched_read_misses: Attempts that fell back or partially
+                  read
+                - batched_read_segments_requested: Segments requested by
+                  batched reads
+                - batched_read_segments_completed: Segments completed by
+                  batched reads
+                - frame_cache_hit_rate: Percentage of samples that hit the
+                  cache
+                - code_object_cache_hit_rate: Percentage of code object
+                  lookups that hit cache
+                - batched_read_success_rate: Percentage of batched reads
+                  that completed all segments
+                - batched_read_segment_completion_rate: Percentage of
+                  requested segments read by batched reads
+
+        Raises:
+            RuntimeError: If stats collection was not enabled (stats=False)
+        """
+        ...
+    def pause_threads(self) -> bool:
+        """
+        Pause all threads in the target process.
+
+        This stops all threads in the target process to allow for consistent
+        memory reads during sampling. Must be paired with a call to
+        resume_threads().
+
+        Returns True if threads were successfully paused, False if they were
+        already paused.
+
+        Raises:
+            RuntimeError: If there is an error stopping the threads
+        """
+        ...
+    def resume_threads(self) -> bool:
+        """
+        Resume all threads in the target process.
+
+        This resumes threads that were previously paused with
+        pause_threads().
+
+        Returns True if threads were successfully resumed, False if they
+        were not paused.
+        """
+        ...
 
 @final
 class GCMonitor:
+    """GCMonitor(pid): Monitor GC events of a remote Python process."""
     def __init__(self, pid: int, *, debug: bool = False) -> None: ...
-    def get_gc_stats(self, all_interpreters: bool = False) -> list[GCStatsInfo]: ...
+    def get_gc_stats(self, all_interpreters: bool = False) -> list[GCStatsInfo]:
+        """
+        Get garbage collector statistics from external Python process.
+
+          all_interpreters
+            If True, return GC statistics from all interpreters.
+            If False, return only from main interpreter.
+
+        Returns a list of GCStatsInfo objects with GC statistics data.
+
+        Returns:
+            list of GCStatsInfo: A list of stats samples containing:
+                - gen: GC generation number.
+                - iid: Interpreter ID.
+                - ts_start: Raw timestamp at collection start.
+                - ts_stop: Raw timestamp at collection stop.
+                - collections: Total number of collections.
+                - collected: Total number of collected objects.
+                - uncollectable: Total number of uncollectable objects.
+                - candidates: Total objects considered and traversed.
+                - heap_size: number of live objects.
+                - duration: Total collection time, in seconds.
+
+        Raises:
+            RuntimeError: If the target process cannot be inspected or if
+                its debug offsets or GC stats layout are incompatible.
+        """
+        ...
 
 @final
 class BinaryWriter:
@@ -293,29 +456,149 @@ class BinaryWriter:
         self, filename: StrOrBytesPath, sample_interval_us: int, start_time_us: int, *, compression: int = 0
     ) -> None: ...
     @property
-    def total_samples(self) -> int: ...
-    def write_sample(self, stack_frames: list[InterpreterInfo], timestamp_us: int) -> None: ...
-    def finalize(self) -> None: ...
-    def close(self) -> None: ...
-    def __enter__(self) -> Self: ...
-    def __exit__(self, exc_type: object = None, exc_val: object = None, exc_tb: object = None) -> bool: ...
-    def get_stats(self) -> _Stats: ...
+    def total_samples(self) -> int:
+        """Total samples written"""
+        ...
+    def write_sample(self, stack_frames: list[InterpreterInfo], timestamp_us: int) -> None:
+        """
+        Write a sample to the binary file.
+
+        Arguments:
+            stack_frames: List of InterpreterInfo objects
+            timestamp_us: Current timestamp in microseconds (from
+                time.monotonic() * 1e6)
+        """
+        ...
+    def finalize(self) -> None:
+        """
+        Finalize and close the binary file.
+
+        Writes string/frame tables, footer, and updates header.
+        """
+        ...
+    def close(self) -> None:
+        """Close the writer without finalizing (discards data)."""
+        ...
+    def __enter__(self) -> Self:
+        """Enter context manager."""
+        ...
+    def __exit__(self, exc_type: object = None, exc_val: object = None, exc_tb: object = None) -> bool:
+        """Exit context manager, finalizing the file."""
+        ...
+    def get_stats(self) -> _Stats:
+        """
+        Get encoding statistics for the writer.
+
+        Returns a dict with encoding statistics including
+        repeat/full/suffix/pop-push record counts, frames written/saved, and
+        compression ratio.
+        """
+        ...
 
 @final
 class BinaryReader:
     def __init__(self, filename: StrOrBytesPath) -> None: ...
     @property
-    def sample_count(self) -> int: ...
+    def sample_count(self) -> int:
+        """Number of samples in file"""
+        ...
     @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: ...
-    def close(self) -> None: ...
-    def __enter__(self) -> Self: ...
-    def __exit__(self, exc_type: object = None, exc_val: object = None, exc_tb: object = None) -> bool: ...
+    def sample_interval_us(self) -> int:
+        """Sample interval in microseconds"""
+        ...
+    def replay(self, collector: object, progress_callback: Callable[[int, int], object] | None = None) -> int:
+        """
+        Replay samples through a collector.
+
+        Arguments:
+            collector: Collector object with collect() method
+            progress_callback: Optional callable(current, total)
+
+        Returns:
+            Number of samples replayed
+        """
+        ...
+    def get_info(self) -> dict[str, object]:
+        """
+        Get metadata about the binary file.
+
+        Returns:
+            Dict with file metadata
+        """
+        ...
+    def get_stats(self) -> _Stats:
+        """
+        Get reconstruction statistics from replay.
+
+        Returns a dict with statistics about record types decoded and
+        samples reconstructed during replay.
+        """
+        ...
+    def close(self) -> None:
+        """Close the reader and free resources."""
+        ...
+    def __enter__(self) -> Self:
+        """Enter context manager."""
+        ...
+    def __exit__(self, exc_type: object = None, exc_val: object = None, exc_tb: object = None) -> bool:
+        """Exit context manager, closing the file."""
+        ...
+
+def zstd_available() -> bool:
+    """
+    Check if zstd compression is available.
+
+    Returns:
+        True if zstd available, False otherwise
+    """
+    ...
+def get_child_pids(pid: int, *, recursive: bool = True) -> list[int]:
+    """
+    Get all child process IDs of the given process.
+
+      pid
+        Process ID of the parent process
+      recursive
+        If True, return all descendants (children, grandchildren, etc.).
+        If False, return only direct children.
+
+    Returns a list of child process IDs.  Returns an empty list if no
+    children are found.
+
+    This function provides a snapshot of child processes at a moment in
+    time.  Child processes may exit or new ones may be created after the
+    list is returned.
+
+    Raises:
+        OSError: If unable to enumerate processes
+        NotImplementedError: If not supported on this platform
+    """
+    ...
+def is_python_process(pid: int) -> bool:
+    """Check if a process is a Python process."""
+    ...
+def get_gc_stats(pid: int, *, all_interpreters: bool = False) -> list[GCStatsInfo]:
+    """
+    Get garbage collector statistics from external Python process.
+
+      all_interpreters
+        If True, return GC statistics from all interpreters.
+        If False, return only from main interpreter.
+
+    Returns:
+        list of GCStatsInfo: A list of stats samples containing:
+            - gen: GC generation number.
+            - iid: Interpreter ID.
+            - ts_start: Raw timestamp at collection start.
+            - ts_stop: Raw timestamp at collection stop.
+            - collections: Total number of collections.
+            - collected: Total number of collected objects.
+            - uncollectable: Total number of uncollectable objects.
+            - candidates: Total objects considered and traversed.
+            - duration: Total collection time, in seconds.
 
-def zstd_available() -> bool: ...
-def get_child_pids(pid: int, *, recursive: bool = True) -> list[int]: ...
-def is_python_process(pid: int) -> bool: ...
-def get_gc_stats(pid: int, *, all_interpreters: bool = False) -> list[GCStatsInfo]: ...
+    Raises:
+        RuntimeError: If the target process cannot be inspected or if its
+            debug offsets or GC stats layout are incompatible.
+    """
+    ...

package/dist/typeshed-fallback/stdlib/_socket.pyi

@@ -1136,21 +1136,21 @@ class socket:
         ...
     def send(self, data: ReadableBuffer, flags: int = 0, /) -> int:
         """
-        send(data[, flags]) -> count
+        Send a data string to the socket.
 
-        Send a data string to the socket.  For the optional flags
-        argument, see the Unix manual.  Return the number of bytes
-        sent; this may be less than len(data) if the network is busy.
+        For the optional flags argument, see the Unix manual.
+        Return the number of bytes sent; this may be less than len(data) if
+        the network is busy.
         """
         ...
     def sendall(self, data: ReadableBuffer, flags: int = 0, /) -> None:
         """
-        sendall(data[, flags])
+        Send a data string to the socket.
 
-        Send a data string to the socket.  For the optional flags
-        argument, see the Unix manual.  This calls send() repeatedly
-        until all data is sent.  If an error occurs, it's impossible
-        to tell how much data has been sent.
+        For the optional flags argument, see the Unix manual.
+        This calls send() repeatedly until all data is sent.
+        If an error occurs, it's impossible to tell how much data has been
+        sent.
         """
         ...
 
@@ -1183,21 +1183,21 @@ class socket:
             /,
         ) -> int:
             """
-            sendmsg(buffers[, ancdata[, flags[, address]]]) -> count
+            Send normal and ancillary data to the socket.
 
-            Send normal and ancillary data to the socket, gathering the
-            non-ancillary data from a series of buffers and concatenating it into
-            a single message.  The buffers argument specifies the non-ancillary
+            It gathering the non-ancillary data from a series of buffers
+            and concatenating it into a single message.
+            The buffers argument specifies the non-ancillary
             data as an iterable of bytes-like objects (e.g. bytes objects).
             The ancdata argument specifies the ancillary data (control messages)
             as an iterable of zero or more tuples (cmsg_level, cmsg_type,
-            cmsg_data), where cmsg_level and cmsg_type are integers specifying the
-            protocol level and protocol-specific type respectively, and cmsg_data
-            is a bytes-like object holding the associated data.  The flags
-            argument defaults to 0 and has the same meaning as for send().  If
-            address is supplied and not None, it sets a destination address for
-            the message.  The return value is the number of bytes of non-ancillary
-            data sent.
+            cmsg_data), where cmsg_level and cmsg_type are integers specifying
+            the protocol level and protocol-specific type respectively, and
+            cmsg_data is a bytes-like object holding the associated data.  The
+            flags argument defaults to 0 and has the same meaning as for send().
+            If address is supplied and not None, it sets a destination address
+            for the message.  The return value is the number of bytes of
+            non-ancillary data sent.
             """
             ...
     if sys.platform == "linux":
@@ -1404,7 +1404,7 @@ def setdefaulttimeout(timeout: float | None, /) -> None:
     """
     setdefaulttimeout(timeout)
 
-    Set the default timeout in seconds (float) for new socket objects.
+    Set the default timeout in seconds (real number) for new socket objects.
     A value of None indicates that new socket objects have no timeout.
     When the socket module is first imported, the default is None.
     """