basedpyright 1.13.2 → 1.13.3

package/dist/typeshed-fallback/stdlib/sqlite3/dbapi2.pyi

@@ -218,10 +218,20 @@ if sys.version_info >= (3, 12):
 
 # Can take or return anything depending on what's in the registry.
 @overload
-def adapt(obj: Any, proto: Any, /) -> Any: ...
+def adapt(obj: Any, proto: Any, /) -> Any:
+    """adapt(obj, protocol, alternate) -> adapt obj to given protocol. Non-standard."""
+    ...
 @overload
-def adapt(obj: Any, proto: Any, alt: _T, /) -> Any | _T: ...
-def complete_statement(statement: str) -> bool: ...
+def adapt(obj: Any, proto: Any, alt: _T, /) -> Any | _T:
+    """adapt(obj, protocol, alternate) -> adapt obj to given protocol. Non-standard."""
+    ...
+def complete_statement(statement: str) -> bool:
+    """
+    complete_statement(sql)
+
+    Checks if a string contains a complete SQL statement. Non-standard.
+    """
+    ...
 
 if sys.version_info >= (3, 12):
     @overload
@@ -235,7 +245,14 @@ if sys.version_info >= (3, 12):
         uri: bool = False,
         *,
         autocommit: bool = ...,
-    ) -> Connection: ...
+    ) -> Connection:
+        """
+        Opens a connection to the SQLite database file database.
+
+        You can use ":memory:" to open a database connection to a database that resides
+        in RAM instead of on disk.
+        """
+        ...
     @overload
     def connect(
         database: StrOrBytesPath,
@@ -248,7 +265,14 @@ if sys.version_info >= (3, 12):
         uri: bool = False,
         *,
         autocommit: bool = ...,
-    ) -> _ConnectionT: ...
+    ) -> _ConnectionT:
+        """
+        Opens a connection to the SQLite database file database.
+
+        You can use ":memory:" to open a database connection to a database that resides
+        in RAM instead of on disk.
+        """
+        ...
     @overload
     def connect(
         database: StrOrBytesPath,
@@ -261,7 +285,14 @@ if sys.version_info >= (3, 12):
         cached_statements: int = 128,
         uri: bool = False,
         autocommit: bool = ...,
-    ) -> _ConnectionT: ...
+    ) -> _ConnectionT:
+        """
+        Opens a connection to the SQLite database file database.
+
+        You can use ":memory:" to open a database connection to a database that resides
+        in RAM instead of on disk.
+        """
+        ...
 
 else:
     @overload
@@ -273,7 +304,16 @@ else:
         check_same_thread: bool = True,
         cached_statements: int = 128,
         uri: bool = False,
-    ) -> Connection: ...
+    ) -> Connection:
+        """
+        connect(database[, timeout, detect_types, isolation_level,
+                check_same_thread, factory, cached_statements, uri])
+
+        Opens a connection to the SQLite database file *database*. You can use
+        ":memory:" to open a database connection to a database that resides in
+        RAM instead of on disk.
+        """
+        ...
     @overload
     def connect(
         database: StrOrBytesPath,
@@ -284,7 +324,16 @@ else:
         factory: type[_ConnectionT],
         cached_statements: int = 128,
         uri: bool = False,
-    ) -> _ConnectionT: ...
+    ) -> _ConnectionT:
+        """
+        connect(database[, timeout, detect_types, isolation_level,
+                check_same_thread, factory, cached_statements, uri])
+
+        Opens a connection to the SQLite database file *database*. You can use
+        ":memory:" to open a database connection to a database that resides in
+        RAM instead of on disk.
+        """
+        ...
     @overload
     def connect(
         database: StrOrBytesPath,
@@ -296,21 +345,59 @@ else:
         factory: type[_ConnectionT],
         cached_statements: int = 128,
         uri: bool = False,
-    ) -> _ConnectionT: ...
+    ) -> _ConnectionT:
+        """
+        connect(database[, timeout, detect_types, isolation_level,
+                check_same_thread, factory, cached_statements, uri])
+
+        Opens a connection to the SQLite database file *database*. You can use
+        ":memory:" to open a database connection to a database that resides in
+        RAM instead of on disk.
+        """
+        ...
+
+def enable_callback_tracebacks(enable: bool, /) -> None:
+    """
+    enable_callback_tracebacks(flag)
 
-def enable_callback_tracebacks(enable: bool, /) -> None: ...
+    Enable or disable callback functions throwing errors to stderr.
+    """
+    ...
 
 if sys.version_info < (3, 12):
     # takes a pos-or-keyword argument because there is a C wrapper
