basedpyright 1.12.6 → 1.13.0

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

@@ -1,3 +1,5 @@
+"""Importing this module enables command line editing using libedit readline."""
+
 import sys
 from _typeshed import StrOrBytesPath
 from collections.abc import Callable, Sequence
@@ -7,30 +9,185 @@ if sys.platform != "win32":
     _Completer: TypeAlias = Callable[[str, int], str | None]
     _CompDisp: TypeAlias = Callable[[str, Sequence[str], int], None]
 
-    def parse_and_bind(string: str, /) -> None: ...
-    def read_init_file(filename: StrOrBytesPath | None = None, /) -> None: ...
-    def get_line_buffer() -> str: ...
-    def insert_text(string: str, /) -> None: ...
-    def redisplay() -> None: ...
-    def read_history_file(filename: StrOrBytesPath | None = None, /) -> None: ...
-    def write_history_file(filename: StrOrBytesPath | None = None, /) -> None: ...
-    def append_history_file(nelements: int, filename: StrOrBytesPath | None = None, /) -> None: ...
-    def get_history_length() -> int: ...
-    def set_history_length(length: int, /) -> None: ...
-    def clear_history() -> None: ...
-    def get_current_history_length() -> int: ...
-    def get_history_item(index: int, /) -> str: ...
-    def remove_history_item(pos: int, /) -> None: ...
-    def replace_history_item(pos: int, line: str, /) -> None: ...
-    def add_history(string: str, /) -> None: ...
-    def set_auto_history(enabled: bool, /) -> None: ...
-    def set_startup_hook(function: Callable[[], object] | None = None, /) -> None: ...
-    def set_pre_input_hook(function: Callable[[], object] | None = None, /) -> None: ...
-    def set_completer(function: _Completer | None = None, /) -> None: ...
-    def get_completer() -> _Completer | None: ...
-    def get_completion_type() -> int: ...
-    def get_begidx() -> int: ...
-    def get_endidx() -> int: ...
-    def set_completer_delims(string: str, /) -> None: ...
-    def get_completer_delims() -> str: ...
-    def set_completion_display_matches_hook(function: _CompDisp | None = None, /) -> None: ...
+    def parse_and_bind(string: str, /) -> None:
+        """
+        parse_and_bind(string) -> None
+        Execute the init line provided in the string argument.
+        """
+        ...
+    def read_init_file(filename: StrOrBytesPath | None = None, /) -> None:
+        """
+        read_init_file([filename]) -> None
+        Execute a readline initialization file.
+        The default filename is the last filename used.
+        """
+        ...
+    def get_line_buffer() -> str:
+        """
+        get_line_buffer() -> string
+        return the current contents of the line buffer.
+        """
+        ...
+    def insert_text(string: str, /) -> None:
+        """
+        insert_text(string) -> None
+        Insert text into the line buffer at the cursor position.
+        """
+        ...
+    def redisplay() -> None:
+        """
+        redisplay() -> None
+        Change what's displayed on the screen to reflect the current
+        contents of the line buffer.
+        """
+        ...
+    def read_history_file(filename: StrOrBytesPath | None = None, /) -> None:
+        """
+        read_history_file([filename]) -> None
+        Load a readline history file.
+        The default filename is ~/.history.
+        """
+        ...
+    def write_history_file(filename: StrOrBytesPath | None = None, /) -> None:
+        """
+        write_history_file([filename]) -> None
+        Save a readline history file.
+        The default filename is ~/.history.
+        """
+        ...
+    def append_history_file(nelements: int, filename: StrOrBytesPath | None = None, /) -> None:
+        """
+        Append the last nelements items of the history list to file.
+
+        The default filename is ~/.history.
+        """
+        ...
+    def get_history_length() -> int:
+        """
+        get_history_length() -> int
+        return the maximum number of lines that will be written to
+        the history file.
+        """
+        ...
+    def set_history_length(length: int, /) -> None:
+        """
+        set_history_length(length) -> None
+        set the maximal number of lines which will be written to
+        the history file. A negative length is used to inhibit
+        history truncation.
+        """
+        ...
+    def clear_history() -> None:
+        """
+        clear_history() -> None
+        Clear the current readline history.
+        """
+        ...
+    def get_current_history_length() -> int:
+        """
+        get_current_history_length() -> integer
+        return the current (not the maximum) length of history.
+        """
+        ...
+    def get_history_item(index: int, /) -> str:
+        """
+        get_history_item() -> string
+        return the current contents of history item at index.
+        """
+        ...
+    def remove_history_item(pos: int, /) -> None:
+        """
+        remove_history_item(pos) -> None
+        remove history item given by its position
+        """
+        ...
+    def replace_history_item(pos: int, line: str, /) -> None:
+        """
+        replace_history_item(pos, line) -> None
+        replaces history item given by its position with contents of line
+        """
+        ...
+    def add_history(string: str, /) -> None:
+        """
+        add_history(string) -> None
+        add an item to the history buffer
+        """
+        ...
+    def set_auto_history(enabled: bool, /) -> None:
+        """
+        set_auto_history(enabled) -> None
+        Enables or disables automatic history.
+        """
+        ...
+    def set_startup_hook(function: Callable[[], object] | None = None, /) -> None:
+        """
+        set_startup_hook([function]) -> None
+        Set or remove the function invoked by the rl_startup_hook callback.
+        The function is called with no arguments just
+        before readline prints the first prompt.
+        """
+        ...
+    def set_pre_input_hook(function: Callable[[], object] | None = None, /) -> None:
+        """
+        Set or remove the function invoked by the rl_pre_input_hook callback.
+
+        The function is called with no arguments after the first prompt
+        has been printed and just before readline starts reading input
+        characters.
+        """
+        ...
+    def set_completer(function: _Completer | None = None, /) -> None:
+        """
+        set_completer([function]) -> None
+        Set or remove the completer function.
+        The function is called as function(text, state),
+        for state in 0, 1, 2, ..., until it returns a non-string.
+        It should return the next possible completion starting with 'text'.
+        """
+        ...
+    def get_completer() -> _Completer | None:
+        """
+        get_completer() -> function
+
+        Returns current completer function.
+        """
+        ...
+    def get_completion_type() -> int:
+        """
+        get_completion_type() -> int
+        Get the type of completion being attempted.
+        """
+        ...
+    def get_begidx() -> int:
+        """
+        get_begidx() -> int
+        get the beginning index of the completion scope
+        """
+        ...
+    def get_endidx() -> int:
+        """
+        get_endidx() -> int
+        get the ending index of the completion scope
+        """
+        ...
+    def set_completer_delims(string: str, /) -> None:
+        """
+        set_completer_delims(string) -> None
+        set the word delimiters for completion
+        """
+        ...
+    def get_completer_delims() -> str:
+        """
+        get_completer_delims() -> string
+        get the word delimiters for completion
+        """
+        ...
+    def set_completion_display_matches_hook(function: _CompDisp | None = None, /) -> None:
+        """
+        set_completion_display_matches_hook([function]) -> None
+        Set or remove the completion display function.
+        The function is called as
+          function(substitution, [matches], longest_match_length)
+        once each time matches need to be displayed.
+        """
+        ...

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

