basedpyright 1.12.6 → 1.13.0

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

@@ -1,3 +1,12 @@
+"""
+Bisection algorithms.
+
+This module provides support for maintaining a list in sorted order without
+having to sort the list after each insertion. For long lists of items with
+expensive comparison operations, this can be an improvement over the more
+common approach.
+"""
+
 import sys
 from _typeshed import SupportsLenAndGetItem, SupportsRichComparisonT
 from collections.abc import Callable, MutableSequence
@@ -14,7 +23,18 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: None = None,
-    ) -> int: ...
+    ) -> int:
+        """
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e < x, and all e in
+        a[i:] have e >= x.  So if x already appears in the list, a.insert(i, x) will
+        insert just before the leftmost x already there.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def bisect_left(
         a: SupportsLenAndGetItem[_T],
@@ -23,7 +43,18 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: Callable[[_T], SupportsRichComparisonT],
-    ) -> int: ...
+    ) -> int:
+        """
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e < x, and all e in
+        a[i:] have e >= x.  So if x already appears in the list, a.insert(i, x) will
+        insert just before the leftmost x already there.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def bisect_right(
         a: SupportsLenAndGetItem[SupportsRichComparisonT],
@@ -32,7 +63,18 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: None = None,
-    ) -> int: ...
+    ) -> int:
+        """
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e <= x, and all e in
+        a[i:] have e > x.  So if x already appears in the list, a.insert(i, x) will
+        insert just after the rightmost x already there.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def bisect_right(
         a: SupportsLenAndGetItem[_T],
@@ -41,7 +83,18 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: Callable[[_T], SupportsRichComparisonT],
-    ) -> int: ...
+    ) -> int:
+        """
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e <= x, and all e in
+        a[i:] have e > x.  So if x already appears in the list, a.insert(i, x) will
+        insert just after the rightmost x already there.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def insort_left(
         a: MutableSequence[SupportsRichComparisonT],
@@ -50,11 +103,29 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: None = None,
-    ) -> None: ...
+    ) -> None:
+        """
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the left of the leftmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def insort_left(
         a: MutableSequence[_T], x: _T, lo: int = 0, hi: int | None = None, *, key: Callable[[_T], SupportsRichComparisonT]
-    ) -> None: ...
+    ) -> None:
+        """
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the left of the leftmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def insort_right(
         a: MutableSequence[SupportsRichComparisonT],
@@ -63,22 +134,88 @@ if sys.version_info >= (3, 10):
         hi: int | None = None,
         *,
         key: None = None,
-    ) -> None: ...
+    ) -> None:
+        """
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the right of the rightmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     @overload
     def insort_right(
         a: MutableSequence[_T], x: _T, lo: int = 0, hi: int | None = None, *, key: Callable[[_T], SupportsRichComparisonT]
-    ) -> None: ...
+    ) -> None:
+        """
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the right of the rightmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
 
 else:
     def bisect_left(
         a: SupportsLenAndGetItem[SupportsRichComparisonT], x: SupportsRichComparisonT, lo: int = 0, hi: int | None = None
-    ) -> int: ...
+    ) -> int:
+        """
+        bisect_left(a, x[, lo[, hi]]) -> index
+
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e < x, and all e in
+        a[i:] have e >= x.  So if x already appears in the list, i points just
+        before the leftmost x already there.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     def bisect_right(
         a: SupportsLenAndGetItem[SupportsRichComparisonT], x: SupportsRichComparisonT, lo: int = 0, hi: int | None = None
-    ) -> int: ...
+    ) -> int:
+        """
+        bisect_right(a, x[, lo[, hi]]) -> index
+
+        Return the index where to insert item x in list a, assuming a is sorted.
+
+        The return value i is such that all e in a[:i] have e <= x, and all e in
+        a[i:] have e > x.  So if x already appears in the list, i points just
+        beyond the rightmost x already there
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     def insort_left(
         a: MutableSequence[SupportsRichComparisonT], x: SupportsRichComparisonT, lo: int = 0, hi: int | None = None
-    ) -> None: ...
+    ) -> None:
+        """
+        insort_left(a, x[, lo[, hi]])
+
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the left of the leftmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...
     def insort_right(
         a: MutableSequence[SupportsRichComparisonT], x: SupportsRichComparisonT, lo: int = 0, hi: int | None = None
-    ) -> None: ...
+    ) -> None:
+        """
+        insort_right(a, x[, lo[, hi]])
+
+        Insert item x in list a, and keep it sorted assuming a is sorted.
+
+        If x is already in a, insert it to the right of the rightmost x.
+
+        Optional args lo (default 0) and hi (default len(a)) bound the
+        slice of a to be searched.
+        """
+        ...

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

@@ -13,13 +13,42 @@ _CharMap: TypeAlias = dict[int, int] | _EncodingMap
 _Handler: TypeAlias = Callable[[UnicodeError], tuple[str | bytes, int]]
 _SearchFunction: TypeAlias = Callable[[str], codecs.CodecInfo | None]
 
-def register(search_function: _SearchFunction, /) -> None: ...
+def register(search_function: _SearchFunction, /) -> None:
+    """
+    Register a codec search function.
 