-    def enable_shared_cache(enable: int) -> None: ...
+    def enable_shared_cache(enable: int) -> None:
+        """
+        enable_shared_cache(do_enable)
+
+        Enable or disable shared cache mode for the calling thread.
+        Experimental/Non-standard.
+        """
+        ...
 
 if sys.version_info >= (3, 10):
-    def register_adapter(type: type[_T], adapter: _Adapter[_T], /) -> None: ...
-    def register_converter(typename: str, converter: _Converter, /) -> None: ...
+    def register_adapter(type: type[_T], adapter: _Adapter[_T], /) -> None:
+        """Register a function to adapt Python objects to SQLite values."""
+        ...
+    def register_converter(typename: str, converter: _Converter, /) -> None:
+        """Register a function to convert SQLite values to Python objects."""
+        ...
 
 else:
-    def register_adapter(type: type[_T], caster: _Adapter[_T], /) -> None: ...
-    def register_converter(name: str, converter: _Converter, /) -> None: ...
+    def register_adapter(type: type[_T], caster: _Adapter[_T], /) -> None:
+        """
+        register_adapter(type, callable)
+
+        Registers an adapter with pysqlite's adapter registry. Non-standard.
+        """
+        ...
+    def register_converter(name: str, converter: _Converter, /) -> None:
+        """
+        register_converter(typename, callable)
+
+        Registers a converter with pysqlite. Non-standard.
+        """
+        ...
 
 class _AggregateProtocol(Protocol):
     def step(self, value: int, /) -> object: ...
@@ -393,56 +480,146 @@ class Connection:
             uri: bool = ...,
         ) -> None: ...
 
-    def close(self) -> None: ...
+    def close(self) -> None:
+        """Closes the connection."""
+        ...
     if sys.version_info >= (3, 11):