@@ -29,6 +29,14 @@ if sys.platform != "win32":
     class struct_rusage(
         structseq[float], tuple[float, float, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
     ):
+        """
+        struct_rusage: Result from getrusage.
+
+        This object may be accessed either as a tuple of
+            (utime,stime,maxrss,ixrss,idrss,isrss,minflt,majflt,
+            nswap,inblock,oublock,msgsnd,msgrcv,nsignals,nvcsw,nivcsw)
+        or via the attributes ru_utime, ru_stime, ru_maxrss, and so on.
+        """
         if sys.version_info >= (3, 10):
             __match_args__: Final = (
                 "ru_utime",
@@ -50,37 +58,69 @@ if sys.platform != "win32":
             )
 
         @property
-        def ru_utime(self) -> float: ...
+        def ru_utime(self) -> float:
+            """user time used"""
+            ...
         @property
-        def ru_stime(self) -> float: ...
+        def ru_stime(self) -> float:
+            """system time used"""
+            ...
         @property
-        def ru_maxrss(self) -> int: ...
+        def ru_maxrss(self) -> int:
+            """max. resident set size"""
+            ...
         @property
-        def ru_ixrss(self) -> int: ...
+        def ru_ixrss(self) -> int:
+            """shared memory size"""
+            ...
         @property
-        def ru_idrss(self) -> int: ...
+        def ru_idrss(self) -> int:
+            """unshared data size"""
+            ...
         @property
-        def ru_isrss(self) -> int: ...
+        def ru_isrss(self) -> int:
+            """unshared stack size"""
+            ...
         @property
-        def ru_minflt(self) -> int: ...
+        def ru_minflt(self) -> int:
+            """page faults not requiring I/O"""
+            ...
         @property
-        def ru_majflt(self) -> int: ...
+        def ru_majflt(self) -> int:
+            """page faults requiring I/O"""
+            ...
         @property
-        def ru_nswap(self) -> int: ...
+        def ru_nswap(self) -> int:
+            """number of swap outs"""
+            ...
         @property
-        def ru_inblock(self) -> int: ...
+        def ru_inblock(self) -> int:
+            """block input operations"""
+            ...
         @property
-        def ru_oublock(self) -> int: ...
+        def ru_oublock(self) -> int:
+            """block output operations"""
+            ...
         @property
-        def ru_msgsnd(self) -> int: ...
+        def ru_msgsnd(self) -> int:
+            """IPC messages sent"""
+            ...
         @property
-        def ru_msgrcv(self) -> int: ...
+        def ru_msgrcv(self) -> int:
+            """IPC messages received"""
+            ...
         @property
-        def ru_nsignals(self) -> int: ...
+        def ru_nsignals(self) -> int:
+            """signals received"""
+            ...
         @property
-        def ru_nvcsw(self) -> int: ...
+        def ru_nvcsw(self) -> int:
+            """voluntary context switches"""
+            ...
         @property
-        def ru_nivcsw(self) -> int: ...
+        def ru_nivcsw(self) -> int:
+            """involuntary context switches"""
+            ...
 
     def getpagesize() -> int: ...
     def getrlimit(resource: int, /) -> tuple[int, int]: ...

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

@@ -1,3 +1,10 @@
+"""
+This module supports asynchronous I/O on multiple file descriptors.
+
+*** IMPORTANT NOTICE ***
+On Windows, only sockets are supported; on Unix, all file descriptors.
+"""
+
 import sys
 from _typeshed import FileDescriptorLike
 from collections.abc import Iterable
@@ -22,6 +29,12 @@ if sys.platform != "win32":
     POLLWRNORM: int
 
 class poll:
+    """
+    Returns a polling object.
+
+    This object supports registering and unregistering file descriptors, and then
+    polling them for I/O events.
+    """
     def register(self, fd: FileDescriptorLike, eventmask: int = ...) -> None: ...
     def modify(self, fd: FileDescriptorLike, eventmask: int) -> None: ...
     def unregister(self, fd: FileDescriptorLike) -> None: ...
@@ -29,7 +42,32 @@ class poll:
 
 def select(
     rlist: Iterable[Any], wlist: Iterable[Any], xlist: Iterable[Any], timeout: float | None = None, /
-) -> tuple[list[Any], list[Any], list[Any]]: ...
+) -> tuple[list[Any], list[Any], list[Any]]:
+    """
+    Wait until one or more file descriptors are ready for some kind of I/O.
+
+    The first three arguments are iterables of file descriptors to be waited for:
+    rlist -- wait until ready for reading
+    wlist -- wait until ready for writing
+    xlist -- wait for an "exceptional condition"
+    If only one kind of condition is required, pass [] for the other lists.
+
+    A file descriptor is either a socket or file object, or a small integer
+    gotten from a fileno() method call on one of those.
+
+    The optional 4th argument specifies a timeout in seconds; it may be
+    a floating point number to specify fractions of seconds.  If it is absent
+    or None, the call will never time out.
+
+    The return value is a tuple of three lists corresponding to the first three
+    arguments; each contains the subset of the corresponding file descriptors
+    that are ready.
+
+    *** IMPORTANT NOTICE ***
+    On Windows, only sockets are supported; on Unix, all file
+    descriptors can be used.
+    """
+    ...
 
 error = OSError
 