-if sys.version_info >= (3, 10):
-    def unregister(search_function: _SearchFunction, /) -> None: ...
+    Search functions are expected to take one argument, the encoding name in
+    all lower case letters, and either return None, or a tuple of functions
+    (encoder, decoder, stream_reader, stream_writer) (or a CodecInfo object).
+    """
+    ...
 
-def register_error(errors: str, handler: _Handler, /) -> None: ...
-def lookup_error(name: str, /) -> _Handler: ...
+if sys.version_info >= (3, 10):
+    def unregister(search_function: _SearchFunction, /) -> None:
+        """
+        Unregister a codec search function and clear the registry's cache.
+
+        If the search function is not registered, do nothing.
+        """
+        ...
+
+def register_error(errors: str, handler: _Handler, /) -> None:
+    """
+    Register the specified error handler under the name errors.
+
+    handler must be a callable object, that will be called with an exception
+    instance containing information about the location of the encoding/decoding
+    error and must return a (replacement, new position) tuple.
+    """
+    ...
+def lookup_error(name: str, /) -> _Handler:
+    """
+    lookup_error(errors) -> handler
+
+    Return the error handler for the specified error handling name or raise a
+    LookupError, if no handler exists under this name.
+    """
+    ...
 
 # The type ignore on `encode` and `decode` is to avoid issues with overlapping overloads, for more details, see #300
 # https://docs.python.org/3/library/codecs.html#binary-transforms
@@ -45,15 +74,65 @@ _BytesToBytesEncoding: TypeAlias = Literal[
 _StrToStrEncoding: TypeAlias = Literal["rot13", "rot_13"]
 
 @overload
-def encode(obj: ReadableBuffer, encoding: _BytesToBytesEncoding, errors: str = "strict") -> bytes: ...
+def encode(obj: ReadableBuffer, encoding: _BytesToBytesEncoding, errors: str = "strict") -> bytes:
+    """
+    Encodes obj using the codec registered for encoding.
+
+    The default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 @overload
-def encode(obj: str, encoding: _StrToStrEncoding, errors: str = "strict") -> str: ...  # type: ignore[overload-overlap]
+def encode(obj: str, encoding: _StrToStrEncoding, errors: str = "strict") -> str:
+    """
+    Encodes obj using the codec registered for encoding.
+
+    The default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 @overload
-def encode(obj: str, encoding: str = "utf-8", errors: str = "strict") -> bytes: ...
+def encode(obj: str, encoding: str = "utf-8", errors: str = "strict") -> bytes:
+    """
+    Encodes obj using the codec registered for encoding.
+
+    The default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 @overload
-def decode(obj: ReadableBuffer, encoding: _BytesToBytesEncoding, errors: str = "strict") -> bytes: ...  # type: ignore[overload-overlap]
+def decode(obj: ReadableBuffer, encoding: _BytesToBytesEncoding, errors: str = "strict") -> bytes:
+    """
+    Decodes obj using the codec registered for encoding.
+
+    Default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 @overload
-def decode(obj: str, encoding: _StrToStrEncoding, errors: str = "strict") -> str: ...
+def decode(obj: str, encoding: _StrToStrEncoding, errors: str = "strict") -> str:
+    """
+    Decodes obj using the codec registered for encoding.
+
+    Default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 
 # these are documented as text encodings but in practice they also accept str as input
 @overload