-        def blobopen(self, table: str, column: str, row: int, /, *, readonly: bool = False, name: str = "main") -> Blob: ...
-
-    def commit(self) -> None: ...
-    def create_aggregate(self, name: str, n_arg: int, aggregate_class: Callable[[], _AggregateProtocol]) -> None: ...
+        def blobopen(self, table: str, column: str, row: int, /, *, readonly: bool = False, name: str = "main") -> Blob:
+            """
+            Open and return a BLOB object.
+
+            table
+              Table name.
+            column
+              Column name.
+            row
+              Row index.
+            readonly
+              Open the BLOB without write permissions.
+            name
+              Database name.
+            """
+            ...
+
+    def commit(self) -> None:
+        """Commit the current transaction."""
+        ...
+    def create_aggregate(self, name: str, n_arg: int, aggregate_class: Callable[[], _AggregateProtocol]) -> None:
+        """Creates a new aggregate. Non-standard."""
+        ...
     if sys.version_info >= (3, 11):
         # num_params determines how many params will be passed to the aggregate class. We provide an overload
         # for the case where num_params = 1, which is expected to be the common case.
         @overload
         def create_window_function(
             self, name: str, num_params: Literal[1], aggregate_class: Callable[[], _SingleParamWindowAggregateClass] | None, /
-        ) -> None: ...
+        ) -> None:
+            """
+            Creates or redefines an aggregate window function. Non-standard.
+
+            name
+              The name of the SQL aggregate window function to be created or
+              redefined.
+            num_params
+              The number of arguments the step and inverse methods takes.
+            aggregate_class
+              A class with step(), finalize(), value(), and inverse() methods.
+              Set to None to clear the window function.
+            """
+            ...
         # And for num_params = -1, which means the aggregate must accept any number of parameters.
         @overload
         def create_window_function(
             self, name: str, num_params: Literal[-1], aggregate_class: Callable[[], _AnyParamWindowAggregateClass] | None, /
-        ) -> None: ...
+        ) -> None:
+            """
+            Creates or redefines an aggregate window function. Non-standard.
+
+            name
+              The name of the SQL aggregate window function to be created or
+              redefined.
+            num_params
+              The number of arguments the step and inverse methods takes.
+            aggregate_class
+              A class with step(), finalize(), value(), and inverse() methods.
+              Set to None to clear the window function.
+            """
+            ...
         @overload
         def create_window_function(
             self, name: str, num_params: int, aggregate_class: Callable[[], _WindowAggregateClass] | None, /
-        ) -> None: ...
-
-    def create_collation(self, name: str, callback: Callable[[str, str], int | SupportsIndex] | None, /) -> None: ...
+        ) -> None:
+            """
+            Creates or redefines an aggregate window function. Non-standard.
+
+            name
+              The name of the SQL aggregate window function to be created or
+              redefined.
+            num_params
+              The number of arguments the step and inverse methods takes.
+            aggregate_class
+              A class with step(), finalize(), value(), and inverse() methods.
+              Set to None to clear the window function.
+            """
+            ...
+
+    def create_collation(self, name: str, callback: Callable[[str, str], int | SupportsIndex] | None, /) -> None:
+        """Creates a collation function. Non-standard."""
+        ...
     def create_function(
         self, name: str, narg: int, func: Callable[..., _SqliteData] | None, *, deterministic: bool = False
-    ) -> None: ...
+    ) -> None:
+        """Creates a new function. Non-standard."""
+        ...
     @overload
-    def cursor(self, factory: None = None) -> Cursor: ...
+    def cursor(self, factory: None = None) -> Cursor:
+        """Return a cursor for the connection."""
+        ...
     @overload
-    def cursor(self, factory: Callable[[Connection], _CursorT]) -> _CursorT: ...
-    def execute(self, sql: str, parameters: _Parameters = ..., /) -> Cursor: ...
-    def executemany(self, sql: str, parameters: Iterable[_Parameters], /) -> Cursor: ...
-    def executescript(self, sql_script: str, /) -> Cursor: ...
-    def interrupt(self) -> None: ...
+    def cursor(self, factory: Callable[[Connection], _CursorT]) -> _CursorT:
+        """Return a cursor for the connection."""
+        ...
+    def execute(self, sql: str, parameters: _Parameters = ..., /) -> Cursor:
+        """Executes a SQL statement. Non-standard."""
+        ...
+    def executemany(self, sql: str, parameters: Iterable[_Parameters], /) -> Cursor:
+        """Repeatedly executes a SQL statement. Non-standard."""
+        ...
+    def executescript(self, sql_script: str, /) -> Cursor:
+        """Executes a multiple SQL statements at once. Non-standard."""
+        ...
+    def interrupt(self) -> None:
+        """Abort any pending database operation. Non-standard."""
+        ...
     if sys.version_info >= (3, 13):
         def iterdump(self, *, filter: str | None = None) -> Generator[str, None, None]: ...
     else:
-        def iterdump(self) -> Generator[str, None, None]: ...
+        def iterdump(self) -> Generator[str, None, None]:
+            """Returns iterator to the dump of the database in an SQL text format. Non-standard."""
+            ...
 
