Sync Linux docstrings

Author: typeshedbot

crates/ty_vendored/vendor/typeshed/stdlib/__future__.pyi

@@ -1,11 +1,68 @@
+"""Record of phased-in incompatible language changes.
+
+Each line is of the form:
+
+    FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+                              CompilerFlag ")"
+
+where, normally, OptionalRelease < MandatoryRelease, and both are 5-tuples
+of the same form as sys.version_info:
+
+    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+     PY_MINOR_VERSION, # the 1; an int
+     PY_MICRO_VERSION, # the 0; an int
+     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+     PY_RELEASE_SERIAL # the 3; an int
+    )
+
+OptionalRelease records the first release in which
+
+    from __future__ import FeatureName
+
+was accepted.
+
+In the case of MandatoryReleases that have not yet occurred,
+MandatoryRelease predicts the release in which the feature will become part
+of the language.
+
+Else MandatoryRelease records when the feature became part of the language;
+in releases at or after that, modules no longer need
+
+    from __future__ import FeatureName
+
+to use the feature in question, but may continue to use such imports.
+
+MandatoryRelease may also be None, meaning that a planned feature got
+dropped or that the release version is undetermined.
+
+Instances of class _Feature have two corresponding methods,
+.getOptionalRelease() and .getMandatoryRelease().
+
+CompilerFlag is the (bitfield) flag that should be passed in the fourth
+argument to the builtin function compile() to enable the feature in
+dynamically compiled code.  This flag is stored in the .compiler_flag
+attribute on _Future instances.  These values must match the appropriate
+#defines of CO_xxx flags in Include/cpython/compile.h.
+
+No feature line is ever to be deleted from this file.
+"""
 from typing_extensions import TypeAlias
 
 _VersionInfo: TypeAlias = tuple[int, int, int, str, int]
 
 class _Feature:
     def __init__(self, optionalRelease: _VersionInfo, mandatoryRelease: _VersionInfo | None, compiler_flag: int) -> None: ...
-    def getOptionalRelease(self) -> _VersionInfo: ...
-    def getMandatoryRelease(self) -> _VersionInfo | None: ...
+    def getOptionalRelease(self) -> _VersionInfo:
+        """Return first release in which this feature was recognized.
+
+This is a 5-tuple, of the same form as sys.version_info.
+"""
+    def getMandatoryRelease(self) -> _VersionInfo | None:
+        """Return release in which this feature will become mandatory.
+
+This is a 5-tuple, of the same form as sys.version_info, or, if
+the feature was dropped, or the release date is undetermined, is None.
+"""
     compiler_flag: int
 
 absolute_import: _Feature

crates/ty_vendored/vendor/typeshed/stdlib/_asyncio.pyi

@@ -1,3 +1,5 @@
+"""Accelerator module for asyncio
+"""
 import sys
 from asyncio.events import AbstractEventLoop
 from collections.abc import Awaitable, Callable, Coroutine, Generator
@@ -12,6 +14,19 @@ _TaskYieldType: TypeAlias = Future[object] | None
 
 @disjoint_base
 class Future(Awaitable[_T]):
+    """This class is *almost* compatible with concurrent.futures.Future.
+
+    Differences:
+
+    - result() and exception() do not take a timeout argument and
+      raise an exception when the future isn't done yet.
+
+    - Callbacks registered with add_done_callback() are always called
+      via the event loop's call_soon_threadsafe().
+
+    - This class is not compatible with the wait() and as_completed()
+      methods in the concurrent.futures package.
+"""
     _state: str
     @property
     def _exception(self) -> BaseException | None: ...
@@ -22,24 +37,80 @@ class Future(Awaitable[_T]):
     def _log_traceback(self, val: Literal[False]) -> None: ...
     _asyncio_future_blocking: bool  # is a part of duck-typing contract for `Future`
     def __init__(self, *, loop: AbstractEventLoop | None = None) -> None: ...
-    def __del__(self) -> None: ...
-    def get_loop(self) -> AbstractEventLoop: ...
+    def __del__(self) -> None:
+        """Called when the instance is about to be destroyed.
+"""
+    def get_loop(self) -> AbstractEventLoop:
+        """Return the event loop the Future is bound to.
+"""
     @property
     def _callbacks(self) -> list[tuple[Callable[[Self], Any], Context]]: ...