@@ -61,14 +140,46 @@ def decode(
     obj: str,
     encoding: Literal["unicode_escape", "unicode-escape", "raw_unicode_escape", "raw-unicode-escape"],
     errors: str = "strict",
-) -> str: ...
+) -> str:
+    """
+    Decodes obj using the codec registered for encoding.
+
+    Default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 
 # hex is officially documented as a bytes to bytes encoding, but it appears to also work with str
 @overload
-def decode(obj: str, encoding: Literal["hex", "hex_codec"], errors: str = "strict") -> bytes: ...
+def decode(obj: str, encoding: Literal["hex", "hex_codec"], errors: str = "strict") -> bytes:
+    """
+    Decodes obj using the codec registered for encoding.
+
+    Default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
 @overload
-def decode(obj: ReadableBuffer, encoding: str = "utf-8", errors: str = "strict") -> str: ...
-def lookup(encoding: str, /) -> codecs.CodecInfo: ...
+def decode(obj: ReadableBuffer, encoding: str = "utf-8", errors: str = "strict") -> str:
+    """
+    Decodes obj using the codec registered for encoding.
+
+    Default encoding is 'utf-8'.  errors may be given to set a
+    different error handling scheme.  Default is 'strict' meaning that encoding
+    errors raise a ValueError.  Other possible values are 'ignore', 'replace'
+    and 'backslashreplace' as well as any other name registered with
+    codecs.register_error that can handle ValueErrors.
+    """
+    ...
+def lookup(encoding: str, /) -> codecs.CodecInfo:
+    """Looks up a codec tuple in the Python codec registry and returns a CodecInfo object."""
+    ...
 def charmap_build(map: str, /) -> _CharMap: ...
 def ascii_decode(data: ReadableBuffer, errors: str | None = None, /) -> tuple[str, int]: ...
 def ascii_encode(str: str, errors: str | None = None, /) -> tuple[bytes, int]: ...

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

@@ -1,3 +1,62 @@
+r"""
+CSV parsing and writing.
+
+This module provides classes that assist in the reading and writing
+of Comma Separated Value (CSV) files, and implements the interface
+described by PEP 305.  Although many CSV files are simple to parse,
+the format is not formally defined by a stable specification and
+is subtle enough that parsing lines of a CSV file with something
+like line.split(",") is bound to fail.  The module supports three
+basic APIs: reading, writing, and registration of dialects.
+
+
+DIALECT REGISTRATION:
+
+Readers and writers support a dialect argument, which is a convenient
+handle on a group of settings.  When the dialect argument is a string,
+it identifies one of the dialects previously registered with the module.
+If it is a class or instance, the attributes of the argument are used as
+the settings for the reader or writer:
+
+    class excel:
+        delimiter = ','
+        quotechar = '"'
+        escapechar = None
+        doublequote = True
+        skipinitialspace = False
+        lineterminator = '\r\n'
+        quoting = QUOTE_MINIMAL
+
+SETTINGS:
+
+    * quotechar - specifies a one-character string to use as the
+        quoting character.  It defaults to '"'.
+    * delimiter - specifies a one-character string to use as the
+        field separator.  It defaults to ','.
+    * skipinitialspace - specifies how to interpret whitespace which
+        immediately follows a delimiter.  It defaults to False, which
+        means that whitespace immediately following a delimiter is part
+        of the following field.
+    * lineterminator -  specifies the character sequence which should
+        terminate rows.
+    * quoting - controls when quotes should be generated by the writer.
+        It can take on any of the following module constants:
+
+        csv.QUOTE_MINIMAL means only when required, for example, when a
+            field contains either the quotechar or the delimiter
+        csv.QUOTE_ALL means that quotes are always placed around fields.
+        csv.QUOTE_NONNUMERIC means that quotes are always placed around
+            fields which do not parse as integers or floating point
+            numbers.
+        csv.QUOTE_NONE means that quotes are never placed around fields.
+    * escapechar - specifies a one-character string used to escape
+        the delimiter when quoting is set to QUOTE_NONE.
+    * doublequote - controls the handling of quotes inside fields.  When
+        True, two consecutive quotes are interpreted as one during read,
+        and when writing, each quote character embedded in the data is
+        written as two quotes
+"""
+
 import sys
 from _typeshed import SupportsWrite
 from collections.abc import Iterable, Iterator