-    def rollback(self) -> None: ...
+    def rollback(self) -> None:
+        """Roll back the current transaction."""
+        ...
     def set_authorizer(
         self, authorizer_callback: Callable[[int, str | None, str | None, str | None, str | None], int] | None
-    ) -> None: ...
-    def set_progress_handler(self, progress_handler: Callable[[], int | None] | None, n: int) -> None: ...
-    def set_trace_callback(self, trace_callback: Callable[[str], object] | None) -> None: ...
+    ) -> None:
+        """Sets authorizer callback. Non-standard."""
+        ...
+    def set_progress_handler(self, progress_handler: Callable[[], int | None] | None, n: int) -> None:
+        """Sets progress handler callback. Non-standard."""
+        ...
+    def set_trace_callback(self, trace_callback: Callable[[str], object] | None) -> None:
+        """Sets a trace callback called for each SQL statement (passed as unicode). Non-standard."""
+        ...
     # enable_load_extension and load_extension is not available on python distributions compiled
     # without sqlite3 loadable extension support. see footnotes https://docs.python.org/3/library/sqlite3.html#f1
-    def enable_load_extension(self, enable: bool, /) -> None: ...
-    def load_extension(self, name: str, /) -> None: ...
+    def enable_load_extension(self, enable: bool, /) -> None:
+        """Enable dynamic loading of SQLite extension modules. Non-standard."""
+        ...
+    def load_extension(self, name: str, /) -> None:
+        """Load SQLite extension module. Non-standard."""
+        ...
     def backup(
         self,
         target: Connection,
@@ -451,21 +628,92 @@ class Connection:
         progress: Callable[[int, int, int], object] | None = None,
         name: str = "main",
         sleep: float = 0.25,
-    ) -> None: ...
+    ) -> None:
+        """Makes a backup of the database. Non-standard."""
+        ...
     if sys.version_info >= (3, 11):
-        def setlimit(self, category: int, limit: int, /) -> int: ...
-        def getlimit(self, category: int, /) -> int: ...
-        def serialize(self, *, name: str = "main") -> bytes: ...
-        def deserialize(self, data: ReadableBuffer, /, *, name: str = "main") -> None: ...
+        def setlimit(self, category: int, limit: int, /) -> int:
+            """
+            Set connection run-time limits.
+
+              category
+                The limit category to be set.
+              limit
+                The new limit. If the new limit is a negative number, the limit is
+                unchanged.
+
+            Attempts to increase a limit above its hard upper bound are silently truncated
+            to the hard upper bound. Regardless of whether or not the limit was changed,
+            the prior value of the limit is returned.
+            """
+            ...
+        def getlimit(self, category: int, /) -> int:
+            """
+            Get connection run-time limits.
+
+            category
+              The limit category to be queried.
+            """
+            ...
+        def serialize(self, *, name: str = "main") -> bytes:
+            """
+            Serialize a database into a byte string.
+
+              name
+                Which database to serialize.
+
+            For an ordinary on-disk database file, the serialization is just a copy of the
+            disk file. For an in-memory database or a "temp" database, the serialization is
+            the same sequence of bytes which would be written to disk if that database
+            were backed up to disk.
+            """
+            ...
+        def deserialize(self, data: ReadableBuffer, /, *, name: str = "main") -> None:
+            """
+            Load a serialized database.
+
+              data
+                The serialized database content.
+              name
+                Which database to reopen with the deserialization.
+
+            The deserialize interface causes the database connection to disconnect from the
+            target database, and then reopen it as an in-memory database based on the given
+            serialized data.
+
+            The deserialize interface will fail with SQLITE_BUSY if the database is
+            currently in a read transaction or is involved in a backup operation.
+            """
+            ...
     if sys.version_info >= (3, 12):
