# This file is generated by rst2docstring import sys from typing import Union, Tuple, List, Optional, Callable, Any, Dict, \ Iterator, Sequence, Literal, Set from collections.abc import Mapping import array import types if sys.version_info >= (3, 8): from typing import Protocol SQLiteValue = Union[None, int, float, bytes, str] """SQLite supports 5 types - None (NULL), 64 bit signed int, 64 bit float, bytes, and str (unicode text)""" SQLiteValues = Union[Tuple[()], Tuple[SQLiteValue, ...]] "A sequence of zero or more SQLiteValue" Bindings = Union[Sequence[Union[SQLiteValue, zeroblob]], Mapping[str, Union[SQLiteValue, zeroblob]]] """Query bindings are either a sequence of SQLiteValue, or a dict mapping names to SQLiteValues. You can also provide zeroblob in Bindings. You can use dict subclasses or any type registered with :class:`collections.abc.Mapping` for named bindings""" # Neither TypeVar nor ParamSpec work, when either should AggregateT = Any "An object provided as first parameter of step and final aggregate functions" AggregateStep = Union [ Callable[[AggregateT], None], Callable[[AggregateT, SQLiteValue], None], Callable[[AggregateT, SQLiteValue, SQLiteValue], None], Callable[[AggregateT, SQLiteValue, SQLiteValue, SQLiteValue], None], Callable[[AggregateT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], None], Callable[[AggregateT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], None], Callable[[AggregateT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], None], ] "AggregateStep is called on each matching row with the relevant number of SQLiteValue" AggregateFinal= Callable[[AggregateT], SQLiteValue] "Final is called after all matching rows have been processed by step, and returns a SQLiteValue" AggregateFactory = Callable[[], Tuple[AggregateT, AggregateStep, AggregateFinal]] """Called each time for the start of a new calculation using an aggregate function, returning an object, a step function and a final function""" ScalarProtocol = Union [ Callable[[], SQLiteValue], Callable[[SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue] ] """Scalar callbacks take zero or more SQLiteValues, and return a SQLiteValue""" if sys.version_info >= (3, 8): class WindowClass(Protocol): "Represents a running window function" def step(self, param: SQLiteValue) -> None: "Adds the param(s) to the window" ... def final(self) -> SQLiteValue: "Finishes the function and returns final value" ... def value(self) -> SQLiteValue: "Returns the current value" ... def inverse(self, param: SQLiteValue) -> None: "Removes the param(s) from the window" ... WindowT = Any "An object provided as first parameter of the 4 window functions, if not using class based callbacks" WindowStep = Union[ Callable[[WindowT], None], Callable[[WindowT, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], None] ] """Window function step takes zero or more SQLiteValues""" WindowFinal = Union[ Callable[[WindowT], SQLiteValue], Callable[[WindowT, SQLiteValue], SQLiteValue], Callable[[WindowT, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], SQLiteValue] ] """Window function final takes zero or more SQLiteValues, and returns a SQLiteValue""" WindowValue = Callable[[WindowT], SQLiteValue] """Window function value returns the current SQLiteValue""" WindowInverse = Union[ Callable[[WindowT], None], Callable[[WindowT, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue], None], Callable[[WindowT, SQLiteValue, SQLiteValue, SQLiteValue, SQLiteValue], None] ] """Window function inverse takes zero or more SQLiteValues""" WindowFactory = Callable[[], Union[WindowClass, Tuple[WindowT, WindowStep, WindowFinal, WindowValue, WindowInverse]]] """Called each time at the start of a new window function execution. It should return either an object with relevant methods or an object used as the first parameter and the 4 methods""" RowTracer = Callable[[Cursor, SQLiteValues], Any] """Row tracers are called with the Cursor, and the row that would be returned. If you return None, then no row is returned, otherwise whatever is returned is returned as a result row for the query""" ExecTracer = Callable[[Cursor, str, Optional[Bindings]], bool] """Execution tracers are called with the cursor, sql query text, and the bindings used. Return False/None to abort execution, or True to continue""" Authorizer = Callable[[int, Optional[str], Optional[str], Optional[str], Optional[str]], int] """Authorizers are called with an operation code and 4 strings (which could be None) depending on the operatation. Return SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE""" CommitHook = Callable[[], bool] """Commit hook is called with no arguments and should return True to abort the commit and False to let it continue""" SQLITE_VERSION_NUMBER: int """The integer version number of SQLite that APSW was compiled against. For example SQLite 3.6.4 will have the value *3006004*. This number may be different than the actual library in use if the library is shared and has been updated. Call :meth:`sqlitelibversion` to get the actual library version.""" def apswversion() -> str: """Returns the APSW version.""" ... compile_options: Tuple[str, ...] """A tuple of the options used to compile SQLite. For example it will be something like this:: ('ENABLE_LOCKING_STYLE=0', 'TEMP_STORE=1', 'THREADSAFE=1') Calls: `sqlite3_compileoption_get `__""" def complete(statement: str) -> bool: """Returns True if the input string comprises one or more complete SQL statements by looking for an unquoted trailing semi-colon. An example use would be if you were prompting the user for SQL statements and needed to know if you had a whole statement, or needed to ask for another line:: statement = input("SQL> ") while not apsw.complete(statement): more = input(" .. ") statement = statement + "\\n" + more Calls: `sqlite3_complete `__""" ... def config(op: int, *args: Any) -> None: """:param op: A `configuration operation `_ :param args: Zero or more arguments as appropriate for *op* Many operations don't make sense from a Python program. The following configuration operations are supported: SQLITE_CONFIG_LOG, SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_URI, SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_COVERING_INDEX_SCAN, SQLITE_CONFIG_PCACHE_HDRSZ, SQLITE_CONFIG_PMASZ, and SQLITE_CONFIG_STMTJRNL_SPILL. See :ref:`tips ` for an example of how to receive log messages (SQLITE_CONFIG_LOG) Calls: `sqlite3_config `__""" ... connection_hooks: List[Callable[[Connection], None]] """The purpose of the hooks is to allow the easy registration of :meth:`functions `, :ref:`virtual tables ` or similar items with each :class:`Connection` as it is created. The default value is an empty list. Whenever a Connection is created, each item in apsw.connection_hooks is invoked with a single parameter being the new Connection object. If the hook raises an exception then the creation of the Connection fails. If you wanted to store your own defined functions in the database then you could define a hook that looked in the relevant tables, got the Python text and turned it into the functions.""" def enablesharedcache(enable: bool) -> None: """If you use the same :class:`Connection` across threads or use multiple :class:`connections ` accessing the same file, then SQLite can `share the cache between them `_. It is :ref:`not recommended ` that you use this. Calls: `sqlite3_enable_shared_cache `__""" ... def exceptionfor(code: int) -> Exception: """If you would like to raise an exception that corresponds to a particular SQLite `error code `_ then call this function. It also understands `extended error codes `_. For example to raise `SQLITE_IOERR_ACCESS `_:: raise apsw.exceptionfor(apsw.SQLITE_IOERR_ACCESS)""" ... def fork_checker() -> None: """**Note** This method is not available on Windows as it does not support the fork system call. SQLite does not allow the use of database connections across `forked `__ processes (see the `SQLite FAQ Q6 `__). (Forking creates a child process that is a duplicate of the parent including the state of all data structures in the program. If you do this to SQLite then parent and child would both consider themselves owners of open databases and silently corrupt each other's work and interfere with each other's locks.) One example of how you may end up using fork is if you use the `multiprocessing module `__ which uses fork to make child processes. If you do use fork or multiprocessing on a platform that supports fork then you **must** ensure database connections and their objects (cursors, backup, blobs etc) are not used in the parent process, or are all closed before calling fork or starting a `Process `__. (Note you must call close to ensure the underlying SQLite objects are closed. It is also a good idea to call `gc.collect(2) `__ to ensure anything you may have missed is also deallocated.) Once you run this method, extra checking code is inserted into SQLite's mutex operations (at a very small performance penalty) that verifies objects are not used across processes. You will get a :exc:`ForkingViolationError` if you do so. Note that due to the way Python's internals work, the exception will be delivered to `sys.excepthook` in addition to the normal exception mechanisms and may be reported by Python after the line where the issue actually arose. (Destructors of objects you didn't close also run between lines.) You should only call this method as the first line after importing APSW, as it has to shutdown and re-initialize SQLite. If you have any SQLite objects already allocated when calling the method then the program will later crash. The recommended use is to use the fork checking as part of your test suite.""" ... def format_sql_value(value: SQLiteValue) -> str: """Returns a Python string representing the supplied value in SQL syntax.""" ... def hard_heap_limit(limit: int) -> int: """Enforces SQLite keeping memory usage below *limit* bytes and returns the previous limit. .. seealso:: :meth:`softheaplimit` Calls: `sqlite3_hard_heap_limit64 `__""" ... def initialize() -> None: """It is unlikely you will want to call this method as SQLite automatically initializes. Calls: `sqlite3_initialize `__""" ... keywords: Set[str] """A set containing every SQLite keyword Calls: * `sqlite3_keyword_count `__ * `sqlite3_keyword_name `__""" def log(errorcode: int, message: str) -> None: """Calls the SQLite logging interface. Note that you must format the message before passing it to this method:: apsw.log(apsw.SQLITE_NOMEM, f"Need { needed } bytes of memory") See :ref:`tips ` for an example of how to receive log messages. Calls: `sqlite3_log `__""" ... def memoryhighwater(reset: bool = False) -> int: """Returns the maximum amount of memory SQLite has used. If *reset* is True then the high water mark is reset to the current value. .. seealso:: :meth:`status` Calls: `sqlite3_memory_highwater `__""" ... def memoryused() -> int: """Returns the amount of memory SQLite is currently using. .. seealso:: :meth:`status` Calls: `sqlite3_memory_used `__""" ... def randomness(amount: int) -> bytes: """Gets random data from SQLite's random number generator. :param amount: How many bytes to return Calls: `sqlite3_randomness `__""" ... def releasememory(amount: int) -> int: """Requests SQLite try to free *amount* bytes of memory. Returns how many bytes were freed. Calls: `sqlite3_release_memory `__""" ... def set_default_vfs(name: str) -> None: """Sets the default vfs to *name* which must be an existing vfs. See :meth:`vfsnames`. Calls: * `sqlite3_vfs_register `__ * `sqlite3_vfs_find `__""" ... def shutdown() -> None: """It is unlikely you will want to call this method and there is no need to do so. It is a **really** bad idea to call it unless you are absolutely sure all :class:`connections `, :class:`blobs `, :class:`cursors `, :class:`vfs ` etc have been closed, deleted and garbage collected. Calls: `sqlite3_shutdown `__""" ... def softheaplimit(limit: int) -> int: """Requests SQLite try to keep memory usage below *limit* bytes and returns the previous limit. .. seealso:: :meth:`hard_heap_limit` Calls: `sqlite3_soft_heap_limit64 `__""" ... def sqlite3_sourceid() -> str: """Returns the exact checkin information for the SQLite 3 source being used. Calls: `sqlite3_sourceid `__""" ... def sqlitelibversion() -> str: """Returns the version of the SQLite library. This value is queried at run time from the library so if you use shared libraries it will be the version in the shared library. Calls: `sqlite3_libversion `__""" ... def status(op: int, reset: bool = False) -> Tuple[int, int]: """Returns current and highwater measurements. :param op: A `status parameter `_ :param reset: If *True* then the highwater is set to the current value :returns: A tuple of current value and highwater value .. seealso:: * :ref:`Status example ` Calls: `sqlite3_status64 `__""" ... def strglob(glob: str, string: str) -> int: """Does string GLOB matching. Note that zero is returned on on a match. Calls: `sqlite3_strglob `__""" ... def stricmp(string1: str, string2: str) -> int: """Does string case-insensitive comparison. Note that zero is returned on on a match. Calls: `sqlite3_stricmp `__""" ... def strlike(glob: str, string: str, escape: int = 0) -> int: """Does string LIKE matching. Note that zero is returned on on a match. Calls: `sqlite3_strlike `__""" ... def strnicmp(string1: str, string2: str, count: int) -> int: """Does string case-insensitive comparison. Note that zero is returned on on a match. Calls: `sqlite3_strnicmp `__""" ... def unregister_vfs(name: str) -> None: """Unregisters the named vfs. See :meth:`vfsnames`. Calls: * `sqlite3_vfs_unregister `__ * `sqlite3_vfs_find `__""" ... using_amalgamation: bool """If True then `SQLite amalgamation `__ is in use (statically compiled into APSW). Using the amalgamation means that SQLite shared libraries are not used and will not affect your code.""" def vfsnames() -> List[str]: """Returns a list of the currently installed :ref:`vfs `. The first item in the list is the default vfs.""" ... class Backup: """You create a backup instance by calling :meth:`Connection.backup`.""" def close(self, force: bool = False) -> None: """Does the same thing as :meth:`~Backup.finish`. This extra api is provided to give the same api as other APSW objects such as :meth:`Connection.close`, :meth:`Blob.close` and :meth:`Cursor.close`. It is safe to call this method multiple times. :param force: If true then any exceptions are ignored.""" ... done: bool """A boolean that is True if the copy completed in the last call to :meth:`~Backup.step`.""" def __enter__(self) -> Backup: """You can use the backup object as a `context manager `_ as defined in :pep:`0343`. The :meth:`~Backup.__exit__` method ensures that backup is :meth:`finished `.""" ... def __exit__(self, etype: Optional[type[BaseException]], evalue: Optional[BaseException], etraceback: Optional[types.TracebackType]) -> Optional[bool]: """Implements context manager in conjunction with :meth:`~Backup.__enter__` ensuring that the copy is :meth:`finished `.""" ... def finish(self) -> None: """Completes the copy process. If all pages have been copied then the transaction is committed on the destination database, otherwise it is rolled back. This method must be called for your backup to take effect. The backup object will always be finished even if there is an exception. It is safe to call this method multiple times. Calls: `sqlite3_backup_finish `__""" ... pagecount: int """Read only. How many pages were in the source database after the last step. If you haven't called :meth:`~Backup.step` or the backup object has been :meth:`finished ` then zero is returned. Calls: `sqlite3_backup_pagecount `__""" remaining: int """Read only. How many pages were remaining to be copied after the last step. If you haven't called :meth:`~Backup.step` or the backup object has been :meth:`finished ` then zero is returned. Calls: `sqlite3_backup_remaining `__""" def step(self, npages: int = -1) -> bool: """Copies *npages* pages from the source to destination database. The source database is locked during the copy so using smaller values allows other access to the source database. The destination database is always locked until the backup object is :meth:`finished `. :param npages: How many pages to copy. If the parameter is omitted or negative then all remaining pages are copied. The default page size is 1024 bytes (1kb) which can be changed before database creation using a `pragma `_. This method may throw a :exc:`BusyError` or :exc:`LockedError` if unable to lock the source database. You can catch those and try again. :returns: True if this copied the last remaining outstanding pages, else false. This is the same value as :attr:`~Backup.done` Calls: `sqlite3_backup_step `__""" ... class Blob: """This object is created by :meth:`Connection.blobopen` and provides access to a blob in the database. It behaves like a Python file. At the C level it wraps a `sqlite3_blob `_. .. note:: You cannot change the size of a blob using this object. You should create it with the correct size in advance either by using :class:`zeroblob` or the `zeroblob() `_ function. See the :ref:`example `.""" def close(self, force: bool = False) -> None: """Closes the blob. Note that even if an error occurs the blob is still closed. .. note:: In some cases errors that technically occurred in the :meth:`~Blob.read` and :meth:`~Blob.write` routines may not be reported until close is called. Similarly errors that occurred in those methods (eg calling :meth:`~Blob.write` on a read-only blob) may also be re-reported in :meth:`~Blob.close`. (This behaviour is what the underlying SQLite APIs do - it is not APSW doing it.) It is okay to call :meth:`~Blob.close` multiple times. :param force: Ignores any errors during close. Calls: `sqlite3_blob_close `__""" ... def __enter__(self) -> Blob: """You can use a blob as a `context manager `_ as defined in :pep:`0343`. When you use *with* statement, the blob is always :meth:`closed ` on exit from the block, even if an exception occurred in the block. For example:: with connection.blobopen() as blob: blob.write("...") res=blob.read(1024)""" ... def __exit__(self, etype: Optional[type[BaseException]], evalue: Optional[BaseException], etraceback: Optional[types.TracebackType]) -> Optional[bool]: """Implements context manager in conjunction with :meth:`~Blob.__enter__`. Any exception that happened in the *with* block is raised after closing the blob.""" ... def length(self) -> int: """Returns the size of the blob in bytes. Calls: `sqlite3_blob_bytes `__""" ... def read(self, length: int = -1) -> bytes: """Reads amount of data requested, or till end of file, whichever is earlier. Attempting to read beyond the end of the blob returns an empty bytes in the same manner as end of file on normal file objects. Negative numbers read remaining data. Calls: `sqlite3_blob_read `__""" ... def readinto(self, buffer: Union[bytearray, array.array[Any], memoryview], offset: int = 0, length: int = -1) -> None: """Reads from the blob into a buffer you have supplied. This method is useful if you already have a buffer like object that data is being assembled in, and avoids allocating results in :meth:`Blob.read` and then copying into buffer. :param buffer: A writable buffer like object. There is a bytearray type that is very useful. `arrays `__ also work. :param offset: The position to start writing into the buffer defaulting to the beginning. :param length: How much of the blob to read. The default is the remaining space left in the buffer. Note that if there is more space available than blob left then you will get a *ValueError* exception. Calls: `sqlite3_blob_read `__""" ... def reopen(self, rowid: int) -> None: """Change this blob object to point to a different row. It can be faster than closing an existing blob an opening a new one. Calls: `sqlite3_blob_reopen `__""" ... def seek(self, offset: int, whence: int = 0) -> None: """Changes current position to *offset* biased by *whence*. :param offset: New position to seek to. Can be positive or negative number. :param whence: Use 0 if *offset* is relative to the beginning of the blob, 1 if *offset* is relative to the current position, and 2 if *offset* is relative to the end of the blob. :raises ValueError: If the resulting offset is before the beginning (less than zero) or beyond the end of the blob.""" ... def tell(self) -> int: """Returns the current offset.""" ... def write(self, data: bytes) -> None: """Writes the data to the blob. :param data: bytes to write :raises TypeError: Wrong data type :raises ValueError: If the data would go beyond the end of the blob. You cannot increase the size of a blob by writing beyond the end. You need to use :class:`zeroblob` to set the desired size first when inserting the blob. Calls: `sqlite3_blob_write `__""" ... class Connection: """This object wraps a `sqlite3 pointer `_.""" authorizer: Optional[Authorizer] """While `preparing `_ statements, SQLite will call any defined authorizer to see if a particular action is ok to be part of the statement. Typical usage would be if you are running user supplied SQL and want to prevent harmful operations. You should also set the :class:`statementcachesize ` to zero. The authorizer callback has 5 parameters: * An `operation code `_ * A string (or None) dependent on the operation `(listed as 3rd) `_ * A string (or None) dependent on the operation `(listed as 4th) `_ * A string name of the database (or None) * Name of the innermost trigger or view doing the access (or None) The authorizer callback should return one of *SQLITE_OK*, *SQLITE_DENY* or *SQLITE_IGNORE*. (*SQLITE_DENY* is returned if there is an error in your Python code). .. seealso:: * :ref:`Example ` * :ref:`statementcache` Calls: `sqlite3_set_authorizer `__""" def autovacuum_pages(self, callable: Optional[Callable[[str, int, int, int], int]]) -> None: """Calls `callable` to find out how many pages to autovacuum. The callback has 4 parameters: * Database name: str (eg "main") * Database pages: int (how many pages make up the database now) * Free pages: int (how many pages could be freed) * Page size: int (page size in bytes) Return how many pages should be freed. Values less than zero or more than the free pages are treated as zero or free page count. On error zero is returned. READ THE NOTE IN THE SQLITE DOCUMENTATION. Calling into SQLite can result in crashes, corrupt databases or worse. Calls: `sqlite3_autovacuum_pages `__""" ... def backup(self, databasename: str, sourceconnection: Connection, sourcedatabasename: str) -> Backup: """Opens a :ref:`backup object `. All data will be copied from source database to this database. :param databasename: Name of the database. This will be ``main`` for the main connection and the name you specified for `attached `_ databases. :param sourceconnection: The :class:`Connection` to copy a database from. :param sourcedatabasename: Name of the database in the source (eg ``main``). :rtype: :class:`backup` .. seealso:: * :ref:`Backup` Calls: `sqlite3_backup_init `__""" ... def blobopen(self, database: str, table: str, column: str, rowid: int, writeable: bool) -> Blob: """Opens a blob for :ref:`incremental I/O `. :param database: Name of the database. This will be ``main`` for the main connection and the name you specified for `attached `_ databases. :param table: The name of the table :param column: The name of the column :param rowid: The id that uniquely identifies the row. :param writeable: If True then you can read and write the blob. If False then you can only read it. :rtype: :class:`Blob` .. seealso:: * :ref:`Blob I/O example ` * `SQLite row ids `_ Calls: `sqlite3_blob_open `__""" ... def cache_stats(self, include_entries: bool = False) -> Dict[str, int]: """Returns information about the statement cache as dict. .. note:: Calling execute with "select a; select b; insert into c ..." will result in 3 cache entries corresponding to each of the 3 queries present. The returned dictionary has the following information. .. list-table:: :header-rows: 1 :widths: auto * - Key - Explanation * - size - Maximum number of entries in the cache * - evictions - How many entries were removed (expired) to make space for a newer entry * - no_cache - Queries that had can_cache parameter set to False * - hits - A match was found in the cache * - misses - No match was found in the cache, or the cache couldn't be used * - no_vdbe - The statement was empty (eg a comment) or SQLite took action during parsing (eg some pragmas). These are not cached and also included in the misses count * - too_big - UTF8 query size was larger than considered for caching. These are also included in the misses count. * - max_cacheable_bytes - Maximum size of query (in bytes of utf8) that will be considered for caching * - entries - (Only present if `include_entries` is True) A list of the cache entries If `entries` is present, then each list entry is a dict with the following information. .. list-table:: :header-rows: 1 :widths: auto * - Key - Explanation * - query - Text of the query itself (first statement only) * - prepare_flags - Flags passed to `sqlite3_prepare_v3 `__ for this query * - uses - How many times this entry has been (re)used * - has_more - Boolean indicating if there was more query text than the first statement""" ... def cacheflush(self) -> None: """Flushes caches to disk mid-transaction. Calls: `sqlite3_db_cacheflush `__""" ... def changes(self) -> int: """Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. Calls: `sqlite3_changes64 `__""" ... def close(self, force: bool = False) -> None: """Closes the database. If there are any outstanding :class:`cursors `, :class:`blobs ` or :class:`backups ` then they are closed too. It is normally not necessary to call this method as the database is automatically closed when there are no more references. It is ok to call the method multiple times. If your user defined functions or collations have direct or indirect references to the Connection then it won't be automatically garbage collected because of circular referencing that can't be automatically broken. Calling *close* will free all those objects and what they reference. SQLite is designed to survive power failures at even the most awkward moments. Consequently it doesn't matter if it is closed when the process is exited, or even if the exit is graceful or abrupt. In the worst case of having a transaction in progress, that transaction will be rolled back by the next program to open the database, reverting the database to a know good state. If *force* is *True* then any exceptions are ignored. Calls: `sqlite3_close `__""" ... def collationneeded(self, callable: Optional[Callable[[Connection, str], None]]) -> None: """*callable* will be called if a statement requires a `collation `_ that hasn't been registered. Your callable will be passed two parameters. The first is the connection object. The second is the name of the collation. If you have the collation code available then call :meth:`Connection.createcollation`. This is useful for creating collations on demand. For example you may include the `locale `_ in the collation name, but since there are thousands of locales in popular use it would not be useful to :meth:`prereigster ` them all. Using :meth:`~Connection.collationneeded` tells you when you need to register them. .. seealso:: * :meth:`~Connection.createcollation` Calls: `sqlite3_collation_needed `__""" ... def column_metadata(self, dbname: Optional[str], table_name: str, column_name: str) -> Tuple[str, str, bool, bool, bool]: """`dbname` is the specific database (eg "main", "temp") or None to search all databases. The returned :class:`tuple` has these fields: 0: str - declared data type 1: str - name of default collation sequence 2: bool - True if not null constraint 3: bool - True if part of primary key 4: bool - True if column is `autoincrement `__ Calls: `sqlite3_table_column_metadata `__""" ... def config(self, op: int, *args: int) -> int: """:param op: A `configuration operation `__ :param args: Zero or more arguments as appropriate for *op* Only optiona that take an int and return one are implemented. Calls: `sqlite3_db_config `__""" ... def create_window_function(self, name:str, factory: Optional[WindowFactory], numargs: int =-1, *, flags: int = 0) -> None: """Registers a `window function `__ :param name: The string name of the function. It should be less than 255 characters :param factory: Called to start a new window. Use None to delete the function. :param numargs: How many arguments the function takes, with -1 meaning any number :param flags: `Function flags `__ You need to provide callbacks for the ``step``, ``final``, ``value`` and ``inverse`` methods. This can be done by having `factory` as a class, and the corresponding method names, or by having `factory` return a sequence of a first parameter, and then each of the 4 functions. **Debugging note** SQlite always calls the ``final`` method to allow for cleanup. If you have an error in one of the other methods, then ``final`` will also be called, and you may see both methods in tracebacks. .. seealso:: * :ref:`Example ` * :meth:`~Connection.createaggregatefunction` Calls: `sqlite3_create_window_function `__""" ... def createaggregatefunction(self, name: str, factory: Optional[AggregateFactory], numargs: int = -1, *, flags: int = 0) -> None: """Registers an aggregate function. Aggregate functions operate on all the relevant rows such as counting how many there are. :param name: The string name of the function. It should be less than 255 characters :param factory: The function that will be called. Use None to delete the function. :param numargs: How many arguments the function takes, with -1 meaning any number :param flags: `Function flags `__ When a query starts, the *factory* will be called and must return a tuple of 3 items: a context object This can be of any type a step function This function is called once for each row. The first parameter will be the context object and the remaining parameters will be from the SQL statement. Any value returned will be ignored. a final function This function is called at the very end with the context object as a parameter. The value returned is set as the return for the function. The final function is always called even if an exception was raised by the step function. This allows you to ensure any resources are cleaned up. .. note:: You can register the same named function but with different callables and *numargs*. See :meth:`~Connection.createscalarfunction` for an example. .. seealso:: * :ref:`Example ` * :meth:`~Connection.createscalarfunction` Calls: `sqlite3_create_function_v2 `__""" ... def createcollation(self, name: str, callback: Optional[Callable[[str, str], int]]) -> None: """You can control how SQLite sorts (termed `collation `_) when giving the ``COLLATE`` term to a `SELECT `_. For example your collation could take into account locale or do numeric sorting. The *callback* will be called with two items. It should return -1 if the first is less then the second, 0 if they are equal, and 1 if first is greater:: def mycollation(one, two): if one < two: return -1 if one == two: return 0 if one > two: return 1 Passing None as the callback will unregister the collation. .. seealso:: * :ref:`Example ` Calls: `sqlite3_create_collation_v2 `__""" ... def createmodule(self, name: str, datasource: Optional[VTModule]) -> None: """Registers a virtual table, or drops it if *datasource* is *None*. See :ref:`virtualtables` for details. .. seealso:: * :ref:`Example ` Calls: `sqlite3_create_module_v2 `__""" ... def createscalarfunction(self, name: str, callable: Optional[ScalarProtocol], numargs: int = -1, *, deterministic: bool = False, flags: int = 0) -> None: """Registers a scalar function. Scalar functions operate on one set of parameters once. :param name: The string name of the function. It should be less than 255 characters :param callable: The function that will be called. Use None to unregister. :param numargs: How many arguments the function takes, with -1 meaning any number :param deterministic: When True this means the function always returns the same result for the same input arguments. SQLite's query planner can perform additional optimisations for deterministic functions. For example a random() function is not deterministic while one that returns the length of a string is. :param flags: Additional `function flags `__ .. note:: You can register the same named function but with different *callable* and *numargs*. For example:: connection.createscalarfunction("toip", ipv4convert, 4) connection.createscalarfunction("toip", ipv6convert, 16) connection.createscalarfunction("toip", strconvert, -1) The one with the correct *numargs* will be called and only if that doesn't exist then the one with negative *numargs* will be called. .. seealso:: * :ref:`Example ` * :meth:`~Connection.createaggregatefunction` Calls: `sqlite3_create_function_v2 `__""" ... def cursor(self) -> Cursor: """Creates a new :class:`Cursor` object on this database. :rtype: :class:`Cursor`""" ... cursor_factory: Callable[[Connection], Any] """Defaults to :class:`Cursor` Called with a :class:`Connection` as the only parameter when a cursor is needed such as by the :meth:`cursor` method, or :meth:`Connection.execute`. Note that whatever is returned doesn't have to be an actual :class:`Cursor` instance, and just needs to have the methods present that are actually called. These are likely to be `execute`, `executemany`, `close` etc.""" def db_filename(self, name: str) -> str: """Returns the full filename of the named (attached) database. The main database is named "main". Calls: `sqlite3_db_filename `__""" ... def db_names(self) -> List[str]: """Returns the list of database names. For example the first database is named 'main', the next 'temp', and the rest with the name provided in `ATTACH `__ Calls: `sqlite3_db_name `__""" ... def deserialize(self, name: str, contents: bytes) -> None: """Replaces the named database with an in-memory copy of *contents*. *name* is **"main"** for the main database, **"temp"** for the temporary database etc. The resulting database is in-memory, read-write, and the memory is owned, resized, and freed by SQLite. .. seealso:: * :meth:`Connection.serialize` Calls: `sqlite3_deserialize `__""" ... def drop_modules(self, keep: Optional[Sequence[str]]) -> None: """If *keep* is *None* then all registered virtual tables are dropped. Otherwise *keep* is a sequence of strings, naming the virtual tables that are kept, dropping all others.""" ... def enableloadextension(self, enable: bool) -> None: """Enables/disables `extension loading `_ which is disabled by default. :param enable: If True then extension loading is enabled, else it is disabled. Calls: `sqlite3_enable_load_extension `__ .. seealso:: * :meth:`~Connection.loadextension`""" ... def __enter__(self) -> Connection: """You can use the database as a `context manager `_ as defined in :pep:`0343`. When you use *with* a transaction is started. If the block finishes with an exception then the transaction is rolled back, otherwise it is committed. For example:: with connection: connection.execute("....") with connection: # nested is supported call_function(connection) connection.execute("...") with connection as db: # You can also use 'as' call_function2(db) db.execute("...") Behind the scenes the `savepoint `_ functionality introduced in SQLite 3.6.8 is used to provide nested transactions.""" ... exectrace: Optional[ExecTracer] """Called with the cursor, statement and bindings for each :meth:`~Cursor.execute` or :meth:`~Cursor.executemany` on this Connection, unless the :class:`Cursor` installed its own tracer. Your execution tracer can also abort execution of a statement. If *callable* is *None* then any existing execution tracer is removed. .. seealso:: * :ref:`tracing` * :ref:`rowtracer` * :attr:`Cursor.exectrace`""" def execute(self, statements: str, bindings: Optional[Bindings] = None, *, can_cache: bool = True, prepare_flags: int = 0) -> Cursor: """Executes the statements using the supplied bindings. Execution returns when the first row is available or all statements have completed. (A cursor is automatically obtained). See :meth:`Cursor.execute` for more details.""" ... def executemany(self, statements: str, sequenceofbindings:Sequence[Bindings], *, can_cache: bool = True, prepare_flags: int = 0) -> Cursor: """This method is for when you want to execute the same statements over a sequence of bindings, such as inserting into a database. (A cursor is automatically obtained). See :meth:`Cursor.executemany` for more details.""" ... def __exit__(self, etype: Optional[type[BaseException]], evalue: Optional[BaseException], etraceback: Optional[types.TracebackType]) -> Optional[bool]: """Implements context manager in conjunction with :meth:`~Connection.__enter__`. Any exception that happened in the *with* block is raised after committing or rolling back the savepoint.""" ... def filecontrol(self, dbname: str, op: int, pointer: int) -> bool: """Calls the :meth:`~VFSFile.xFileControl` method on the :ref:`VFS` implementing :class:`file access ` for the database. :param dbname: The name of the database to affect (eg "main", "temp", attached name) :param op: A `numeric code `_ with values less than 100 reserved for SQLite internal use. :param pointer: A number which is treated as a ``void pointer`` at the C level. :returns: True or False indicating if the VFS understood the op. If you want data returned back then the *pointer* needs to point to something mutable. Here is an example using `ctypes `_ of passing a Python dictionary to :meth:`~VFSFile.xFileControl` which can then modify the dictionary to set return values:: obj={"foo": 1, 2: 3} # object we want to pass objwrap=ctypes.py_object(obj) # objwrap must live before and after the call else # it gets garbage collected connection.filecontrol( "main", # which db 123, # our op code ctypes.addressof(objwrap)) # get pointer The :meth:`~VFSFile.xFileControl` method then looks like this:: def xFileControl(self, op, pointer): if op==123: # our op code obj=ctypes.py_object.from_address(pointer).value # play with obj - you can use id() to verify it is the same print(obj["foo"]) obj["result"]="it worked" return True else: # pass to parent/superclass return super(MyFile, self).xFileControl(op, pointer) This is how you set the chunk size by which the database grows. Do not combine it into one line as the c_int would be garbage collected before the filecontrol call is made:: chunksize=ctypes.c_int(32768) connection.filecontrol("main", apsw.SQLITE_FCNTL_CHUNK_SIZE, ctypes.addressof(chunksize)) Calls: `sqlite3_file_control `__""" ... filename: str """The filename of the database. Calls: `sqlite3_db_filename `__""" filename_journal: str """The journal filename of the database, Calls: `sqlite3_filename_journal `__""" filename_wal: str """The WAL filename of the database, Calls: `sqlite3_filename_wal `__""" def getautocommit(self) -> bool: """Returns if the Connection is in auto commit mode (ie not in a transaction). Calls: `sqlite3_get_autocommit `__""" ... def getexectrace(self) -> Optional[ExecTracer]: """Returns the currently installed :attr:`execution tracer `""" ... def getrowtrace(self) -> Optional[RowTracer]: """Returns the currently installed :attr:`row tracer `""" ... in_transaction: bool """True if currently in a transaction, else False Calls: `sqlite3_get_autocommit `__""" def __init__(self, filename: str, flags: int = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, vfs: Optional[str] = None, statementcachesize: int = 100): """Opens the named database. You can use ``:memory:`` to get a private temporary in-memory database that is not shared with any other connections. :param flags: One or more of the `open flags `_ orred together :param vfs: The name of the `vfs `_ to use. If *None* then the default vfs will be used. :param statementcachesize: Use zero to disable the statement cache, or a number larger than the total distinct SQL statements you execute frequently. Calls: `sqlite3_open_v2 `__ .. seealso:: * :attr:`apsw.connection_hooks` * :ref:`statementcache` * :ref:`vfs`""" ... def interrupt(self) -> None: """Causes any pending operations on the database to abort at the earliest opportunity. You can call this from any thread. For example you may have a long running query when the user presses the stop button in your user interface. :exc:`InterruptError` will be raised in the query that got interrupted. Calls: `sqlite3_interrupt `__""" ... def last_insert_rowid(self) -> int: """Returns the integer key of the most recent insert in the database. Calls: `sqlite3_last_insert_rowid `__""" ... def limit(self, id: int, newval: int = -1) -> int: """If called with one parameter then the current limit for that *id* is returned. If called with two then the limit is set to *newval*. :param id: One of the `runtime limit ids `_ :param newval: The new limit. This is a 32 bit signed integer even on 64 bit platforms. :returns: The limit in place on entry to the call. Calls: `sqlite3_limit `__ .. seealso:: * :ref:`Example `""" ... def loadextension(self, filename: str, entrypoint: Optional[str] = None) -> None: """Loads *filename* as an `extension `_ :param filename: The file to load. This must be Unicode or Unicode compatible :param entrypoint: The initialization method to call. If this parameter is not supplied then the SQLite default of ``sqlite3_extension_init`` is used. :raises ExtensionLoadingError: If the extension could not be loaded. The exception string includes more details. Calls: `sqlite3_load_extension `__ .. seealso:: * :meth:`~Connection.enableloadextension`""" ... open_flags: int """The integer flags used to open the database.""" open_vfs: str """The string name of the vfs used to open the database.""" def overloadfunction(self, name: str, nargs: int) -> None: """Registers a placeholder function so that a virtual table can provide an implementation via :meth:`VTTable.FindFunction`. :param name: Function name :param nargs: How many arguments the function takes Due to cvstrac 3507 underlying errors will not be returned. Calls: `sqlite3_overload_function `__""" ... def readonly(self, name: str) -> bool: """True or False if the named (attached) database was opened readonly or file permissions don't allow writing. The main database is named "main". An exception is raised if the database doesn't exist. Calls: `sqlite3_db_readonly `__""" ... def release_memory(self) -> None: """Attempts to free as much heap memory as possible used by this connection. Calls: `sqlite3_db_release_memory `__""" ... rowtrace: Optional[RowTracer] """Called with the cursor and row being returned for :class:`cursors ` associated with this Connection, unless the Cursor installed its own tracer. You can change the data that is returned or cause the row to be skipped altogether. If *callable* is *None* then any existing row tracer is removed. .. seealso:: * :ref:`tracing` * :ref:`rowtracer` * :attr:`Cursor.exectrace`""" def serialize(self, name: str) -> bytes: """Returns a memory copy of the database. *name* is **"main"** for the main database, **"temp"** for the temporary database etc. The memory copy is the same as if the database was backed up to disk. If the database name doesn't exist or is empty, then None is returned, not an exception (this is SQLite's behaviour). .. seealso:: * :meth:`Connection.deserialize` Calls: `sqlite3_serialize `__""" ... def set_last_insert_rowid(self, rowid: int) -> None: """Sets the value calls to :meth:`last_insert_rowid` will return. Calls: `sqlite3_set_last_insert_rowid `__""" ... def setauthorizer(self, callable: Optional[Authorizer]) -> None: """Sets the :attr:`authorizer`""" ... def setbusyhandler(self, callable: Optional[Callable[[int], bool]]) -> None: """Sets the busy handler to callable. callable will be called with one integer argument which is the number of prior calls to the busy callback for the same lock. If the busy callback returns False, then SQLite returns *SQLITE_BUSY* to the calling code. If the callback returns True, then SQLite tries to open the table again and the cycle repeats. If you previously called :meth:`~Connection.setbusytimeout` then calling this overrides that. Passing None unregisters the existing handler. .. seealso:: * :meth:`Connection.setbusytimeout` * :ref:`Busy handling ` Calls: `sqlite3_busy_handler `__""" ... def setbusytimeout(self, milliseconds: int) -> None: """If the database is locked such as when another connection is making changes, SQLite will keep retrying. This sets the maximum amount of time SQLite will keep retrying before giving up. If the database is still busy then :class:`apsw.BusyError` will be returned. :param milliseconds: Maximum thousandths of a second to wait. If you previously called :meth:`~Connection.setbusyhandler` then calling this overrides that. .. seealso:: * :meth:`Connection.setbusyhandler` * :ref:`Busy handling ` Calls: `sqlite3_busy_timeout `__""" ... def setcommithook(self, callable: Optional[CommitHook]) -> None: """*callable* will be called just before a commit. It should return False for the commit to go ahead and True for it to be turned into a rollback. In the case of an exception in your callable, a True (ie rollback) value is returned. Pass None to unregister the existing hook. .. seealso:: * :ref:`Example ` Calls: `sqlite3_commit_hook `__""" ... def setexectrace(self, callable: Optional[ExecTracer]) -> None: """Method to set :attr:`Connection.exectrace`""" ... def setprofile(self, callable: Optional[Callable[[str, int], None]]) -> None: """Sets a callable which is invoked at the end of execution of each statement and passed the statement string and how long it took to execute. (The execution time is in nanoseconds.) Note that it is called only on completion. If for example you do a ``SELECT`` and only read the first result, then you won't reach the end of the statement. Calls: `sqlite3_profile `__""" ... def setprogresshandler(self, callable: Optional[Callable[[], bool]], nsteps: int = 20) -> None: """Sets a callable which is invoked every *nsteps* SQLite inststructions. The callable should return True to abort or False to continue. (If there is an error in your Python *callable* then True/abort will be returned). .. seealso:: * :ref:`Example ` Calls: `sqlite3_progress_handler `__""" ... def setrollbackhook(self, callable: Optional[Callable[[], None]]) -> None: """Sets a callable which is invoked during a rollback. If *callable* is *None* then any existing rollback hook is unregistered. The *callable* is called with no parameters and the return value is ignored. Calls: `sqlite3_rollback_hook `__""" ... def setrowtrace(self, callable: Optional[RowTracer]) -> None: """Method to set :attr:`Connection.rowtrace`""" ... def setupdatehook(self, callable: Optional[Callable[[int, str, str, int], None]]) -> None: """Calls *callable* whenever a row is updated, deleted or inserted. If *callable* is *None* then any existing update hook is unregistered. The update hook cannot make changes to the database while the query is still executing, but can record them for later use or apply them in a different connection. The update hook is called with 4 parameters: type (int) *SQLITE_INSERT*, *SQLITE_DELETE* or *SQLITE_UPDATE* database name (string) This is ``main`` for the database or the name specified in `ATTACH `_ table name (string) The table on which the update happened rowid (64 bit integer) The affected row .. seealso:: * :ref:`Example ` Calls: `sqlite3_update_hook `__""" ... def setwalhook(self, callable: Optional[Callable[[Connection, str, int], int]]) -> None: """*callable* will be called just after data is committed in :ref:`wal` mode. It should return *SQLITE_OK* or an error code. The callback is called with 3 parameters: * The Connection * The database name (eg "main" or the name of an attached database) * The number of pages in the wal log You can pass in None in order to unregister an existing hook. Calls: `sqlite3_wal_hook `__""" ... def sqlite3pointer(self) -> int: """Returns the underlying `sqlite3 * `_ for the connection. This method is useful if there are other C level libraries in the same process and you want them to use the APSW connection handle. The value is returned as a number using `PyLong_FromVoidPtr `__ under the hood. You should also ensure that you increment the reference count on the :class:`Connection` for as long as the other libraries are using the pointer. It is also a very good idea to call :meth:`sqlitelibversion` and ensure it is the same as the other libraries.""" ... def status(self, op: int, reset: bool = False) -> Tuple[int, int]: """Returns current and highwater measurements for the database. :param op: A `status parameter `_ :param reset: If *True* then the highwater is set to the current value :returns: A tuple of current value and highwater value .. seealso:: The :func:`status` example which works in exactly the same way. * :ref:`Status example ` Calls: `sqlite3_db_status `__""" ... system_errno: int """The underlying system error code for the most recent I/O errors or failing to open files. Calls: `sqlite3_system_errno `__""" def table_exists(self, dbname: Optional[str], table_name: str) -> bool: """Returns True if the named table exists, else False. `dbname` is the specific database (eg "main", "temp") or None to search all databases Calls: `sqlite3_table_column_metadata `__""" ... def totalchanges(self) -> int: """Returns the total number of database rows that have be modified, inserted, or deleted since the database connection was opened. Calls: `sqlite3_total_changes64 `__""" ... def trace_v2(self, mask: int, callback: Optional[Callable[[dict], None]] = None) -> None: """Registers a trace callback. The callback is called with a dict of relevant values based on the code. .. list-table:: :header-rows: 1 :widths: auto * - Key - Type - Explanation * - code - :class:`int` - One of the `trace event codes `__ * - connection - :class:`Connection` - Connection this trace event belongs to * - sql - :class:`str` - SQL text (except SQLITE_TRACE_CLOSE) * - profile - :class:`int` - nanoseconds SQL took to execute (SQLITE_TRACE_PROFILE only) * - stmt_status - :class:`dict` - SQLITE_TRACE_PROFILE only: Keys are names from `status parameters `__ - eg *"SQLITE_STMTSTATUS_VM_STEP"* and corresponding integer values. The counters are reset each time a statement starts execution. Calls: * `sqlite3_trace_v2 `__ * `sqlite3_stmt_status `__""" ... def txn_state(self, schema: Optional[str] = None) -> int: """Returns the current transaction state of the database, or a specific schema if provided. ValueError is raised if schema is not None or a valid schema name. :attr:`apsw.mapping_txn_state` contains the names and values returned. Calls: `sqlite3_txn_state `__""" ... def wal_autocheckpoint(self, n: int) -> None: """Sets how often the :ref:`wal` checkpointing is run. :param n: A number representing the checkpointing interval or zero/negative to disable auto checkpointing. Calls: `sqlite3_wal_autocheckpoint `__""" ... def wal_checkpoint(self, dbname: Optional[str] = None, mode: int = SQLITE_CHECKPOINT_PASSIVE) -> Tuple[int, int]: """Does a WAL checkpoint. Has no effect if the database(s) are not in WAL mode. :param dbname: The name of the database or all databases if None :param mode: One of the `checkpoint modes `__. :return: A tuple of the size of the WAL log in frames and the number of frames checkpointed as described in the `documentation `__. Calls: `sqlite3_wal_checkpoint_v2 `__""" ... class Cursor: """You obtain cursors by calling :meth:`Connection.cursor`.""" def close(self, force: bool = False) -> None: """It is very unlikely you will need to call this method. It exists because older versions of SQLite required all Connection/Cursor activity to be confined to the same thread. That is no longer the case. Cursors are automatically garbage collected and when there are none left will allow the connection to be garbage collected if it has no other references. A cursor is open if there are remaining statements to execute (if your query included multiple statements), or if you called :meth:`~Cursor.executemany` and not all of the *sequenceofbindings* have been used yet. :param force: If False then you will get exceptions if there is remaining work to do be in the Cursor such as more statements to execute, more data from the executemany binding sequence etc. If force is True then all remaining work and state information will be silently discarded.""" ... connection: Connection """:class:`Connection` this cursor is using""" description: Tuple[Tuple[str, str, None, None, None, None, None], ...] """Based on the `DB-API cursor property `__, this returns the same as :meth:`getdescription` but with 5 Nones appended. See also :issue:`131`.""" description_full: Tuple[Tuple[str, str, str, str, str], ...] """Only present if SQLITE_ENABLE_COLUMN_METADATA was defined at compile time. Returns all information about the query result columns. In addition to the name and declared type, you also get the database name, table name, and origin name. Calls: * `sqlite3_column_name `__ * `sqlite3_column_decltype `__ * `sqlite3_column_database_name `__ * `sqlite3_column_table_name `__ * `sqlite3_column_origin_name `__""" exectrace: Optional[ExecTracer] """Called with the cursor, statement and bindings for each :meth:`~Cursor.execute` or :meth:`~Cursor.executemany` on this cursor. If *callable* is *None* then any existing execution tracer is unregistered. .. seealso:: * :ref:`tracing` * :ref:`executiontracer` * :attr:`Connection.exectrace`""" def execute(self, statements: str, bindings: Optional[Bindings] = None, *, can_cache: bool = True, prepare_flags: int = 0) -> Cursor: """Executes the statements using the supplied bindings. Execution returns when the first row is available or all statements have completed. :param statements: One or more SQL statements such as ``select * from books`` or ``begin; insert into books ...; select last_insert_rowid(); end``. :param bindings: If supplied should either be a sequence or a dictionary. Each item must be one of the :ref:`supported types ` :param can_cache: If False then the statement cache will not be used to find an already prepared query, nor will it be placed in the cache after execution :param prepare_flags: `flags `__ passed to `sqlite_prepare_v3 `__ If you use numbered bindings in the query then supply a sequence. Any sequence will work including lists and iterators. For example:: cursor.execute("insert into books values(?,?)", ("title", "number")) .. note:: A common gotcha is wanting to insert a single string but not putting it in a tuple:: cursor.execute("insert into books values(?)", "a title") The string is a sequence of 8 characters and so it will look like you are supplying 8 bindings when only one is needed. Use a one item tuple with a trailing comma like this:: cursor.execute("insert into books values(?)", ("a title",) ) If you used names in the statement then supply a dictionary as the binding. It is ok to be missing entries from the dictionary - None/null will be used. For example:: cursor.execute("insert into books values(:title, :isbn, :rating)", {"title": "book title", "isbn": 908908908}) The return is the cursor object itself which is also an iterator. This allows you to write:: for row in cursor.execute("select * from books"): print(row) :raises TypeError: The bindings supplied were neither a dict nor a sequence :raises BindingsError: You supplied too many or too few bindings for the statements :raises IncompleteExecutionError: There are remaining unexecuted queries from your last execute Calls: * `sqlite3_prepare_v3 `__ * `sqlite3_step `__ * `sqlite3_bind_int64 `__ * `sqlite3_bind_null `__ * `sqlite3_bind_text64 `__ * `sqlite3_bind_double `__ * `sqlite3_bind_blob64 `__ * `sqlite3_bind_zeroblob `__""" ... def executemany(self, statements: str, sequenceofbindings: Sequence[Bindings], *, can_cache: bool = True, prepare_flags: int = 0) -> Cursor: """This method is for when you want to execute the same statements over a sequence of bindings. Conceptually it does this:: for binding in sequenceofbindings: cursor.execute(statements, binding) Example:: rows=( (1, 7), (2, 23), (4, 92), (12, 12) ) cursor.executemany("insert into nums values(?,?)", rows) The return is the cursor itself which acts as an iterator. Your statements can return data. See :meth:`~Cursor.execute` for more information.""" ... expanded_sql: str """The SQL text with bound parameters expanded. For example:: execute("select ?, ?", (3, "three")) would return:: select 3, 'three' Note that while SQLite supports nulls in strings, their implementation of sqlite3_expanded_sql stops at the first null. Calls: `sqlite3_expanded_sql `__""" def fetchall(self) -> list[Tuple[SQLiteValue, ...]]: """Returns all remaining result rows as a list. This method is defined in DBAPI. It is a longer way of doing ``list(cursor)``.""" ... def fetchone(self) -> Optional[Any]: """Returns the next row of data or None if there are no more rows.""" ... def getconnection(self) -> Connection: """Returns the :attr:`connection` this cursor is using""" ... def getdescription(self) -> Tuple[Tuple[str, str], ...]: """If you are trying to get information about a table or view, then `pragma table_info `__ is better. Returns a tuple describing each column in the result row. The return is identical for every row of the results. You can only call this method once you have started executing a statement and before you have finished:: # This will error cursor.getdescription() for row in cursor.execute("select ....."): # this works print (cursor.getdescription()) print (row) The information about each column is a tuple of ``(column_name, declared_column_type)``. The type is what was declared in the ``CREATE TABLE`` statement - the value returned in the row will be whatever type you put in for that row and column. (This is known as `manifest typing `_ which is also the way that Python works. The variable ``a`` could contain an integer, and then you could put a string in it. Other static languages such as C or other SQL databases only let you put one type in - eg ``a`` could only contain an integer or a string, but never both.) Example:: cursor.execute("create table books(title string, isbn number, wibbly wobbly zebra)") cursor.execute("insert into books values(?,?,?)", (97, "fjfjfj", 3.7)) cursor.execute("insert into books values(?,?,?)", ("fjfjfj", 3.7, 97)) for row in cursor.execute("select * from books"): print (cursor.getdescription()) print (row) Output:: # row 0 - description (('title', 'string'), ('isbn', 'number'), ('wibbly', 'wobbly zebra')) # row 0 - values (97, 'fjfjfj', 3.7) # row 1 - description (('title', 'string'), ('isbn', 'number'), ('wibbly', 'wobbly zebra')) # row 1 - values ('fjfjfj', 3.7, 97) Calls: * `sqlite3_column_name `__ * `sqlite3_column_decltype `__""" ... def getexectrace(self) -> Optional[ExecTracer]: """Returns the currently installed :attr:`execution tracer ` .. seealso:: * :ref:`tracing`""" ... def getrowtrace(self) -> Optional[RowTracer]: """Returns the currently installed (via :meth:`~Cursor.setrowtrace`) row tracer. .. seealso:: * :ref:`tracing`""" ... is_explain: int """Returns 0 if executing a normal query, 1 if it is an EXPLAIN query, and 2 if an EXPLAIN QUERY PLAN query. Calls: `sqlite3_stmt_isexplain `__""" is_readonly: bool """Returns True if the current query does not change the database. Note that called functions, virtual tables etc could make changes though. Calls: `sqlite3_stmt_readonly `__""" def __iter__(self: Cursor) -> Cursor: """Cursors are iterators""" ... def __next__(self: Cursor) -> Any: """Cursors are iterators""" ... rowtrace: Optional[RowTracer] """Called with cursor and row being returned. You can change the data that is returned or cause the row to be skipped altogether. If *callable* is *None* then any existing row tracer is unregistered. .. seealso:: * :ref:`tracing` * :ref:`rowtracer` * :attr:`Connection.rowtrace`""" def setexectrace(self, callable: Optional[ExecTracer]) -> None: """Sets the :attr:`execution tracer `""" ... def setrowtrace(self, callable: Optional[RowTracer]) -> None: """Sets the :attr:`row tracer `""" ... class URIFilename: """SQLite uses a convoluted method of storing `uri parameters `__ after the filename binding the C filename representation and parameters together. This class encapsulates that binding. The :ref:`example ` shows usage of this class. Your :meth:`VFS.xOpen` method will generally be passed one of these instead of a string as the filename if the URI flag was used or the main database flag is set. You can safely pass it on to the :class:`VFSFile` constructor which knows how to get the name back out.""" def filename(self) -> str: """Returns the filename.""" ... def uri_boolean(self, name: str, default: bool) -> bool: """Returns the boolean value for parameter `name` or `default` if not present. Calls: `sqlite3_uri_boolean `__""" ... def uri_int(self, name: str, default: int) -> int: """Returns the integer value for parameter `name` or `default` if not present. Calls: `sqlite3_uri_int64 `__""" ... def uri_parameter(self, name: str) -> Optional[str]: """Returns the value of parameter `name` or None. Calls: `sqlite3_uri_parameter `__""" ... class VFSFile: """Wraps access to a file. You only need to derive from this class if you want the file object returned from :meth:`VFS.xOpen` to inherit from an existing VFS implementation. .. note:: All file sizes and offsets are 64 bit quantities even on 32 bit operating systems.""" def excepthook(self, etype: type[BaseException], evalue: BaseException, etraceback: Optional[types.TracebackType]) ->None: """Called when there has been an exception in a :class:`VFSFile` routine. The default implementation calls ``sys.excepthook`` and if that fails then ``PyErr_Display``. The three arguments correspond to what ``sys.exc_info()`` would return. :param etype: The exception type :param evalue: The exception value :param etraceback: The exception traceback. Note this includes all frames all the way up to the thread being started.""" ... def __init__(self, vfs: str, filename: Union[str,URIFilename], flags: List[int]): """:param vfs: The vfs you want to inherit behaviour from. You can use an empty string ``""`` to inherit from the default vfs. :param name: The name of the file being opened. May be an instance of :class:`URIFilename`. :param flags: A two item list ``[inflags, outflags]`` as detailed in :meth:`VFS.xOpen`. :raises ValueError: If the named VFS is not registered. .. note:: If the VFS that you inherit from supports :ref:`write ahead logging ` then your :class:`VFSFile` will also support the xShm methods necessary to implement wal. .. seealso:: :meth:`VFS.xOpen`""" ... def xCheckReservedLock(self) -> bool: """Returns True if any database connection (in this or another process) has a lock other than `SQLITE_LOCK_NONE or SQLITE_LOCK_SHARED `_.""" ... def xClose(self) -> None: """Close the database. Note that even if you return an error you should still close the file. It is safe to call this method multiple times.""" ... def xDeviceCharacteristics(self) -> int: """Return `I/O capabilities `_ (bitwise or of appropriate values). If you do not implement the function or have an error then 0 (the SQLite default) is returned.""" ... def xFileControl(self, op: int, ptr: int) -> bool: """Receives `file control `_ request typically issued by :meth:`Connection.filecontrol`. See :meth:`Connection.filecontrol` for an example of how to pass a Python object to this routine. :param op: A numeric code. Codes below 100 are reserved for SQLite internal use. :param ptr: An integer corresponding to a pointer at the C level. :returns: A boolean indicating if the op was understood As of SQLite 3.6.10, this method is called by SQLite if you have inherited from an underlying VFSFile. Consequently ensure you pass any unrecognised codes through to your super class. For example:: def xFileControl(self, op, ptr): if op==1027: process_quick(ptr) elif op==1028: obj=ctypes.py_object.from_address(ptr).value else: # this ensures superclass implementation is called return super(MyFile, self).xFileControl(op, ptr) # we understood the op return True""" ... def xFileSize(self) -> int: """Return the size of the file in bytes. Remember that file sizes are 64 bit quantities even on 32 bit operating systems.""" ... def xLock(self, level: int) -> None: """Increase the lock to the level specified which is one of the `SQLITE_LOCK `_ family of constants. If you can't increase the lock level because someone else has locked it, then raise :exc:`BusyError`.""" ... def xRead(self, amount: int, offset: int) -> bytes: """Read the specified *amount* of data starting at *offset*. You should make every effort to read all the data requested, or return an error. If you have the file open for non-blocking I/O or if signals happen then it is possible for the underlying operating system to do a partial read. You will need to request the remaining data. Except for empty files SQLite considers short reads to be a fatal error. :param amount: Number of bytes to read :param offset: Where to start reading. This number may be 64 bit once the database is larger than 2GB.""" ... def xSectorSize(self) -> int: """Return the native underlying sector size. SQLite uses the value returned in determining the default database page size. If you do not implement the function or have an error then 4096 (the SQLite default) is returned.""" ... def xSync(self, flags: int) -> None: """Ensure data is on the disk platters (ie could survive a power failure immediately after the call returns) with the `sync flags `_ detailing what needs to be synced. You can sync more than what is requested.""" ... def xTruncate(self, newsize: int) -> None: """Set the file length to *newsize* (which may be more or less than the current length).""" ... def xUnlock(self, level: int) -> None: """Decrease the lock to the level specified which is one of the `SQLITE_LOCK `_ family of constants.""" ... def xWrite(self, data: bytes, offset: int) -> None: """Write the *data* starting at absolute *offset*. You must write all the data requested, or return an error. If you have the file open for non-blocking I/O or if signals happen then it is possible for the underlying operating system to do a partial write. You will need to write the remaining data. :param offset: Where to start writing. This number may be 64 bit once the database is larger than 2GB.""" ... class VFS: """Provides operating system access. You can get an overview in the `SQLite documentation `_. To create a VFS your Python class must inherit from :class:`VFS`.""" def excepthook(self, etype: type[BaseException], evalue: BaseException, etraceback: Optional[types.TracebackType]) -> Any: """Called when there has been an exception in a :class:`VFS` routine. The default implementation passes args to ``sys.excepthook`` and if that fails then ``PyErr_Display``. The three arguments correspond to what ``sys.exc_info()`` would return.""" ... def __init__(self, name: str, base: Optional[str] = None, makedefault: bool = False, maxpathname: int = 1024): """:param name: The name to register this vfs under. If the name already exists then this vfs will replace the prior one of the same name. Use :meth:`apsw.vfsnames` to get a list of registered vfs names. :param base: If you would like to inherit behaviour from an already registered vfs then give their name. To inherit from the default vfs, use a zero length string ``""`` as the name. :param makedefault: If true then this vfs will be registered as the default, and will be used by any opens that don't specify a vfs. :param maxpathname: The maximum length of database name in bytes when represented in UTF-8. If a pathname is passed in longer than this value then SQLite will not `be able to open it `__. :raises ValueError: If *base* is not *None* and the named vfs is not currently registered. Calls: * `sqlite3_vfs_register `__ * `sqlite3_vfs_find `__""" ... def unregister(self) -> None: """Unregisters the VFS making it unavailable to future database opens. You do not need to call this as the VFS is automatically unregistered by when the VFS has no more references or open databases using it. It is however useful to call if you have made your VFS be the default and wish to immediately make it be unavailable. It is safe to call this routine multiple times. Calls: `sqlite3_vfs_unregister `__""" ... def xAccess(self, pathname: str, flags: int) -> bool: """SQLite wants to check access permissions. Return True or False accordingly. :param pathname: File or directory to check :param flags: One of the `access flags `_""" ... def xCurrentTime(self) -> float: """Return the `Julian Day Number `_ as a floating point number where the integer portion is the day and the fractional part is the time. Do not adjust for timezone (ie use `UTC `_).""" ... def xDelete(self, filename: str, syncdir: bool) -> None: """Delete the named file. If the file is missing then raise an :exc:`IOError` exception with extendedresult *SQLITE_IOERR_DELETE_NOENT* :param filename: File to delete :param syncdir: If True then the directory should be synced ensuring that the file deletion has been recorded on the disk platters. ie if there was an immediate power failure after this call returns, on a reboot the file would still be deleted.""" ... def xDlClose(self, handle: int) -> None: """Close and unload the library corresponding to the handle you returned from :meth:`~VFS.xDlOpen`. You can use ctypes to do this:: def xDlClose(handle): # Note leading underscore in _ctypes _ctypes.dlclose(handle) # Linux/Mac/Unix _ctypes.FreeLibrary(handle) # Windows""" ... def xDlError(self) -> str: """Return an error string describing the last error of :meth:`~VFS.xDlOpen` or :meth:`~VFS.xDlSym` (ie they returned zero/NULL). If you do not supply this routine then SQLite provides a generic message. To implement this method, catch exceptions in :meth:`~VFS.xDlOpen` or :meth:`~VFS.xDlSym`, turn them into strings, save them, and return them in this routine. If you have an error in this routine or return None then SQLite's generic message will be used.""" ... def xDlOpen(self, filename: str) -> int: """Load the shared library. You should return a number which will be treated as a void pointer at the C level. On error you should return 0 (NULL). The number is passed as is to :meth:`~VFS.xDlSym`/:meth:`~VFS.xDlClose` so it can represent anything that is convenient for you (eg an index into an array). You can use ctypes to load a library:: def xDlOpen(name): return ctypes.cdll.LoadLibrary(name)._handle""" ... def xDlSym(self, handle: int, symbol: str) -> int: """Returns the address of the named symbol which will be called by SQLite. On error you should return 0 (NULL). You can use ctypes:: def xDlSym(ptr, name): return _ctypes.dlsym (ptr, name) # Linux/Unix/Mac etc (note leading underscore) return ctypes.win32.kernel32.GetProcAddress (ptr, name) # Windows :param handle: The value returned from an earlier :meth:`~VFS.xDlOpen` call :param symbol: A string""" ... def xFullPathname(self, name: str) -> str: """Return the absolute pathname for name. You can use ``os.path.abspath`` to do this.""" ... def xGetLastError(self) -> Tuple[int, str]: """This method is to return an integer error code and (optional) text describing the last error that happened in this thread. .. note:: SQLite 3.12 changed the semantics in an incompatible way from earlier versions. You will need to rewrite earlier implementations.""" ... def xGetSystemCall(self, name: str) -> Optional[int]: """Returns a pointer for the current method implementing the named system call. Return None if the call does not exist.""" ... def xNextSystemCall(self, name: Optional[str]) -> Optional[str]: """This method is repeatedly called to iterate over all of the system calls in the vfs. When called with None you should return the name of the first system call. In subsequent calls return the name after the one passed in. If name is the last system call then return None. .. note:: Because of internal SQLite implementation semantics memory will be leaked on each call to this function. Consequently you should build up the list of call names once rather than repeatedly doing it.""" ... def xOpen(self, name: Optional[Union[str,URIFilename]], flags: List[int]) -> VFSFile: """This method should return a new file object based on name. You can return a :class:`VFSFile` from a completely different VFS. :param name: File to open. Note that *name* may be *None* in which case you should open a temporary file with a name of your choosing. May be an instance of :class:`URIFilename`. :param flags: A list of two integers ``[inputflags, outputflags]``. Each integer is one or more of the `open flags `_ binary orred together. The ``inputflags`` tells you what SQLite wants. For example *SQLITE_OPEN_DELETEONCLOSE* means the file should be automatically deleted when closed. The ``outputflags`` describes how you actually did open the file. For example if you opened it read only then *SQLITE_OPEN_READONLY* should be set.""" ... def xRandomness(self, numbytes: int) -> bytes: """This method is called once when SQLite needs to seed the random number generator. It is called on the default VFS only. It is not called again, even across :meth:`apsw.shutdown` calls. You can return less than the number of bytes requested including None. If you return more then the surplus is ignored.""" ... def xSetSystemCall(self, name: Optional[str], pointer: int) -> bool: """Change a system call used by the VFS. This is useful for testing and some other scenarios such as sandboxing. :param name: The string name of the system call :param pointer: A pointer provided as an int. There is no reference counting or other memory tracking of the pointer. If you provide one you need to ensure it is around for the lifetime of this and any other related VFS. Raise an exception to return an error. If the system call does not exist then raise :exc:`NotFoundError`. If `name` is None, then all systemcalls are reset to their defaults. This behaviour is not documented. :returns: True if the system call was set. False if the system call is not known.""" ... def xSleep(self, microseconds: int) -> int: """Pause execution of the thread for at least the specified number of microseconds (millionths of a second). This routine is typically called from the busy handler. :returns: How many microseconds you actually requested the operating system to sleep for. For example if your operating system sleep call only takes seconds then you would have to have rounded the microseconds number up to the nearest second and should return that rounded up value.""" ... if sys.version_info >= (3, 8): class VTCursor(Protocol): """.. note:: There is no actual *VTCursor* class - it is shown this way for documentation convenience and is present as a `typing protocol `__. Your cursor instance should implement all the methods documented here. The :class:`VTCursor` object is used for iterating over a table. There may be many cursors simultaneously so each one needs to keep track of where :ref:`Virtual table structure ` it is. .. seealso:: :ref:`Virtual table structure `""" def Close(self) -> None: """This is the destructor for the cursor. Note that you must cleanup. The method will not be called again if you raise an exception.""" ... def Column(self, number: int) -> SQLiteValue: """Requests the value of the specified column *number* of the current row. If *number* is -1 then return the rowid. :returns: Must be one one of the :ref:`5 supported types `""" ... def Eof(self) -> bool: """Called to ask if we are at the end of the table. It is called after each call to Filter and Next. :returns: False if the cursor is at a valid row of data, else True .. note:: This method can only return True or False to SQLite. If you have an exception in the method or provide a non-boolean return then True (no more data) will be returned to SQLite.""" ... def Filter(self, indexnum: int, indexname: str, constraintargs: Optional[Tuple]) -> None: """This method is always called first to initialize an iteration to the first row of the table. The arguments come from the :meth:`~VTTable.BestIndex` method in the :class:`table ` object with constraintargs being a tuple of the constraints you requested. If you always return None in BestIndex then indexnum will be zero, indexstring will be None and constraintargs will be empty).""" ... def Next(self) -> None: """Move the cursor to the next row. Do not have an exception if there is no next row. Instead return False when :meth:`~VTCursor.Eof` is subsequently called. If you said you had indices in your :meth:`VTTable.BestIndex` return, and they were selected for use as provided in the parameters to :meth:`~VTCursor.Filter` then you should move to the next appropriate indexed and constrained row.""" ... def Rowid(self) -> int: """Return the current rowid.""" ... if sys.version_info >= (3, 8): class VTModule(Protocol): """.. note:: There is no actual *VTModule* class - it is shown this way for documentation convenience and is present as a `typing protocol `__. Your module instance should implement all the methods documented here. A module instance is used to create the virtual tables. Once you have a module object, you register it with a connection by calling :meth:`Connection.createmodule`:: # make an instance mymod=MyModuleClass() # register the vtable on connection con con.createmodule("modulename", mymod) # tell SQLite about the table con.execute("create VIRTUAL table tablename USING modulename('arg1', 2)") The create step is to tell SQLite about the existence of the table. Any number of tables referring to the same module can be made this way. Note the (optional) arguments which are passed to the module.""" def Connect(self, connection: Connection, modulename: str, databasename: str, tablename: str, *args: Tuple[SQLiteValue, ...]) -> Tuple[str, VTTable]: """The parameters and return are identical to :meth:`~VTModule.Create`. This method is called when there are additional references to the table. :meth:`~VTModule.Create` will be called the first time and :meth:`~VTModule.Connect` after that. The advise is to create caches, generated data and other heavyweight processing on :meth:`~VTModule.Create` calls and then find and reuse that on the subsequent :meth:`~VTModule.Connect` calls. The corresponding call is :meth:`VTTable.Disconnect`. If you have a simple virtual table implementation, then just set :meth:`~VTModule.Connect` to be the same as :meth:`~VTModule.Create`:: class MyModule: def Create(self, connection, modulename, databasename, tablename, *args): # do lots of hard work Connect=Create""" ... def Create(self, connection: Connection, modulename: str, databasename: str, tablename: str, *args: Tuple[SQLiteValue, ...]) -> Tuple[str, VTTable]: """Called when a table is first created on a :class:`connection `. :param connection: An instance of :class:`Connection` :param modulename: The string name under which the module was :meth:`registered ` :param databasename: The name of the database. This will be ``main`` for directly opened files and the name specified in `ATTACH `_ statements. :param tablename: Name of the table the user wants to create. :param args: Any arguments that were specified in the `create virtual table `_ statement. :returns: A list of two items. The first is a SQL `create table `_ statement. The columns are parsed so that SQLite knows what columns and declared types exist for the table. The second item is an object that implements the :class:`table ` methods. The corresponding call is :meth:`VTTable.Destroy`.""" ... if sys.version_info >= (3, 8): class VTTable(Protocol): """.. note:: There is no actual *VTTable* class - it is shown this way for documentation convenience and is present as a `typing protocol `__. Your table instance should implement the methods documented here. The :class:`VTTable` object contains knowledge of the indices, makes cursors and can perform transactions. .. _vtablestructure: A virtual table is structured as a series of rows, each of which has the same columns. The value in a column must be one of the `5 supported types `_, but the type can be different between rows for the same column. The virtual table routines identify the columns by number, starting at zero. Each row has a **unique** 64 bit integer `rowid `_ with the :class:`Cursor ` routines operating on this number, as well as some of the :class:`Table ` routines such as :meth:`UpdateChangeRow `.""" def Begin(self) -> None: """This function is used as part of transactions. You do not have to provide the method.""" ... def BestIndex(self, constraints: Sequence[Tuple[int, int], ...], orderbys: Sequence[Tuple[int, int], ...]) -> Any: """This is a complex method. To get going initially, just return *None* and you will be fine. Implementing this method reduces the number of rows scanned in your table to satisfy queries, but only if you have an index or index like mechanism available. .. note:: The implementation of this method differs slightly from the `SQLite documentation `__ for the C API. You are not passed "unusable" constraints. The argv/constraintarg positions are not off by one. In the C api, you have to return position 1 to get something passed to :meth:`VTCursor.Filter` in position 0. With the APSW implementation, you return position 0 to get Filter arg 0, position 1 to get Filter arg 1 etc. The purpose of this method is to ask if you have the ability to determine if a row meets certain constraints that doesn't involve visiting every row. An example constraint is ``price > 74.99``. In a traditional SQL database, queries with constraints can be speeded up `with indices `_. If you return None, then SQLite will visit every row in your table and evaluate the constraint itself. Your index choice returned from BestIndex will also be passed to the :meth:`~VTCursor.Filter` method on your cursor object. Note that SQLite may call this method multiple times trying to find the most efficient way of answering a complex query. **constraints** You will be passed the constraints as a sequence of tuples containing two items. The first item is the column number and the second item is the operation. Example query: ``select * from foo where price > 74.99 and quantity<=10 and customer='Acme Widgets'`` If customer is column 0, price column 2 and quantity column 5 then the constraints will be:: (2, apsw.SQLITE_INDEX_CONSTRAINT_GT), (5, apsw.SQLITE_INDEX_CONSTRAINT_LE), (0, apsw.SQLITE_INDEX_CONSTRAINT_EQ) Note that you do not get the value of the constraint (ie "Acme Widgets", 74.99 and 10 in this example). If you do have any suitable indices then you return a sequence the same length as constraints with the members mapping to the constraints in order. Each can be one of None, an integer or a tuple of an integer and a boolean. Conceptually SQLite is giving you a list of constraints and you are returning a list of the same length describing how you could satisfy each one. Each list item returned corresponding to a constraint is one of: None This means you have no index for that constraint. SQLite will have to iterate over every row for it. integer This is the argument number for the constraintargs being passed into the :meth:`~VTCursor.Filter` function of your :class:`cursor ` (the values "Acme Widgets", 74.99 and 10 in the example). (integer, boolean) By default SQLite will check what you return. For example if you said that you had an index on price, SQLite will still check that each row you returned is greater than 74.99. If you set the boolean to False then SQLite won't do that double checking. Example query: ``select * from foo where price > 74.99 and quantity<=10 and customer=='Acme Widgets'``. customer is column 0, price column 2 and quantity column 5. You can index on customer equality and price. +----------------------------------------+--------------------------------+ | Constraints (in) | Constraints used (out) | +========================================+================================+ | :: | :: | | | | | (2, apsw.SQLITE_INDEX_CONSTRAINT_GT), | 1, | | (5, apsw.SQLITE_INDEX_CONSTRAINT_LE), | None, | | (0, apsw.SQLITE_INDEX_CONSTRAINT_EQ) | 0 | | | | +----------------------------------------+--------------------------------+ When your :class:`~VTCursor.Filter` method in the cursor is called, constraintarg[0] will be "Acme Widgets" (customer constraint value) and constraintarg[1] will be 74.99 (price constraint value). You can also return an index number (integer) and index string to use (SQLite attaches no significance to these values - they are passed as is to your :meth:`VTCursor.Filter` method as a way for the BestIndex method to let the :meth:`~VTCursor.Filter` method know which of your indices or similar mechanism to use. **orderbys** The second argument to BestIndex is a sequence of orderbys because the query requested the results in a certain order. If your data is already in that order then SQLite can give the results back as is. If not, then SQLite will have to sort the results first. Example query: ``select * from foo order by price desc, quantity asc`` Price is column 2, quantity column 5 so orderbys will be:: (2, True), # True means descending, False is ascending (5, False) **Return** You should return up to 5 items. Items not present in the return have a default value. 0: constraints used (default None) This must either be None or a sequence the same length as constraints passed in. Each item should be as specified above saying if that constraint is used, and if so which constraintarg to make the value be in your :meth:`VTCursor.Filter` function. 1: index number (default zero) This value is passed as is to :meth:`VTCursor.Filter` 2: index string (default None) This value is passed as is to :meth:`VTCursor.Filter` 3: orderby consumed (default False) Return True if your output will be in exactly the same order as the orderbys passed in 4: estimated cost (default a huge number) Approximately how many disk operations are needed to provide the results. SQLite uses the cost to optimise queries. For example if the query includes *A or B* and A has 2,000 operations and B has 100 then it is best to evaluate B before A. **A complete example** Query is ``select * from foo where price>74.99 and quantity<=10 and customer=="Acme Widgets" order by price desc, quantity asc``. Customer is column 0, price column 2 and quantity column 5. You can index on customer equality and price. :: BestIndex(constraints, orderbys) constraints= ( (2, apsw.SQLITE_INDEX_CONSTRAINT_GT), (5, apsw.SQLITE_INDEX_CONSTRAINT_LE), (0, apsw.SQLITE_INDEX_CONSTRAINT_EQ) ) orderbys= ( (2, True), (5, False) ) # You return ( (1, None, 0), # constraints used 27, # index number "idx_pr_cust", # index name False, # results are not in orderbys order 1000 # about 1000 disk operations to access index ) # Your Cursor.Filter method will be called with: 27, # index number you returned "idx_pr_cust", # index name you returned "Acme Widgets", # constraintarg[0] - customer 74.99 # constraintarg[1] - price""" ... def Commit(self) -> None: """This function is used as part of transactions. You do not have to provide the method.""" ... def Destroy(self) -> None: """The opposite of :meth:`VTModule.Create`. This method is called when the table is no longer used. Note that you must always release resources even if you intend to return an error, as it will not be called again on error. SQLite may also leak memory if you return an error.""" ... def Disconnect(self) -> None: """The opposite of :meth:`VTModule.Connect`. This method is called when a reference to a virtual table is no longer used, but :meth:`VTTable.Destroy` will be called when the table is no longer used.""" ... def FindFunction(self, name: str, nargs: int): """Called to find if the virtual table has its own implementation of a particular scalar function. You should return the function if you have it, else return None. You do not have to provide this method. This method is called while SQLite is `preparing `_ a query. If a query is in the :ref:`statement cache ` then *FindFunction* won't be called again. If you want to return different implementations for the same function over time then you will need to disable the :ref:`statement cache `. :param name: The function name :param nargs: How many arguments the function takes .. seealso:: * :meth:`Connection.overloadfunction`""" ... def Open(self) -> VTCursor: """Returns a :class:`cursor ` object.""" ... def Rename(self, newname: str) -> None: """Notification that the table will be given a new name. If you return without raising an exception, then SQLite renames the table (you don't have to do anything). If you raise an exception then the renaming is prevented. You do not have to provide this method.""" ... def Rollback(self) -> None: """This function is used as part of transactions. You do not have to provide the method.""" ... def Sync(self) -> None: """This function is used as part of transactions. You do not have to provide the method.""" ... def UpdateChangeRow(self, row: int, newrowid: int, fields: Tuple[SQLiteValue, ...]): """Change an existing row. You may also need to change the rowid - for example if the query was ``UPDATE table SET rowid=rowid+100 WHERE ...`` :param row: The existing 64 bit integer rowid :param newrowid: If not the same as *row* then also change the rowid to this. :param fields: A tuple of values the same length and order as columns in your table""" ... def UpdateDeleteRow(self, rowid: int): """Delete the row with the specified *rowid*. :param rowid: 64 bit integer""" ... def UpdateInsertRow(self, rowid: Optional[int], fields: Tuple[SQLiteValue, ...]) -> Optional[int]: """Insert a row with the specified *rowid*. :param rowid: *None* if you should choose the rowid yourself, else a 64 bit integer :param fields: A tuple of values the same length and order as columns in your table :returns: If *rowid* was *None* then return the id you assigned to the row. If *rowid* was not *None* then the return value is ignored.""" ... class zeroblob: """If you want to insert a blob into a row, you previously needed to supply the entire blob in one go. To read just one byte also required retrieving the blob in its entirety. For example to insert a 100MB file you would have done:: largedata=open("largefile", "rb").read() cur.execute("insert into foo values(?)", (largedata,)) SQLite 3.5 allowed for incremental Blob I/O so you can read and write blobs in small amounts. You cannot change the size of a blob so you need to reserve space which you do through zeroblob which creates a blob of the specified size but full of zero bytes. For example you would reserve space for your 100MB one of these two ways:: cur.execute("insert into foo values(zeroblob(100000000))") cur.execute("insert into foo values(?), (apsw.zeroblob(100000000),)) This class is used for the second way. Once a blob exists in the database, you then use the :class:`Blob` class to read and write its contents.""" def __init__(self, size: int): """:param size: Number of zeroed bytes to create""" ... def length(self) -> int: """Size of zero blob in bytes.""" ... SQLITE_ABORT: int = 4 """For `Result Codes '__""" SQLITE_ABORT_ROLLBACK: int = 516 """For `Extended Result Codes '__""" SQLITE_ACCESS_EXISTS: int = 0 """For `Flags for the xAccess VFS method '__""" SQLITE_ACCESS_READ: int = 2 """For `Flags for the xAccess VFS method '__""" SQLITE_ACCESS_READWRITE: int = 1 """For `Flags for the xAccess VFS method '__""" SQLITE_ALTER_TABLE: int = 26 """For `Authorizer Action Codes '__""" SQLITE_ANALYZE: int = 28 """For `Authorizer Action Codes '__""" SQLITE_ATTACH: int = 24 """For `Authorizer Action Codes '__""" SQLITE_AUTH: int = 23 """For `Result Codes '__""" SQLITE_AUTH_USER: int = 279 """For `Extended Result Codes '__""" SQLITE_BUSY: int = 5 """For `Result Codes '__""" SQLITE_BUSY_RECOVERY: int = 261 """For `Extended Result Codes '__""" SQLITE_BUSY_SNAPSHOT: int = 517 """For `Extended Result Codes '__""" SQLITE_BUSY_TIMEOUT: int = 773 """For `Extended Result Codes '__""" SQLITE_CANTOPEN: int = 14 """For `Result Codes '__""" SQLITE_CANTOPEN_CONVPATH: int = 1038 """For `Extended Result Codes '__""" SQLITE_CANTOPEN_DIRTYWAL: int = 1294 """For `Extended Result Codes '__""" SQLITE_CANTOPEN_FULLPATH: int = 782 """For `Extended Result Codes '__""" SQLITE_CANTOPEN_ISDIR: int = 526 """For `Extended Result Codes '__""" SQLITE_CANTOPEN_NOTEMPDIR: int = 270 """For `Extended Result Codes '__""" SQLITE_CANTOPEN_SYMLINK: int = 1550 """For `Extended Result Codes '__""" SQLITE_CHECKPOINT_FULL: int = 1 """For `Checkpoint Mode Values '__""" SQLITE_CHECKPOINT_PASSIVE: int = 0 """For `Checkpoint Mode Values '__""" SQLITE_CHECKPOINT_RESTART: int = 2 """For `Checkpoint Mode Values '__""" SQLITE_CHECKPOINT_TRUNCATE: int = 3 """For `Checkpoint Mode Values '__""" SQLITE_CONFIG_COVERING_INDEX_SCAN: int = 20 """For `Configuration Options '__""" SQLITE_CONFIG_GETMALLOC: int = 5 """For `Configuration Options '__""" SQLITE_CONFIG_GETMUTEX: int = 11 """For `Configuration Options '__""" SQLITE_CONFIG_GETPCACHE: int = 15 """For `Configuration Options '__""" SQLITE_CONFIG_GETPCACHE2: int = 19 """For `Configuration Options '__""" SQLITE_CONFIG_HEAP: int = 8 """For `Configuration Options '__""" SQLITE_CONFIG_LOG: int = 16 """For `Configuration Options '__""" SQLITE_CONFIG_LOOKASIDE: int = 13 """For `Configuration Options '__""" SQLITE_CONFIG_MALLOC: int = 4 """For `Configuration Options '__""" SQLITE_CONFIG_MEMDB_MAXSIZE: int = 29 """For `Configuration Options '__""" SQLITE_CONFIG_MEMSTATUS: int = 9 """For `Configuration Options '__""" SQLITE_CONFIG_MMAP_SIZE: int = 22 """For `Configuration Options '__""" SQLITE_CONFIG_MULTITHREAD: int = 2 """For `Configuration Options '__""" SQLITE_CONFIG_MUTEX: int = 10 """For `Configuration Options '__""" SQLITE_CONFIG_PAGECACHE: int = 7 """For `Configuration Options '__""" SQLITE_CONFIG_PCACHE: int = 14 """For `Configuration Options '__""" SQLITE_CONFIG_PCACHE2: int = 18 """For `Configuration Options '__""" SQLITE_CONFIG_PCACHE_HDRSZ: int = 24 """For `Configuration Options '__""" SQLITE_CONFIG_PMASZ: int = 25 """For `Configuration Options '__""" SQLITE_CONFIG_SCRATCH: int = 6 """For `Configuration Options '__""" SQLITE_CONFIG_SERIALIZED: int = 3 """For `Configuration Options '__""" SQLITE_CONFIG_SINGLETHREAD: int = 1 """For `Configuration Options '__""" SQLITE_CONFIG_SMALL_MALLOC: int = 27 """For `Configuration Options '__""" SQLITE_CONFIG_SORTERREF_SIZE: int = 28 """For `Configuration Options '__""" SQLITE_CONFIG_SQLLOG: int = 21 """For `Configuration Options '__""" SQLITE_CONFIG_STMTJRNL_SPILL: int = 26 """For `Configuration Options '__""" SQLITE_CONFIG_URI: int = 17 """For `Configuration Options '__""" SQLITE_CONFIG_WIN32_HEAPSIZE: int = 23 """For `Configuration Options '__""" SQLITE_CONSTRAINT: int = 19 """For `Result Codes '__""" SQLITE_CONSTRAINT_CHECK: int = 275 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_COMMITHOOK: int = 531 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_DATATYPE: int = 3091 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_FOREIGNKEY: int = 787 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_FUNCTION: int = 1043 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_NOTNULL: int = 1299 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_PINNED: int = 2835 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_PRIMARYKEY: int = 1555 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_ROWID: int = 2579 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_TRIGGER: int = 1811 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_UNIQUE: int = 2067 """For `Extended Result Codes '__""" SQLITE_CONSTRAINT_VTAB: int = 2323 """For `Extended Result Codes '__""" SQLITE_COPY: int = 0 """For `Authorizer Action Codes '__""" SQLITE_CORRUPT: int = 11 """For `Result Codes '__""" SQLITE_CORRUPT_INDEX: int = 779 """For `Extended Result Codes '__""" SQLITE_CORRUPT_SEQUENCE: int = 523 """For `Extended Result Codes '__""" SQLITE_CORRUPT_VTAB: int = 267 """For `Extended Result Codes '__""" SQLITE_CREATE_INDEX: int = 1 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TABLE: int = 2 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TEMP_INDEX: int = 3 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TEMP_TABLE: int = 4 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TEMP_TRIGGER: int = 5 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TEMP_VIEW: int = 6 """For `Authorizer Action Codes '__""" SQLITE_CREATE_TRIGGER: int = 7 """For `Authorizer Action Codes '__""" SQLITE_CREATE_VIEW: int = 8 """For `Authorizer Action Codes '__""" SQLITE_CREATE_VTABLE: int = 29 """For `Authorizer Action Codes '__""" SQLITE_DBCONFIG_DEFENSIVE: int = 1010 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_DQS_DDL: int = 1014 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_DQS_DML: int = 1013 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_FKEY: int = 1002 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER: int = 1004 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION: int = 1005 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_QPSG: int = 1007 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_TRIGGER: int = 1003 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_ENABLE_VIEW: int = 1015 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_LEGACY_ALTER_TABLE: int = 1012 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_LEGACY_FILE_FORMAT: int = 1016 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_LOOKASIDE: int = 1001 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_MAINDBNAME: int = 1000 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_MAX: int = 1017 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE: int = 1006 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_RESET_DATABASE: int = 1009 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_TRIGGER_EQP: int = 1008 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_TRUSTED_SCHEMA: int = 1017 """For `Database Connection Configuration Options '__""" SQLITE_DBCONFIG_WRITABLE_SCHEMA: int = 1011 """For `Database Connection Configuration Options '__""" SQLITE_DBSTATUS_CACHE_HIT: int = 7 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_CACHE_MISS: int = 8 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_CACHE_SPILL: int = 12 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_CACHE_USED: int = 1 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_CACHE_USED_SHARED: int = 11 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_CACHE_WRITE: int = 9 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_DEFERRED_FKS: int = 10 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_LOOKASIDE_HIT: int = 4 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL: int = 6 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE: int = 5 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_LOOKASIDE_USED: int = 0 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_MAX: int = 12 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_SCHEMA_USED: int = 2 """For `Status Parameters for database connections '__""" SQLITE_DBSTATUS_STMT_USED: int = 3 """For `Status Parameters for database connections '__""" SQLITE_DELETE: int = 9 """For `Authorizer Action Codes '__""" SQLITE_DENY: int = 1 """For `Authorizer Return Codes '__""" SQLITE_DETACH: int = 25 """For `Authorizer Action Codes '__""" SQLITE_DETERMINISTIC: int = 2048 """For `Function Flags '__""" SQLITE_DIRECTONLY: int = 524288 """For `Function Flags '__""" SQLITE_DONE: int = 101 """For `Result Codes '__""" SQLITE_DROP_INDEX: int = 10 """For `Authorizer Action Codes '__""" SQLITE_DROP_TABLE: int = 11 """For `Authorizer Action Codes '__""" SQLITE_DROP_TEMP_INDEX: int = 12 """For `Authorizer Action Codes '__""" SQLITE_DROP_TEMP_TABLE: int = 13 """For `Authorizer Action Codes '__""" SQLITE_DROP_TEMP_TRIGGER: int = 14 """For `Authorizer Action Codes '__""" SQLITE_DROP_TEMP_VIEW: int = 15 """For `Authorizer Action Codes '__""" SQLITE_DROP_TRIGGER: int = 16 """For `Authorizer Action Codes '__""" SQLITE_DROP_VIEW: int = 17 """For `Authorizer Action Codes '__""" SQLITE_DROP_VTABLE: int = 30 """For `Authorizer Action Codes '__""" SQLITE_EMPTY: int = 16 """For `Result Codes '__""" SQLITE_ERROR: int = 1 """For `Result Codes '__""" SQLITE_ERROR_MISSING_COLLSEQ: int = 257 """For `Extended Result Codes '__""" SQLITE_ERROR_RETRY: int = 513 """For `Extended Result Codes '__""" SQLITE_ERROR_SNAPSHOT: int = 769 """For `Extended Result Codes '__""" SQLITE_FAIL: int = 3 """For `Conflict resolution modes '__""" SQLITE_FCNTL_BEGIN_ATOMIC_WRITE: int = 31 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_BUSYHANDLER: int = 15 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_CHUNK_SIZE: int = 6 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_CKPT_DONE: int = 37 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_CKPT_START: int = 39 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_CKSM_FILE: int = 41 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_COMMIT_ATOMIC_WRITE: int = 32 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_COMMIT_PHASETWO: int = 22 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_DATA_VERSION: int = 35 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_EXTERNAL_READER: int = 40 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_FILE_POINTER: int = 7 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_GET_LOCKPROXYFILE: int = 2 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_HAS_MOVED: int = 20 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_JOURNAL_POINTER: int = 28 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_LAST_ERRNO: int = 4 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_LOCKSTATE: int = 1 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_LOCK_TIMEOUT: int = 34 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_MMAP_SIZE: int = 18 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_OVERWRITE: int = 11 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_PDB: int = 30 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_PERSIST_WAL: int = 10 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_POWERSAFE_OVERWRITE: int = 13 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_PRAGMA: int = 14 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_RBU: int = 26 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_RESERVE_BYTES: int = 38 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_RESET_CACHE: int = 42 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE: int = 33 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_SET_LOCKPROXYFILE: int = 3 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_SIZE_HINT: int = 5 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_SIZE_LIMIT: int = 36 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_SYNC: int = 21 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_SYNC_OMITTED: int = 8 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_TEMPFILENAME: int = 16 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_TRACE: int = 19 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_VFSNAME: int = 12 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_VFS_POINTER: int = 27 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_WAL_BLOCK: int = 24 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_WIN32_AV_RETRY: int = 9 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_WIN32_GET_HANDLE: int = 29 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_WIN32_SET_HANDLE: int = 23 """For `Standard File Control Opcodes '__""" SQLITE_FCNTL_ZIPVFS: int = 25 """For `Standard File Control Opcodes '__""" SQLITE_FORMAT: int = 24 """For `Result Codes '__""" SQLITE_FULL: int = 13 """For `Result Codes '__""" SQLITE_FUNCTION: int = 31 """For `Authorizer Action Codes '__""" SQLITE_IGNORE: int = 2 """For `Authorizer Return Codes '__""" SQLITE_INDEX_CONSTRAINT_EQ: int = 2 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_FUNCTION: int = 150 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_GE: int = 32 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_GLOB: int = 66 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_GT: int = 4 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_IS: int = 72 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_ISNOT: int = 69 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_ISNOTNULL: int = 70 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_ISNULL: int = 71 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_LE: int = 8 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_LIKE: int = 65 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_LIMIT: int = 73 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_LT: int = 16 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_MATCH: int = 64 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_NE: int = 68 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_OFFSET: int = 74 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_CONSTRAINT_REGEXP: int = 67 """For `Virtual Table Constraint Operator Codes '__""" SQLITE_INDEX_SCAN_UNIQUE: int = 1 """For `Virtual Table Scan Flags '__""" SQLITE_INNOCUOUS: int = 2097152 """For `Function Flags '__""" SQLITE_INSERT: int = 18 """For `Authorizer Action Codes '__""" SQLITE_INTERNAL: int = 2 """For `Result Codes '__""" SQLITE_INTERRUPT: int = 9 """For `Result Codes '__""" SQLITE_IOCAP_ATOMIC: int = 1 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC16K: int = 64 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC1K: int = 4 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC2K: int = 8 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC32K: int = 128 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC4K: int = 16 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC512: int = 2 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC64K: int = 256 """For `Device Characteristics '__""" SQLITE_IOCAP_ATOMIC8K: int = 32 """For `Device Characteristics '__""" SQLITE_IOCAP_BATCH_ATOMIC: int = 16384 """For `Device Characteristics '__""" SQLITE_IOCAP_IMMUTABLE: int = 8192 """For `Device Characteristics '__""" SQLITE_IOCAP_POWERSAFE_OVERWRITE: int = 4096 """For `Device Characteristics '__""" SQLITE_IOCAP_SAFE_APPEND: int = 512 """For `Device Characteristics '__""" SQLITE_IOCAP_SEQUENTIAL: int = 1024 """For `Device Characteristics '__""" SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN: int = 2048 """For `Device Characteristics '__""" SQLITE_IOERR: int = 10 """For `Result Codes '__""" SQLITE_IOERR_ACCESS: int = 3338 """For `Extended Result Codes '__""" SQLITE_IOERR_AUTH: int = 7178 """For `Extended Result Codes '__""" SQLITE_IOERR_BEGIN_ATOMIC: int = 7434 """For `Extended Result Codes '__""" SQLITE_IOERR_BLOCKED: int = 2826 """For `Extended Result Codes '__""" SQLITE_IOERR_CHECKRESERVEDLOCK: int = 3594 """For `Extended Result Codes '__""" SQLITE_IOERR_CLOSE: int = 4106 """For `Extended Result Codes '__""" SQLITE_IOERR_COMMIT_ATOMIC: int = 7690 """For `Extended Result Codes '__""" SQLITE_IOERR_CONVPATH: int = 6666 """For `Extended Result Codes '__""" SQLITE_IOERR_CORRUPTFS: int = 8458 """For `Extended Result Codes '__""" SQLITE_IOERR_DATA: int = 8202 """For `Extended Result Codes '__""" SQLITE_IOERR_DELETE: int = 2570 """For `Extended Result Codes '__""" SQLITE_IOERR_DELETE_NOENT: int = 5898 """For `Extended Result Codes '__""" SQLITE_IOERR_DIR_CLOSE: int = 4362 """For `Extended Result Codes '__""" SQLITE_IOERR_DIR_FSYNC: int = 1290 """For `Extended Result Codes '__""" SQLITE_IOERR_FSTAT: int = 1802 """For `Extended Result Codes '__""" SQLITE_IOERR_FSYNC: int = 1034 """For `Extended Result Codes '__""" SQLITE_IOERR_GETTEMPPATH: int = 6410 """For `Extended Result Codes '__""" SQLITE_IOERR_LOCK: int = 3850 """For `Extended Result Codes '__""" SQLITE_IOERR_MMAP: int = 6154 """For `Extended Result Codes '__""" SQLITE_IOERR_NOMEM: int = 3082 """For `Extended Result Codes '__""" SQLITE_IOERR_RDLOCK: int = 2314 """For `Extended Result Codes '__""" SQLITE_IOERR_READ: int = 266 """For `Extended Result Codes '__""" SQLITE_IOERR_ROLLBACK_ATOMIC: int = 7946 """For `Extended Result Codes '__""" SQLITE_IOERR_SEEK: int = 5642 """For `Extended Result Codes '__""" SQLITE_IOERR_SHMLOCK: int = 5130 """For `Extended Result Codes '__""" SQLITE_IOERR_SHMMAP: int = 5386 """For `Extended Result Codes '__""" SQLITE_IOERR_SHMOPEN: int = 4618 """For `Extended Result Codes '__""" SQLITE_IOERR_SHMSIZE: int = 4874 """For `Extended Result Codes '__""" SQLITE_IOERR_SHORT_READ: int = 522 """For `Extended Result Codes '__""" SQLITE_IOERR_TRUNCATE: int = 1546 """For `Extended Result Codes '__""" SQLITE_IOERR_UNLOCK: int = 2058 """For `Extended Result Codes '__""" SQLITE_IOERR_VNODE: int = 6922 """For `Extended Result Codes '__""" SQLITE_IOERR_WRITE: int = 778 """For `Extended Result Codes '__""" SQLITE_LIMIT_ATTACHED: int = 7 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_COLUMN: int = 2 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_COMPOUND_SELECT: int = 4 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_EXPR_DEPTH: int = 3 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_FUNCTION_ARG: int = 6 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_LENGTH: int = 0 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_LIKE_PATTERN_LENGTH: int = 8 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_SQL_LENGTH: int = 1 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_TRIGGER_DEPTH: int = 10 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_VARIABLE_NUMBER: int = 9 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_VDBE_OP: int = 5 """For `Run-Time Limit Categories '__""" SQLITE_LIMIT_WORKER_THREADS: int = 11 """For `Run-Time Limit Categories '__""" SQLITE_LOCKED: int = 6 """For `Result Codes '__""" SQLITE_LOCKED_SHAREDCACHE: int = 262 """For `Extended Result Codes '__""" SQLITE_LOCKED_VTAB: int = 518 """For `Extended Result Codes '__""" SQLITE_LOCK_EXCLUSIVE: int = 4 """For `File Locking Levels '__""" SQLITE_LOCK_NONE: int = 0 """For `File Locking Levels '__""" SQLITE_LOCK_PENDING: int = 3 """For `File Locking Levels '__""" SQLITE_LOCK_RESERVED: int = 2 """For `File Locking Levels '__""" SQLITE_LOCK_SHARED: int = 1 """For `File Locking Levels '__""" SQLITE_MISMATCH: int = 20 """For `Result Codes '__""" SQLITE_MISUSE: int = 21 """For `Result Codes '__""" SQLITE_NOLFS: int = 22 """For `Result Codes '__""" SQLITE_NOMEM: int = 7 """For `Result Codes '__""" SQLITE_NOTADB: int = 26 """For `Result Codes '__""" SQLITE_NOTFOUND: int = 12 """For `Result Codes '__""" SQLITE_NOTICE: int = 27 """For `Result Codes '__""" SQLITE_NOTICE_RECOVER_ROLLBACK: int = 539 """For `Extended Result Codes '__""" SQLITE_NOTICE_RECOVER_WAL: int = 283 """For `Extended Result Codes '__""" SQLITE_OK: int = 0 """For `Result Codes '__""" SQLITE_OK_LOAD_PERMANENTLY: int = 256 """For `Extended Result Codes '__""" SQLITE_OK_SYMLINK: int = 512 """For `Extended Result Codes '__""" SQLITE_OPEN_AUTOPROXY: int = 32 """For `Flags For File Open Operations '__""" SQLITE_OPEN_CREATE: int = 4 """For `Flags For File Open Operations '__""" SQLITE_OPEN_DELETEONCLOSE: int = 8 """For `Flags For File Open Operations '__""" SQLITE_OPEN_EXCLUSIVE: int = 16 """For `Flags For File Open Operations '__""" SQLITE_OPEN_EXRESCODE: int = 33554432 """For `Flags For File Open Operations '__""" SQLITE_OPEN_FULLMUTEX: int = 65536 """For `Flags For File Open Operations '__""" SQLITE_OPEN_MAIN_DB: int = 256 """For `Flags For File Open Operations '__""" SQLITE_OPEN_MAIN_JOURNAL: int = 2048 """For `Flags For File Open Operations '__""" SQLITE_OPEN_MEMORY: int = 128 """For `Flags For File Open Operations '__""" SQLITE_OPEN_NOFOLLOW: int = 16777216 """For `Flags For File Open Operations '__""" SQLITE_OPEN_NOMUTEX: int = 32768 """For `Flags For File Open Operations '__""" SQLITE_OPEN_PRIVATECACHE: int = 262144 """For `Flags For File Open Operations '__""" SQLITE_OPEN_READONLY: int = 1 """For `Flags For File Open Operations '__""" SQLITE_OPEN_READWRITE: int = 2 """For `Flags For File Open Operations '__""" SQLITE_OPEN_SHAREDCACHE: int = 131072 """For `Flags For File Open Operations '__""" SQLITE_OPEN_SUBJOURNAL: int = 8192 """For `Flags For File Open Operations '__""" SQLITE_OPEN_SUPER_JOURNAL: int = 16384 """For `Flags For File Open Operations '__""" SQLITE_OPEN_TEMP_DB: int = 512 """For `Flags For File Open Operations '__""" SQLITE_OPEN_TEMP_JOURNAL: int = 4096 """For `Flags For File Open Operations '__""" SQLITE_OPEN_TRANSIENT_DB: int = 1024 """For `Flags For File Open Operations '__""" SQLITE_OPEN_URI: int = 64 """For `Flags For File Open Operations '__""" SQLITE_OPEN_WAL: int = 524288 """For `Flags For File Open Operations '__""" SQLITE_PERM: int = 3 """For `Result Codes '__""" SQLITE_PRAGMA: int = 19 """For `Authorizer Action Codes '__""" SQLITE_PREPARE_NORMALIZE: int = 2 """For `Prepare Flags '__""" SQLITE_PREPARE_NO_VTAB: int = 4 """For `Prepare Flags '__""" SQLITE_PREPARE_PERSISTENT: int = 1 """For `Prepare Flags '__""" SQLITE_PROTOCOL: int = 15 """For `Result Codes '__""" SQLITE_RANGE: int = 25 """For `Result Codes '__""" SQLITE_READ: int = 20 """For `Authorizer Action Codes '__""" SQLITE_READONLY: int = 8 """For `Result Codes '__""" SQLITE_READONLY_CANTINIT: int = 1288 """For `Extended Result Codes '__""" SQLITE_READONLY_CANTLOCK: int = 520 """For `Extended Result Codes '__""" SQLITE_READONLY_DBMOVED: int = 1032 """For `Extended Result Codes '__""" SQLITE_READONLY_DIRECTORY: int = 1544 """For `Extended Result Codes '__""" SQLITE_READONLY_RECOVERY: int = 264 """For `Extended Result Codes '__""" SQLITE_READONLY_ROLLBACK: int = 776 """For `Extended Result Codes '__""" SQLITE_RECURSIVE: int = 33 """For `Authorizer Action Codes '__""" SQLITE_REINDEX: int = 27 """For `Authorizer Action Codes '__""" SQLITE_REPLACE: int = 5 """For `Conflict resolution modes '__""" SQLITE_ROLLBACK: int = 1 """For `Conflict resolution modes '__""" SQLITE_ROW: int = 100 """For `Result Codes '__""" SQLITE_SAVEPOINT: int = 32 """For `Authorizer Action Codes '__""" SQLITE_SCHEMA: int = 17 """For `Result Codes '__""" SQLITE_SELECT: int = 21 """For `Authorizer Action Codes '__""" SQLITE_SHM_EXCLUSIVE: int = 8 """For `Flags for the xShmLock VFS method '__""" SQLITE_SHM_LOCK: int = 2 """For `Flags for the xShmLock VFS method '__""" SQLITE_SHM_SHARED: int = 4 """For `Flags for the xShmLock VFS method '__""" SQLITE_SHM_UNLOCK: int = 1 """For `Flags for the xShmLock VFS method '__""" SQLITE_STATUS_MALLOC_COUNT: int = 9 """For `Status Parameters '__""" SQLITE_STATUS_MALLOC_SIZE: int = 5 """For `Status Parameters '__""" SQLITE_STATUS_MEMORY_USED: int = 0 """For `Status Parameters '__""" SQLITE_STATUS_PAGECACHE_OVERFLOW: int = 2 """For `Status Parameters '__""" SQLITE_STATUS_PAGECACHE_SIZE: int = 7 """For `Status Parameters '__""" SQLITE_STATUS_PAGECACHE_USED: int = 1 """For `Status Parameters '__""" SQLITE_STATUS_PARSER_STACK: int = 6 """For `Status Parameters '__""" SQLITE_STATUS_SCRATCH_OVERFLOW: int = 4 """For `Status Parameters '__""" SQLITE_STATUS_SCRATCH_SIZE: int = 8 """For `Status Parameters '__""" SQLITE_STATUS_SCRATCH_USED: int = 3 """For `Status Parameters '__""" SQLITE_STMTSTATUS_AUTOINDEX: int = 3 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_FILTER_HIT: int = 8 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_FILTER_MISS: int = 7 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_FULLSCAN_STEP: int = 1 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_MEMUSED: int = 99 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_REPREPARE: int = 5 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_RUN: int = 6 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_SORT: int = 2 """For `Status Parameters for prepared statements '__""" SQLITE_STMTSTATUS_VM_STEP: int = 4 """For `Status Parameters for prepared statements '__""" SQLITE_SUBTYPE: int = 1048576 """For `Function Flags '__""" SQLITE_SYNC_DATAONLY: int = 16 """For `Synchronization Type Flags '__""" SQLITE_SYNC_FULL: int = 3 """For `Synchronization Type Flags '__""" SQLITE_SYNC_NORMAL: int = 2 """For `Synchronization Type Flags '__""" SQLITE_TOOBIG: int = 18 """For `Result Codes '__""" SQLITE_TRACE_CLOSE: int = 8 """For `SQL Trace Event Codes '__""" SQLITE_TRACE_PROFILE: int = 2 """For `SQL Trace Event Codes '__""" SQLITE_TRACE_ROW: int = 4 """For `SQL Trace Event Codes '__""" SQLITE_TRACE_STMT: int = 1 """For `SQL Trace Event Codes '__""" SQLITE_TRANSACTION: int = 22 """For `Authorizer Action Codes '__""" SQLITE_TXN_NONE: int = 0 """For `Allowed return values from [sqlite3_txn_state()] '__""" SQLITE_TXN_READ: int = 1 """For `Allowed return values from [sqlite3_txn_state()] '__""" SQLITE_TXN_WRITE: int = 2 """For `Allowed return values from [sqlite3_txn_state()] '__""" SQLITE_UPDATE: int = 23 """For `Authorizer Action Codes '__""" SQLITE_VTAB_CONSTRAINT_SUPPORT: int = 1 """For `Virtual Table Configuration Options '__""" SQLITE_VTAB_DIRECTONLY: int = 3 """For `Virtual Table Configuration Options '__""" SQLITE_VTAB_INNOCUOUS: int = 2 """For `Virtual Table Configuration Options '__""" SQLITE_WARNING: int = 28 """For `Result Codes '__""" SQLITE_WARNING_AUTOINDEX: int = 284 """For `Extended Result Codes '__""" mapping_access: Dict[Union[str,int],Union[int,str]] """Flags for the xAccess VFS method mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_access_exists.html SQLITE_ACCESS_EXISTS SQLITE_ACCESS_READ SQLITE_ACCESS_READWRITE""" mapping_authorizer_function: Dict[Union[str,int],Union[int,str]] """Authorizer Action Codes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_alter_table.html SQLITE_ALTER_TABLE SQLITE_ANALYZE SQLITE_ATTACH SQLITE_COPY SQLITE_CREATE_INDEX SQLITE_CREATE_TABLE SQLITE_CREATE_TEMP_INDEX SQLITE_CREATE_TEMP_TABLE SQLITE_CREATE_TEMP_TRIGGER SQLITE_CREATE_TEMP_VIEW SQLITE_CREATE_TRIGGER SQLITE_CREATE_VIEW SQLITE_CREATE_VTABLE SQLITE_DELETE SQLITE_DETACH SQLITE_DROP_INDEX SQLITE_DROP_TABLE SQLITE_DROP_TEMP_INDEX SQLITE_DROP_TEMP_TABLE SQLITE_DROP_TEMP_TRIGGER SQLITE_DROP_TEMP_VIEW SQLITE_DROP_TRIGGER SQLITE_DROP_VIEW SQLITE_DROP_VTABLE SQLITE_FUNCTION SQLITE_INSERT SQLITE_PRAGMA SQLITE_READ SQLITE_RECURSIVE SQLITE_REINDEX SQLITE_SAVEPOINT SQLITE_SELECT SQLITE_TRANSACTION SQLITE_UPDATE""" mapping_authorizer_return: Dict[Union[str,int],Union[int,str]] """Authorizer Return Codes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_deny.html SQLITE_DENY SQLITE_IGNORE""" mapping_bestindex_constraints: Dict[Union[str,int],Union[int,str]] """Virtual Table Constraint Operator Codes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_index_constraint_eq.html SQLITE_INDEX_CONSTRAINT_EQ SQLITE_INDEX_CONSTRAINT_FUNCTION SQLITE_INDEX_CONSTRAINT_GE SQLITE_INDEX_CONSTRAINT_GLOB SQLITE_INDEX_CONSTRAINT_GT SQLITE_INDEX_CONSTRAINT_IS SQLITE_INDEX_CONSTRAINT_ISNOT SQLITE_INDEX_CONSTRAINT_ISNOTNULL SQLITE_INDEX_CONSTRAINT_ISNULL SQLITE_INDEX_CONSTRAINT_LE SQLITE_INDEX_CONSTRAINT_LIKE SQLITE_INDEX_CONSTRAINT_LIMIT SQLITE_INDEX_CONSTRAINT_LT SQLITE_INDEX_CONSTRAINT_MATCH SQLITE_INDEX_CONSTRAINT_NE SQLITE_INDEX_CONSTRAINT_OFFSET SQLITE_INDEX_CONSTRAINT_REGEXP""" mapping_config: Dict[Union[str,int],Union[int,str]] """Configuration Options mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_config_covering_index_scan.html SQLITE_CONFIG_COVERING_INDEX_SCAN SQLITE_CONFIG_GETMALLOC SQLITE_CONFIG_GETMUTEX SQLITE_CONFIG_GETPCACHE SQLITE_CONFIG_GETPCACHE2 SQLITE_CONFIG_HEAP SQLITE_CONFIG_LOG SQLITE_CONFIG_LOOKASIDE SQLITE_CONFIG_MALLOC SQLITE_CONFIG_MEMDB_MAXSIZE SQLITE_CONFIG_MEMSTATUS SQLITE_CONFIG_MMAP_SIZE SQLITE_CONFIG_MULTITHREAD SQLITE_CONFIG_MUTEX SQLITE_CONFIG_PAGECACHE SQLITE_CONFIG_PCACHE SQLITE_CONFIG_PCACHE2 SQLITE_CONFIG_PCACHE_HDRSZ SQLITE_CONFIG_PMASZ SQLITE_CONFIG_SCRATCH SQLITE_CONFIG_SERIALIZED SQLITE_CONFIG_SINGLETHREAD SQLITE_CONFIG_SMALL_MALLOC SQLITE_CONFIG_SORTERREF_SIZE SQLITE_CONFIG_SQLLOG SQLITE_CONFIG_STMTJRNL_SPILL SQLITE_CONFIG_URI SQLITE_CONFIG_WIN32_HEAPSIZE""" mapping_conflict_resolution_modes: Dict[Union[str,int],Union[int,str]] """Conflict resolution modes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_fail.html SQLITE_FAIL SQLITE_REPLACE SQLITE_ROLLBACK""" mapping_db_config: Dict[Union[str,int],Union[int,str]] """Database Connection Configuration Options mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_dbconfig_defensive.html SQLITE_DBCONFIG_DEFENSIVE SQLITE_DBCONFIG_DQS_DDL SQLITE_DBCONFIG_DQS_DML SQLITE_DBCONFIG_ENABLE_FKEY SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION SQLITE_DBCONFIG_ENABLE_QPSG SQLITE_DBCONFIG_ENABLE_TRIGGER SQLITE_DBCONFIG_ENABLE_VIEW SQLITE_DBCONFIG_LEGACY_ALTER_TABLE SQLITE_DBCONFIG_LEGACY_FILE_FORMAT SQLITE_DBCONFIG_LOOKASIDE SQLITE_DBCONFIG_MAINDBNAME SQLITE_DBCONFIG_MAX SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE SQLITE_DBCONFIG_RESET_DATABASE SQLITE_DBCONFIG_TRIGGER_EQP SQLITE_DBCONFIG_TRUSTED_SCHEMA SQLITE_DBCONFIG_WRITABLE_SCHEMA""" mapping_db_status: Dict[Union[str,int],Union[int,str]] """Status Parameters for database connections mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_dbstatus_options.html SQLITE_DBSTATUS_CACHE_HIT SQLITE_DBSTATUS_CACHE_MISS SQLITE_DBSTATUS_CACHE_SPILL SQLITE_DBSTATUS_CACHE_USED SQLITE_DBSTATUS_CACHE_USED_SHARED SQLITE_DBSTATUS_CACHE_WRITE SQLITE_DBSTATUS_DEFERRED_FKS SQLITE_DBSTATUS_LOOKASIDE_HIT SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE SQLITE_DBSTATUS_LOOKASIDE_USED SQLITE_DBSTATUS_MAX SQLITE_DBSTATUS_SCHEMA_USED SQLITE_DBSTATUS_STMT_USED""" mapping_device_characteristics: Dict[Union[str,int],Union[int,str]] """Device Characteristics mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_iocap_atomic.html SQLITE_IOCAP_ATOMIC SQLITE_IOCAP_ATOMIC16K SQLITE_IOCAP_ATOMIC1K SQLITE_IOCAP_ATOMIC2K SQLITE_IOCAP_ATOMIC32K SQLITE_IOCAP_ATOMIC4K SQLITE_IOCAP_ATOMIC512 SQLITE_IOCAP_ATOMIC64K SQLITE_IOCAP_ATOMIC8K SQLITE_IOCAP_BATCH_ATOMIC SQLITE_IOCAP_IMMUTABLE SQLITE_IOCAP_POWERSAFE_OVERWRITE SQLITE_IOCAP_SAFE_APPEND SQLITE_IOCAP_SEQUENTIAL SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN""" mapping_extended_result_codes: Dict[Union[str,int],Union[int,str]] """Extended Result Codes mapping names to int and int to names. Doc at https://sqlite.org/rescode.html SQLITE_ABORT_ROLLBACK SQLITE_AUTH_USER SQLITE_BUSY_RECOVERY SQLITE_BUSY_SNAPSHOT SQLITE_BUSY_TIMEOUT SQLITE_CANTOPEN_CONVPATH SQLITE_CANTOPEN_DIRTYWAL SQLITE_CANTOPEN_FULLPATH SQLITE_CANTOPEN_ISDIR SQLITE_CANTOPEN_NOTEMPDIR SQLITE_CANTOPEN_SYMLINK SQLITE_CONSTRAINT_CHECK SQLITE_CONSTRAINT_COMMITHOOK SQLITE_CONSTRAINT_DATATYPE SQLITE_CONSTRAINT_FOREIGNKEY SQLITE_CONSTRAINT_FUNCTION SQLITE_CONSTRAINT_NOTNULL SQLITE_CONSTRAINT_PINNED SQLITE_CONSTRAINT_PRIMARYKEY SQLITE_CONSTRAINT_ROWID SQLITE_CONSTRAINT_TRIGGER SQLITE_CONSTRAINT_UNIQUE SQLITE_CONSTRAINT_VTAB SQLITE_CORRUPT_INDEX SQLITE_CORRUPT_SEQUENCE SQLITE_CORRUPT_VTAB SQLITE_ERROR_MISSING_COLLSEQ SQLITE_ERROR_RETRY SQLITE_ERROR_SNAPSHOT SQLITE_IOERR_ACCESS SQLITE_IOERR_AUTH SQLITE_IOERR_BEGIN_ATOMIC SQLITE_IOERR_BLOCKED SQLITE_IOERR_CHECKRESERVEDLOCK SQLITE_IOERR_CLOSE SQLITE_IOERR_COMMIT_ATOMIC SQLITE_IOERR_CONVPATH SQLITE_IOERR_CORRUPTFS SQLITE_IOERR_DATA SQLITE_IOERR_DELETE SQLITE_IOERR_DELETE_NOENT SQLITE_IOERR_DIR_CLOSE SQLITE_IOERR_DIR_FSYNC SQLITE_IOERR_FSTAT SQLITE_IOERR_FSYNC SQLITE_IOERR_GETTEMPPATH SQLITE_IOERR_LOCK SQLITE_IOERR_MMAP SQLITE_IOERR_NOMEM SQLITE_IOERR_RDLOCK SQLITE_IOERR_READ SQLITE_IOERR_ROLLBACK_ATOMIC SQLITE_IOERR_SEEK SQLITE_IOERR_SHMLOCK SQLITE_IOERR_SHMMAP SQLITE_IOERR_SHMOPEN SQLITE_IOERR_SHMSIZE SQLITE_IOERR_SHORT_READ SQLITE_IOERR_TRUNCATE SQLITE_IOERR_UNLOCK SQLITE_IOERR_VNODE SQLITE_IOERR_WRITE SQLITE_LOCKED_SHAREDCACHE SQLITE_LOCKED_VTAB SQLITE_NOTICE_RECOVER_ROLLBACK SQLITE_NOTICE_RECOVER_WAL SQLITE_OK_LOAD_PERMANENTLY SQLITE_OK_SYMLINK SQLITE_READONLY_CANTINIT SQLITE_READONLY_CANTLOCK SQLITE_READONLY_DBMOVED SQLITE_READONLY_DIRECTORY SQLITE_READONLY_RECOVERY SQLITE_READONLY_ROLLBACK SQLITE_WARNING_AUTOINDEX""" mapping_file_control: Dict[Union[str,int],Union[int,str]] """Standard File Control Opcodes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html SQLITE_FCNTL_BEGIN_ATOMIC_WRITE SQLITE_FCNTL_BUSYHANDLER SQLITE_FCNTL_CHUNK_SIZE SQLITE_FCNTL_CKPT_DONE SQLITE_FCNTL_CKPT_START SQLITE_FCNTL_CKSM_FILE SQLITE_FCNTL_COMMIT_ATOMIC_WRITE SQLITE_FCNTL_COMMIT_PHASETWO SQLITE_FCNTL_DATA_VERSION SQLITE_FCNTL_EXTERNAL_READER SQLITE_FCNTL_FILE_POINTER SQLITE_FCNTL_GET_LOCKPROXYFILE SQLITE_FCNTL_HAS_MOVED SQLITE_FCNTL_JOURNAL_POINTER SQLITE_FCNTL_LAST_ERRNO SQLITE_FCNTL_LOCKSTATE SQLITE_FCNTL_LOCK_TIMEOUT SQLITE_FCNTL_MMAP_SIZE SQLITE_FCNTL_OVERWRITE SQLITE_FCNTL_PDB SQLITE_FCNTL_PERSIST_WAL SQLITE_FCNTL_POWERSAFE_OVERWRITE SQLITE_FCNTL_PRAGMA SQLITE_FCNTL_RBU SQLITE_FCNTL_RESERVE_BYTES SQLITE_FCNTL_RESET_CACHE SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE SQLITE_FCNTL_SET_LOCKPROXYFILE SQLITE_FCNTL_SIZE_HINT SQLITE_FCNTL_SIZE_LIMIT SQLITE_FCNTL_SYNC SQLITE_FCNTL_SYNC_OMITTED SQLITE_FCNTL_TEMPFILENAME SQLITE_FCNTL_TRACE SQLITE_FCNTL_VFSNAME SQLITE_FCNTL_VFS_POINTER SQLITE_FCNTL_WAL_BLOCK SQLITE_FCNTL_WIN32_AV_RETRY SQLITE_FCNTL_WIN32_GET_HANDLE SQLITE_FCNTL_WIN32_SET_HANDLE SQLITE_FCNTL_ZIPVFS""" mapping_function_flags: Dict[Union[str,int],Union[int,str]] """Function Flags mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_deterministic.html SQLITE_DETERMINISTIC SQLITE_DIRECTONLY SQLITE_INNOCUOUS SQLITE_SUBTYPE""" mapping_limits: Dict[Union[str,int],Union[int,str]] """Run-Time Limit Categories mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_limit_attached.html SQLITE_LIMIT_ATTACHED SQLITE_LIMIT_COLUMN SQLITE_LIMIT_COMPOUND_SELECT SQLITE_LIMIT_EXPR_DEPTH SQLITE_LIMIT_FUNCTION_ARG SQLITE_LIMIT_LENGTH SQLITE_LIMIT_LIKE_PATTERN_LENGTH SQLITE_LIMIT_SQL_LENGTH SQLITE_LIMIT_TRIGGER_DEPTH SQLITE_LIMIT_VARIABLE_NUMBER SQLITE_LIMIT_VDBE_OP SQLITE_LIMIT_WORKER_THREADS""" mapping_locking_level: Dict[Union[str,int],Union[int,str]] """File Locking Levels mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_lock_exclusive.html SQLITE_LOCK_EXCLUSIVE SQLITE_LOCK_NONE SQLITE_LOCK_PENDING SQLITE_LOCK_RESERVED SQLITE_LOCK_SHARED""" mapping_open_flags: Dict[Union[str,int],Union[int,str]] """Flags For File Open Operations mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_open_autoproxy.html SQLITE_OPEN_AUTOPROXY SQLITE_OPEN_CREATE SQLITE_OPEN_DELETEONCLOSE SQLITE_OPEN_EXCLUSIVE SQLITE_OPEN_EXRESCODE SQLITE_OPEN_FULLMUTEX SQLITE_OPEN_MAIN_DB SQLITE_OPEN_MAIN_JOURNAL SQLITE_OPEN_MEMORY SQLITE_OPEN_NOFOLLOW SQLITE_OPEN_NOMUTEX SQLITE_OPEN_PRIVATECACHE SQLITE_OPEN_READONLY SQLITE_OPEN_READWRITE SQLITE_OPEN_SHAREDCACHE SQLITE_OPEN_SUBJOURNAL SQLITE_OPEN_SUPER_JOURNAL SQLITE_OPEN_TEMP_DB SQLITE_OPEN_TEMP_JOURNAL SQLITE_OPEN_TRANSIENT_DB SQLITE_OPEN_URI SQLITE_OPEN_WAL""" mapping_prepare_flags: Dict[Union[str,int],Union[int,str]] """Prepare Flags mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_prepare_normalize.html SQLITE_PREPARE_NORMALIZE SQLITE_PREPARE_NO_VTAB SQLITE_PREPARE_PERSISTENT""" mapping_result_codes: Dict[Union[str,int],Union[int,str]] """Result Codes mapping names to int and int to names. Doc at https://sqlite.org/rescode.html SQLITE_ABORT SQLITE_AUTH SQLITE_BUSY SQLITE_CANTOPEN SQLITE_CONSTRAINT SQLITE_CORRUPT SQLITE_DONE SQLITE_EMPTY SQLITE_ERROR SQLITE_FORMAT SQLITE_FULL SQLITE_INTERNAL SQLITE_INTERRUPT SQLITE_IOERR SQLITE_LOCKED SQLITE_MISMATCH SQLITE_MISUSE SQLITE_NOLFS SQLITE_NOMEM SQLITE_NOTADB SQLITE_NOTFOUND SQLITE_NOTICE SQLITE_OK SQLITE_PERM SQLITE_PROTOCOL SQLITE_RANGE SQLITE_READONLY SQLITE_ROW SQLITE_SCHEMA SQLITE_TOOBIG SQLITE_WARNING""" mapping_statement_status: Dict[Union[str,int],Union[int,str]] """Status Parameters for prepared statements mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_stmtstatus_counter.html SQLITE_STMTSTATUS_AUTOINDEX SQLITE_STMTSTATUS_FILTER_HIT SQLITE_STMTSTATUS_FILTER_MISS SQLITE_STMTSTATUS_FULLSCAN_STEP SQLITE_STMTSTATUS_MEMUSED SQLITE_STMTSTATUS_REPREPARE SQLITE_STMTSTATUS_RUN SQLITE_STMTSTATUS_SORT SQLITE_STMTSTATUS_VM_STEP""" mapping_status: Dict[Union[str,int],Union[int,str]] """Status Parameters mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_status_malloc_count.html SQLITE_STATUS_MALLOC_COUNT SQLITE_STATUS_MALLOC_SIZE SQLITE_STATUS_MEMORY_USED SQLITE_STATUS_PAGECACHE_OVERFLOW SQLITE_STATUS_PAGECACHE_SIZE SQLITE_STATUS_PAGECACHE_USED SQLITE_STATUS_PARSER_STACK SQLITE_STATUS_SCRATCH_OVERFLOW SQLITE_STATUS_SCRATCH_SIZE SQLITE_STATUS_SCRATCH_USED""" mapping_sync: Dict[Union[str,int],Union[int,str]] """Synchronization Type Flags mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_sync_dataonly.html SQLITE_SYNC_DATAONLY SQLITE_SYNC_FULL SQLITE_SYNC_NORMAL""" mapping_trace_codes: Dict[Union[str,int],Union[int,str]] """SQL Trace Event Codes mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_trace.html SQLITE_TRACE SQLITE_TRACE_CLOSE SQLITE_TRACE_PROFILE SQLITE_TRACE_ROW SQLITE_TRACE_STMT""" mapping_txn_state: Dict[Union[str,int],Union[int,str]] """Allowed return values from [sqlite3_txn_state()] mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_txn_none.html SQLITE_TXN_NONE SQLITE_TXN_READ SQLITE_TXN_WRITE""" mapping_virtual_table_configuration_options: Dict[Union[str,int],Union[int,str]] """Virtual Table Configuration Options mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_vtab_constraint_support.html SQLITE_VTAB_CONSTRAINT_SUPPORT SQLITE_VTAB_DIRECTONLY SQLITE_VTAB_INNOCUOUS""" mapping_virtual_table_scan_flags: Dict[Union[str,int],Union[int,str]] """Virtual Table Scan Flags mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_index_scan_unique.html SQLITE_INDEX_SCAN_UNIQUE""" mapping_wal_checkpoint: Dict[Union[str,int],Union[int,str]] """Checkpoint Mode Values mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_checkpoint_full.html SQLITE_CHECKPOINT_FULL SQLITE_CHECKPOINT_PASSIVE SQLITE_CHECKPOINT_RESTART SQLITE_CHECKPOINT_TRUNCATE""" mapping_xshmlock_flags: Dict[Union[str,int],Union[int,str]] """Flags for the xShmLock VFS method mapping names to int and int to names. Doc at https://sqlite.org/c3ref/c_shm_exclusive.html SQLITE_SHM_EXCLUSIVE SQLITE_SHM_LOCK SQLITE_SHM_SHARED SQLITE_SHM_UNLOCK""" class Error(Exception): """ This is the base for APSW exceptions. .. attribute:: Error.result For exceptions corresponding to `SQLite error codes `_ codes this attribute is the numeric error code. .. attribute:: Error.extendedresult APSW runs with `extended result codes `_ turned on. This attribute includes the detailed code. .. attribute:: Error.error_offset The location of the error in the SQL when encoded in UTF-8. The value is from `sqlite3_error_offset `__.""" class AbortError(Error): """*SQLITE_ABORT*. Callback routine requested an abort.""" class AuthError(Error): """*SQLITE_AUTH*. :attr:`Authorization ` denied.""" class BindingsError(Error): """There are several causes for this exception. When using tuples, an incorrect number of bindings where supplied:: cursor.execute("select ?,?,?", (1,2)) # too few bindings cursor.execute("select ?,?,?", (1,2,3,4)) # too many bindings You are using named bindings, but not all bindings are named. You should either use entirely the named style or entirely numeric (unnamed) style:: cursor.execute("select * from foo where x=:name and y=?") .. note:: It is not considered an error to have missing keys in a dictionary. For example this is perfectly valid:: cursor.execute("insert into foo values($a,:b,$c)", {'a': 1}) *b* and *c* are not in the dict. For missing keys, None/NULL will be used. This is so you don't have to add lots of spurious values to the supplied dict. If your schema requires every column have a value, then SQLite will generate an error due to some values being None/NULL so that case will be caught.""" class BusyError(Error): """*SQLITE_BUSY*. The database file is locked. Use :meth:`Connection.setbusytimeout` to change how long SQLite waits for the database to be unlocked or :meth:`Connection.setbusyhandler` to use your own handler.""" class CantOpenError(Error): """*SQLITE_CANTOPEN*. Unable to open the database file.""" class ConnectionClosedError(Error): """You have called :meth:`Connection.close` and then continued to use the :class:`Connection` or associated :class:`cursors `.""" class ConnectionNotClosedError(Error): """This exception is no longer generated. It was required in earlier releases due to constraints in threading usage with SQLite.""" class ConstraintError(Error): """*SQLITE_CONSTRAINT*. Abort due to `constraint `_ violation. This would happen if the schema required a column to be within a specific range. If you have multiple constraints, you `can't tell `__ which one was the cause.""" class CorruptError(Error): """*SQLITE_CORRUPT*. The database disk image appears to be a SQLite database but the values inside are inconsistent.""" class CursorClosedError(Error): """You have called :meth:`Cursor.close` and then tried to use the cursor.""" class EmptyError(Error): """*SQLITE_EMPTY*. Database is completely empty.""" class ExecTraceAbort(Error): """The :ref:`execution tracer ` returned False so execution was aborted.""" class ExecutionCompleteError(Error): """A statement is complete but you try to run it more anyway!""" class ExtensionLoadingError(Error): """An error happened loading an `extension `_.""" class ForkingViolationError(Error): """See :meth:`apsw.fork_checker`.""" class FormatError(Error): """*SQLITE_FORMAT*. (No longer used) `Auxiliary database `_ format error.""" class FullError(Error): """*SQLITE_FULL*. The disk appears to be full.""" class IOError(Error): """*SQLITE_IOERR*. Some kind of disk I/O error occurred. The :ref:`extended error code ` will give more detail.""" class IncompleteExecutionError(Error): """You have tried to start a new SQL execute call before executing all the previous ones. See the :ref:`execution model ` for more details.""" class InternalError(Error): """*SQLITE_INTERNAL*. (No longer used) Internal logic error in SQLite.""" class InterruptError(Error): """*SQLITE_INTERRUPT*. Operation terminated by `sqlite3_interrupt `_ - use :meth:`Connection.interrupt`.""" class LockedError(Error): """*SQLITE_LOCKED*. A table in the database is locked.""" class MismatchError(Error): """*SQLITE_MISMATCH*. Data type mismatch. For example a rowid or integer primary key must be an integer.""" class MisuseError(Error): """*SQLITE_MISUSE*. SQLite library used incorrectly - typically similar to *ValueError* in Python. Examples include not having enough flags when opening a connection (eg not including a READ or WRITE flag), or out of spec such as registering a function with more than 127 parameters.""" class NoLFSError(Error): """*SQLITE_NOLFS*. SQLite has attempted to use a feature not supported by the operating system such as `large file support `_.""" class NoMemError(Error): """*SQLITE_NOMEM*. A memory allocation failed.""" class NotADBError(Error): """*SQLITE_NOTADB*. File opened that is not a database file. SQLite has a header on database files to verify they are indeed SQLite databases.""" class NotFoundError(Error): """*SQLITE_NOTFOUND*. Returned when various internal items were not found such as requests for non-existent system calls or file controls.""" class PermissionsError(Error): """*SQLITE_PERM*. Access permission denied by the operating system, or parts of the database are readonly such as a cursor.""" class ProtocolError(Error): """*SQLITE_PROTOCOL*. (No longer used) Database lock protocol error.""" class RangeError(Error): """*SQLITE_RANGE*. (Cannot be generated using APSW). 2nd parameter to `sqlite3_bind `_ out of range""" class ReadOnlyError(Error): """*SQLITE_READONLY*. Attempt to write to a readonly database.""" class SQLError(Error): """*SQLITE_ERROR*. This error is documented as a bad SQL query or missing database, but is also returned for a lot of other situations. It is the default error code unless there is a more specific one.""" class SchemaChangeError(Error): """*SQLITE_SCHEMA*. The database schema changed. A :meth:`prepared statement ` becomes invalid if the database schema was changed. Behind the scenes SQLite reprepares the statement. Another or the same :class:`Connection` may change the schema again before the statement runs. SQLite will attempt up to 5 times before giving up and returning this error.""" class ThreadingViolationError(Error): """You have used an object concurrently in two threads. For example you may try to use the same cursor in two different threads at the same time, or tried to close the same connection in two threads at the same time. You can also get this exception by using a cursor as an argument to itself (eg as the input data for :meth:`Cursor.executemany`). Cursors can only be used for one thing at a time.""" class TooBigError(Error): """*SQLITE_TOOBIG*. String or BLOB exceeds size limit. You can change the limits using :meth:`Connection.limit`.""" class VFSFileClosedError(Error): """The VFS file is closed so the operation cannot be performed.""" class VFSNotImplementedError(Error): """A call cannot be made to an inherited :ref:`VFS` method as the VFS does not implement the method."""