@@ -21,6 +80,11 @@ _QuotingType: TypeAlias = int
 class Error(Exception): ...
 
 class Dialect:
+    """
+    CSV dialect
+
+    The Dialect type records CSV parsing and generation options.
+    """
     delimiter: str
     quotechar: str | None
     escapechar: str | None
@@ -57,7 +121,22 @@ def writer(
     lineterminator: str = "\r\n",
     quoting: _QuotingType = 0,
     strict: bool = False,
-) -> _writer: ...
+) -> _writer:
+    """
+    csv_writer = csv.writer(fileobj [, dialect='excel']
+                                [optional keyword args])
+        for row in sequence:
+            csv_writer.writerow(row)
+
+        [or]
+
+        csv_writer = csv.writer(fileobj [, dialect='excel']
+                                [optional keyword args])
+        csv_writer.writerows(rows)
+
+    The "fileobj" argument can be any object that supports the file API.
+    """
+    ...
 def reader(
     csvfile: Iterable[str],
     dialect: _DialectLike = "excel",
@@ -70,7 +149,23 @@ def reader(
     lineterminator: str = "\r\n",
     quoting: _QuotingType = 0,
     strict: bool = False,
-) -> _reader: ...
+) -> _reader:
+    """
+    csv_reader = reader(iterable [, dialect='excel']
+                            [optional keyword args])
+        for row in csv_reader:
+            process(row)
+
+    The "iterable" argument can be any object that returns a line
+    of input for each iteration, such as a file object or a list.  The
+    optional "dialect" parameter is discussed below.  The function
+    also accepts optional keyword arguments which override settings
+    provided by the dialect.
+
+    The returned object is an iterator.  Each iteration returns a row
+    of the CSV file (which can span multiple input lines).
+    """
+    ...
 def register_dialect(
     name: str,
     dialect: type[Dialect] = ...,
@@ -83,8 +178,36 @@ def register_dialect(
     lineterminator: str = "\r\n",
     quoting: _QuotingType = 0,
     strict: bool = False,
-) -> None: ...
-def unregister_dialect(name: str) -> None: ...
-def get_dialect(name: str) -> Dialect: ...
-def list_dialects() -> list[str]: ...
-def field_size_limit(new_limit: int = ...) -> int: ...
+) -> None:
+    """
+    Create a mapping from a string name to a dialect class.
+    dialect = csv.register_dialect(name[, dialect[, **fmtparams]])
+    """
+    ...
+def unregister_dialect(name: str) -> None:
+    """
+    Delete the name/dialect mapping associated with a string name.
+    csv.unregister_dialect(name)
+    """
+    ...
+def get_dialect(name: str) -> Dialect:
+    """
+    Return the dialect instance associated with name.
+    dialect = csv.get_dialect(name)
+    """
+    ...
+def list_dialects() -> list[str]:
+    """
+    Return a list of all know dialect names.
+    names = csv.list_dialects()
+    """
+    ...
+def field_size_limit(new_limit: int = ...) -> int:
+    """
+    Sets an upper limit on parsed fields.
+        csv.field_size_limit([limit])
+
+    Returns old limit. If limit is not given, no new limit is set and
+    the old limit is returned
+    """
+    ...