-        def getconfig(self, op: int, /) -> bool: ...
-        def setconfig(self, op: int, enable: bool = True, /) -> bool: ...
-
-    def __call__(self, sql: str, /) -> _Statement: ...
-    def __enter__(self) -> Self: ...
+        def getconfig(self, op: int, /) -> bool:
+            """
+            Query a boolean connection configuration option.
+
+            op
+              The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes.
+            """
+            ...
+        def setconfig(self, op: int, enable: bool = True, /) -> bool:
+            """
+            Set a boolean connection configuration option.
+
+            op
+              The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes.
+            """
+            ...
+
+    def __call__(self, sql: str, /) -> _Statement:
+        """Call self as a function."""
+        ...
+    def __enter__(self) -> Self:
+        """For context manager. Non-standard."""
+        ...
     def __exit__(
         self, type: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None, /
-    ) -> Literal[False]: ...
+    ) -> Literal[False]:
+        """For context manager. Non-standard."""
+        ...
 
 class Cursor(Iterator[Any]):
     arraysize: int
@@ -480,19 +728,41 @@ class Cursor(Iterator[Any]):
     @property
     def rowcount(self) -> int: ...
     def __init__(self, cursor: Connection, /) -> None: ...
-    def close(self) -> None: ...
-    def execute(self, sql: str, parameters: _Parameters = (), /) -> Self: ...
-    def executemany(self, sql: str, seq_of_parameters: Iterable[_Parameters], /) -> Self: ...
-    def executescript(self, sql_script: str, /) -> Cursor: ...
-    def fetchall(self) -> list[Any]: ...
-    def fetchmany(self, size: int | None = 1) -> list[Any]: ...
+    def close(self) -> None:
+        """Closes the cursor."""
+        ...
+    def execute(self, sql: str, parameters: _Parameters = (), /) -> Self:
+        """Executes a SQL statement."""
+        ...
+    def executemany(self, sql: str, seq_of_parameters: Iterable[_Parameters], /) -> Self:
+        """Repeatedly executes a SQL statement."""
+        ...
+    def executescript(self, sql_script: str, /) -> Cursor:
+        """Executes a multiple SQL statements at once. Non-standard."""
+        ...
+    def fetchall(self) -> list[Any]:
+        """Fetches all rows from the resultset."""
+        ...
+    def fetchmany(self, size: int | None = 1) -> list[Any]:
+        """Fetches several rows from the resultset."""
+        ...
     # Returns either a row (as created by the row_factory) or None, but
     # putting None in the return annotation causes annoying false positives.
-    def fetchone(self) -> Any: ...
-    def setinputsizes(self, sizes: Unused, /) -> None: ...  # does nothing
-    def setoutputsize(self, size: Unused, column: Unused = None, /) -> None: ...  # does nothing
-    def __iter__(self) -> Self: ...
-    def __next__(self) -> Any: ...
+    def fetchone(self) -> Any:
+        """Fetches one row from the resultset."""
+        ...
+    def setinputsizes(self, sizes: Unused, /) -> None:
+        """Required by DB-API. Does nothing in pysqlite."""
+        ...
+    def setoutputsize(self, size: Unused, column: Unused = None, /) -> None:
+        """Required by DB-API. Does nothing in pysqlite."""
+        ...
+    def __iter__(self) -> Self:
+        """Implement iter(self)."""
+        ...
+    def __next__(self) -> Any:
+        """Implement next(self)."""
+        ...
 
 class Error(Exception):
     if sys.version_info >= (3, 11):
@@ -518,21 +788,45 @@ class ProgrammingError(DatabaseError): ...
 
 class Row:
     def __init__(self, cursor: Cursor, data: tuple[Any, ...], /) -> None: ...
-    def keys(self) -> list[str]: ...
+    def keys(self) -> list[str]:
+        """Returns the keys of the row."""
+        ...
     @overload
-    def __getitem__(self, key: int | str, /) -> Any: ...
+    def __getitem__(self, key: int | str, /) -> Any:
+        """Return self[key]."""
+        ...
     @overload