@@ -37,6 +75,22 @@ if sys.platform != "linux" and sys.platform != "win32":
     # BSD only
     @final
     class kevent:
+        """
+        kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
+
+        This object is the equivalent of the struct kevent for the C API.
+
+        See the kqueue manpage for more detailed information about the meaning
+        of the arguments.
+
+        One minor note: while you might hope that udata could store a
+        reference to a python object, it cannot, because it is impossible to
+        keep a proper reference count of the object once it's passed into the
+        kernel. Therefore, I have restricted it to only storing an integer.  I
+        recommend ignoring it and simply using the 'ident' field to key off
+        of. You could also set up a dictionary on the python side to store a
+        udata->object mapping.
+        """
         data: Any
         fflags: int
         filter: int
@@ -56,15 +110,53 @@ if sys.platform != "linux" and sys.platform != "win32":
     # BSD only
     @final
     class kqueue:
+        """
+        Kqueue syscall wrapper.
+
+        For example, to start watching a socket for input:
+        >>> kq = kqueue()
+        >>> sock = socket()
+        >>> sock.connect((host, port))
+        >>> kq.control([kevent(sock, KQ_FILTER_WRITE, KQ_EV_ADD)], 0)
+
+        To wait one second for it to become writeable:
+        >>> kq.control(None, 1, 1000)
+
+        To stop listening:
+        >>> kq.control([kevent(sock, KQ_FILTER_WRITE, KQ_EV_DELETE)], 0)
+        """
         closed: bool
         def __init__(self) -> None: ...