-    def add_done_callback(self, fn: Callable[[Self], object], /, *, context: Context | None = None) -> None: ...
-    def cancel(self, msg: Any | None = None) -> bool: ...
-    def cancelled(self) -> bool: ...
-    def done(self) -> bool: ...
-    def result(self) -> _T: ...
-    def exception(self) -> BaseException | None: ...
-    def remove_done_callback(self, fn: Callable[[Self], object], /) -> int: ...
-    def set_result(self, result: _T, /) -> None: ...
-    def set_exception(self, exception: type | BaseException, /) -> None: ...
-    def __iter__(self) -> Generator[Any, None, _T]: ...
-    def __await__(self) -> Generator[Any, None, _T]: ...
+    def add_done_callback(self, fn: Callable[[Self], object], /, *, context: Context | None = None) -> None:
+        """Add a callback to be run when the future becomes done.
+
+The callback is called with a single argument - the future object. If
+the future is already done when this is called, the callback is
+scheduled with call_soon.
+"""
+    def cancel(self, msg: Any | None = None) -> bool:
+        """Cancel the future and schedule callbacks.
+
+If the future is already done or cancelled, return False.  Otherwise,
+change the future's state to cancelled, schedule the callbacks and
+return True.
+"""
+    def cancelled(self) -> bool:
+        """Return True if the future was cancelled.
+"""
+    def done(self) -> bool:
+        """Return True if the future is done.
+
+Done means either that a result / exception are available, or that the
+future was cancelled.
+"""
+    def result(self) -> _T:
+        """Return the result this future represents.
+
+If the future has been cancelled, raises CancelledError.  If the
+future's result isn't yet available, raises InvalidStateError.  If
+the future is done and has an exception set, this exception is raised.
+"""
+    def exception(self) -> BaseException | None:
+        """Return the exception that was set on this future.
+
+The exception (or None if no exception was set) is returned only if
+the future is done.  If the future has been cancelled, raises
+CancelledError.  If the future isn't done yet, raises
+InvalidStateError.
+"""
+    def remove_done_callback(self, fn: Callable[[Self], object], /) -> int:
+        """Remove all instances of a callback from the "call when done" list.
+
+Returns the number of callbacks removed.
+"""
+    def set_result(self, result: _T, /) -> None:
+        """Mark the future done and set its result.
+
+If the future is already done when this method is called, raises
+InvalidStateError.
+"""
+    def set_exception(self, exception: type | BaseException, /) -> None:
+        """Mark the future done and set an exception.
+
+If the future is already done when this method is called, raises
+InvalidStateError.
+"""
+    def __iter__(self) -> Generator[Any, None, _T]:
+        """Implement iter(self).
+"""
+    def __await__(self) -> Generator[Any, None, _T]:
+        """Return an iterator to be used in await expression.
+"""
     @property
     def _loop(self) -> AbstractEventLoop: ...
-    def __class_getitem__(cls, item: Any, /) -> GenericAlias: ...
+    def __class_getitem__(cls, item: Any, /) -> GenericAlias:
+        """See PEP 585
+"""
 
 if sys.version_info >= (3, 12):
     _TaskCompatibleCoro: TypeAlias = Coroutine[Any, Any, _T_co]
@@ -52,6 +123,8 @@ else:
 # and `asyncio.Task.set_result()` always raises.
 @disjoint_base
 class Task(Future[_T_co]):  # type: ignore[type-var]  # pyright: ignore[reportInvalidTypeArguments]