-    def __getitem__(self, key: slice, /) -> tuple[Any, ...]: ...
-    def __hash__(self) -> int: ...
-    def __iter__(self) -> Iterator[Any]: ...
-    def __len__(self) -> int: ...
+    def __getitem__(self, key: slice, /) -> tuple[Any, ...]:
+        """Return self[key]."""
+        ...
+    def __hash__(self) -> int:
+        """Return hash(self)."""
+        ...
+    def __iter__(self) -> Iterator[Any]:
+        """Implement iter(self)."""
+        ...
+    def __len__(self) -> int:
+        """Return len(self)."""
+        ...
     # These return NotImplemented for anything that is not a Row.
-    def __eq__(self, value: object, /) -> bool: ...
-    def __ge__(self, value: object, /) -> bool: ...
-    def __gt__(self, value: object, /) -> bool: ...
-    def __le__(self, value: object, /) -> bool: ...
-    def __lt__(self, value: object, /) -> bool: ...
-    def __ne__(self, value: object, /) -> bool: ...
+    def __eq__(self, value: object, /) -> bool:
+        """Return self==value."""
+        ...
+    def __ge__(self, value: object, /) -> bool:
+        """Return self>=value."""
+        ...
+    def __gt__(self, value: object, /) -> bool:
+        """Return self>value."""
+        ...
+    def __le__(self, value: object, /) -> bool:
+        """Return self<=value."""
+        ...
+    def __lt__(self, value: object, /) -> bool:
+        """Return self<value."""
+        ...
+    def __ne__(self, value: object, /) -> bool:
+        """Return self!=value."""
+        ...
 
 @final
 class _Statement: ...
@@ -542,14 +836,54 @@ class Warning(Exception): ...
 if sys.version_info >= (3, 11):
     @final
     class Blob:
-        def close(self) -> None: ...
-        def read(self, length: int = -1, /) -> bytes: ...
-        def write(self, data: ReadableBuffer, /) -> None: ...
-        def tell(self) -> int: ...
+        def close(self) -> None:
+            """Close the blob."""
+            ...
+        def read(self, length: int = -1, /) -> bytes:
+            """
+            Read data at the current offset position.
+
+              length
+                Read length in bytes.
+
+            If the end of the blob is reached, the data up to end of file will be returned.
+            When length is not specified, or is negative, Blob.read() will read until the
+            end of the blob.
+            """
+            ...
+        def write(self, data: ReadableBuffer, /) -> None:
+            """
+            Write data at the current offset.
+
+            This function cannot change the blob length.  Writing beyond the end of the
+            blob will result in an exception being raised.
+            """
+            ...
+        def tell(self) -> int:
+            """Return the current access position for the blob."""
+            ...
         # whence must be one of os.SEEK_SET, os.SEEK_CUR, os.SEEK_END
-        def seek(self, offset: int, origin: int = 0, /) -> None: ...
-        def __len__(self) -> int: ...
-        def __enter__(self) -> Self: ...
-        def __exit__(self, type: object, val: object, tb: object, /) -> Literal[False]: ...
-        def __getitem__(self, key: SupportsIndex | slice, /) -> int: ...
-        def __setitem__(self, key: SupportsIndex | slice, value: int, /) -> None: ...
+        def seek(self, offset: int, origin: int = 0, /) -> None:
+            """
+            Set the current access position to offset.
+
+            The origin argument defaults to os.SEEK_SET (absolute blob positioning).
+            Other values for origin are os.SEEK_CUR (seek relative to the current position)
+            and os.SEEK_END (seek relative to the blob's end).
+            """
+            ...
+        def __len__(self) -> int:
+            """Return len(self)."""
+            ...
+        def __enter__(self) -> Self:
+            """Blob context manager enter."""
+            ...
+        def __exit__(self, type: object, val: object, tb: object, /) -> Literal[False]:
+            """Blob context manager exit."""
+            ...
+        def __getitem__(self, key: SupportsIndex | slice, /) -> int:
+            """Return self[key]."""
+            ...
+        def __setitem__(self, key: SupportsIndex | slice, value: int, /) -> None:
+            """Set self[key] to value."""
+            ...