-        def close(self) -> None: ...
+        def close(self) -> None:
+            """
+            Close the kqueue control file descriptor.
+
+            Further operations on the kqueue object will raise an exception.
+            """
+            ...
         def control(
             self, changelist: Iterable[kevent] | None, maxevents: int, timeout: float | None = None, /
-        ) -> list[kevent]: ...
-        def fileno(self) -> int: ...
+        ) -> list[kevent]:
+            """
+            Calls the kernel kevent function.
+
+            changelist
+              Must be an iterable of kevent objects describing the changes to be made
+              to the kernel's watch list or None.
+            maxevents
+              The maximum number of events that the kernel will return.
+            timeout
+              The maximum time to wait in seconds, or else None to wait forever.
+              This accepts floats for smaller timeouts, too.
+            """
+            ...
+        def fileno(self) -> int:
+            """Return the kqueue control file descriptor."""
+            ...
         @classmethod
-        def fromfd(cls, fd: FileDescriptorLike, /) -> kqueue: ...
+        def fromfd(cls, fd: FileDescriptorLike, /) -> kqueue:
+            """Create a kqueue object from a given control fd."""
+            ...
 
     KQ_EV_ADD: int
     KQ_EV_CLEAR: int

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

@@ -1,3 +1,15 @@
+"""
+This module provides access to the Unix shadow password database.
+It is available on various Unix versions.
+
+Shadow password database entries are reported as 9-tuples of type struct_spwd,
+containing the following items from the password database (see `<shadow.h>'):
+sp_namp, sp_pwdp, sp_lstchg, sp_min, sp_max, sp_warn, sp_inact, sp_expire, sp_flag.
+The sp_namp and sp_pwdp are strings, the rest are integers.
+An exception is raised if the entry asked for cannot be found.
+You have to be root to be able to use this module.
+"""
+
 import sys
 from _typeshed import structseq
 from typing import Any, Final, final
@@ -5,6 +17,13 @@ from typing import Any, Final, final
 if sys.platform != "win32":
     @final
     class struct_spwd(structseq[Any], tuple[str, str, int, int, int, int, int, int, int]):
+        """
+        spwd.struct_spwd: Results from getsp*() routines.
+
+        This object may be accessed either as a 9-tuple of
+          (sp_namp,sp_pwdp,sp_lstchg,sp_min,sp_max,sp_warn,sp_inact,sp_expire,sp_flag)
+        or via the object attributes as named in the above tuple.
+        """
         if sys.version_info >= (3, 10):
             __match_args__: Final = (
                 "sp_namp",
@@ -19,23 +38,53 @@ if sys.platform != "win32":
             )
 
         @property
-        def sp_namp(self) -> str: ...
+        def sp_namp(self) -> str:
+            """login name"""
+            ...
         @property
-        def sp_pwdp(self) -> str: ...
+        def sp_pwdp(self) -> str:
+            """encrypted password"""
+            ...
         @property
-        def sp_lstchg(self) -> int: ...
+        def sp_lstchg(self) -> int:
+            """date of last change"""
+            ...
         @property
-        def sp_min(self) -> int: ...
+        def sp_min(self) -> int:
+            """min #days between changes"""
+            ...
         @property
-        def sp_max(self) -> int: ...
+        def sp_max(self) -> int:
+            """max #days between changes"""
+            ...
         @property
-        def sp_warn(self) -> int: ...
+        def sp_warn(self) -> int:
+            """#days before pw expires to warn user about it"""
+            ...
         @property
-        def sp_inact(self) -> int: ...
+        def sp_inact(self) -> int:
+            """#days after pw expires until account is disabled"""
+            ...
         @property
-        def sp_expire(self) -> int: ...
+        def sp_expire(self) -> int:
+            """#days since 1970-01-01 when account expires"""
+            ...
         @property
-        def sp_flag(self) -> int: ...
+        def sp_flag(self) -> int:
+            """reserved"""
+            ...
+
+    def getspall() -> list[struct_spwd]:
+        """
+        Return a list of all available shadow password database entries, in arbitrary order.
+
+        See `help(spwd)` for more on shadow password database entries.
+        """
+        ...
+    def getspnam(arg: str, /) -> struct_spwd:
+        """
+        Return the shadow password database entry for the given user name.
 
-    def getspall() -> list[struct_spwd]: ...
-    def getspnam(arg: str, /) -> struct_spwd: ...
+        See `help(spwd)` for more on shadow password database entries.
+        """
+        ...