+    """A coroutine wrapped in a Future.
+"""
     if sys.version_info >= (3, 12):
         def __init__(
             self,
@@ -86,27 +159,118 @@ class Task(Future[_T_co]):  # type: ignore[type-var]  # pyright: ignore[reportIn
     if sys.version_info >= (3, 12):
         def get_context(self) -> Context: ...
 
-    def get_stack(self, *, limit: int | None = None) -> list[FrameType]: ...
-    def print_stack(self, *, limit: int | None = None, file: TextIO | None = None) -> None: ...
+    def get_stack(self, *, limit: int | None = None) -> list[FrameType]:
+        """Return the list of stack frames for this task's coroutine.
+
+If the coroutine is not done, this returns the stack where it is
+suspended.  If the coroutine has completed successfully or was
+cancelled, this returns an empty list.  If the coroutine was
+terminated by an exception, this returns the list of traceback
+frames.
+
+The frames are always ordered from oldest to newest.
+
+The optional limit gives the maximum number of frames to
+return; by default all available frames are returned.  Its
+meaning differs depending on whether a stack or a traceback is
+returned: the newest frames of a stack are returned, but the
+oldest frames of a traceback are returned.  (This matches the
+behavior of the traceback module.)
+
+For reasons beyond our control, only one stack frame is
+returned for a suspended coroutine.
+"""
+    def print_stack(self, *, limit: int | None = None, file: TextIO | None = None) -> None:
+        """Print the stack or traceback for this task's coroutine.
+
+This produces output similar to that of the traceback module,
+for the frames retrieved by get_stack().  The limit argument
+is passed to get_stack().  The file argument is an I/O stream
+to which the output is written; by default output is written
+to sys.stderr.
+"""
     if sys.version_info >= (3, 11):
-        def cancelling(self) -> int: ...
-        def uncancel(self) -> int: ...
+        def cancelling(self) -> int:
+            """Return the count of the task's cancellation requests.
+
+This count is incremented when .cancel() is called
+and may be decremented using .uncancel().
+"""
+        def uncancel(self) -> int:
+            """Decrement the task's count of cancellation requests.
+
+This should be used by tasks that catch CancelledError
+and wish to continue indefinitely until they are cancelled again.
+
+Returns the remaining number of cancellation requests.
+"""
+
+    def __class_getitem__(cls, item: Any, /) -> GenericAlias:
+        """See PEP 585
+"""
+
+def get_event_loop() -> AbstractEventLoop:
+    """Return an asyncio event loop.
+
+When called from a coroutine or a callback (e.g. scheduled with
+call_soon or similar API), this function will always return the
+running event loop.
+
+If there is no running event loop set, the function will return
+the result of `get_event_loop_policy().get_event_loop()` call.
+"""
+def get_running_loop() -> AbstractEventLoop:
+    """Return the running event loop.  Raise a RuntimeError if there is none.
+
+This function is thread-specific.
+"""
+def _set_running_loop(loop: AbstractEventLoop | None, /) -> None:
+    """Set the running event loop.
+
+This is a low-level function intended to be used by event loops.
+This function is thread-specific.
+"""
+def _get_running_loop() -> AbstractEventLoop:
+    """Return the running event loop or None.
+
+This is a low-level function intended to be used by event loops.
+This function is thread-specific.
+"""
+def _register_task(task: Task[Any]) -> None:
+    """Register a new task in asyncio as executed by loop.
+
+Returns None.
+"""
+def _unregister_task(task: Task[Any]) -> None:
+    """Unregister a task.
+
+Returns None.
+"""
+def _enter_task(loop: AbstractEventLoop, task: Task[Any]) -> None:
+    """Enter into task execution or resume suspended task.
+
+Task belongs to loop.
+
+Returns None.
+"""
+def _leave_task(loop: AbstractEventLoop, task: Task[Any]) -> None:
+    """Leave task execution or suspend a task.
 
-    def __class_getitem__(cls, item: Any, /) -> GenericAlias: ...
+Task belongs to loop.
 
-def get_event_loop() -> AbstractEventLoop: ...
-def get_running_loop() -> AbstractEventLoop: ...
-def _set_running_loop(loop: AbstractEventLoop | None, /) -> None: ...
-def _get_running_loop() -> AbstractEventLoop: ...
-def _register_task(task: Task[Any]) -> None: ...
-def _unregister_task(task: Task[Any]) -> None: ...
-def _enter_task(loop: AbstractEventLoop, task: Task[Any]) -> None: ...
-def _leave_task(loop: AbstractEventLoop, task: Task[Any]) -> None: ...
+Returns None.
+"""
 
 if sys.version_info >= (3, 12):
-    def current_task(loop: AbstractEventLoop | None = None) -> Task[Any] | None: ...
+    def current_task(loop: AbstractEventLoop | None = None) -> Task[Any] | None:
+        """Return a currently executed task.
+"""
 
 if sys.version_info >= (3, 14):
     def future_discard_from_awaited_by(future: Future[Any], waiter: Future[Any], /) -> None: ...
-    def future_add_to_awaited_by(future: Future[Any], waiter: Future[Any], /) -> None: ...
-    def all_tasks(loop: AbstractEventLoop | None = None) -> set[Task[Any]]: ...
+    def future_add_to_awaited_by(future: Future[Any], waiter: Future[Any], /) -> None:
+        """Record that `fut` is awaited on by `waiter`.
+"""
+    def all_tasks(loop: AbstractEventLoop | None = None) -> set[Task[Any]]:
+        """Return a set of all tasks for the loop.
+"""