From 745281573db86efa2a89822f9055cc7c193db574 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 3 Aug 2022 23:15:01 +0200 Subject: [PATCH 1/9] gh-95273: Re-organize sqlite3 doc module level funcs and attrs Put module level functions before module level attributes, and (mostly) sort them alphabetically. This makes sqlite3.connect() the first encounter in the sqlite3 reference. --- Doc/library/sqlite3.rst | 303 +++++++++++++++++++--------------------- 1 file changed, 146 insertions(+), 157 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 3fade30c2562d3..e83b32aaf416f1 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -155,137 +155,9 @@ Reference Module functions and constants ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. data:: apilevel - - String constant stating the supported DB-API level. Required by the DB-API. - Hard-coded to ``"2.0"``. - -.. data:: paramstyle - - String constant stating the type of parameter marker formatting expected by - the :mod:`sqlite3` module. Required by the DB-API. Hard-coded to - ``"qmark"``. - - .. note:: - - The :mod:`sqlite3` module supports both ``qmark`` and ``numeric`` DB-API - parameter styles, because that is what the underlying SQLite library - supports. However, the DB-API does not allow multiple values for - the ``paramstyle`` attribute. - -.. data:: version - - Version number of this module as a :class:`string `. - This is not the version of the SQLite library. - - .. deprecated-removed:: 3.12 3.14 - This constant used to reflect the version number of the ``pysqlite`` - package, a third-party library which used to upstream changes to - ``sqlite3``. Today, it carries no meaning or practical value. - - -.. data:: version_info - - Version number of this module as a :class:`tuple` of :class:`integers `. - This is not the version of the SQLite library. - - .. deprecated-removed:: 3.12 3.14 - This constant used to reflect the version number of the ``pysqlite`` - package, a third-party library which used to upstream changes to - ``sqlite3``. Today, it carries no meaning or practical value. - - -.. data:: sqlite_version - - Version number of the runtime SQLite library as a :class:`string `. - - -.. data:: sqlite_version_info - - Version number of the runtime SQLite library as a :class:`tuple` of - :class:`integers `. - - -.. data:: threadsafety - - Integer constant required by the DB-API 2.0, stating the level of thread - safety the :mod:`sqlite3` module supports. This attribute is set based on - the default `threading mode `_ the - underlying SQLite library is compiled with. The SQLite threading modes are: - - 1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is - unsafe to use in more than a single thread at once. - 2. **Multi-thread**: In this mode, SQLite can be safely used by multiple - threads provided that no single database connection is used - simultaneously in two or more threads. - 3. **Serialized**: In serialized mode, SQLite can be safely used by - multiple threads with no restriction. - - The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels - are as follows: - - +------------------+-----------------+----------------------+-------------------------------+ - | SQLite threading | `threadsafety`_ | `SQLITE_THREADSAFE`_ | DB-API 2.0 meaning | - | mode | | | | - +==================+=================+======================+===============================+ - | single-thread | 0 | 0 | Threads may not share the | - | | | | module | - +------------------+-----------------+----------------------+-------------------------------+ - | multi-thread | 1 | 2 | Threads may share the module, | - | | | | but not connections | - +------------------+-----------------+----------------------+-------------------------------+ - | serialized | 3 | 1 | Threads may share the module, | - | | | | connections and cursors | - +------------------+-----------------+----------------------+-------------------------------+ - - .. _threadsafety: https://peps.python.org/pep-0249/#threadsafety - .. _SQLITE_THREADSAFE: https://sqlite.org/compile.html#threadsafe - - .. versionchanged:: 3.11 - Set *threadsafety* dynamically instead of hard-coding it to ``1``. - -.. data:: PARSE_DECLTYPES - - Pass this flag value to the *detect_types* parameter of - :func:`connect` to look up a converter function using - the declared types for each column. - The types are declared when the database table is created. - ``sqlite3`` will look up a converter function using the first word of the - declared type as the converter dictionary key. - For example: - - - .. code-block:: sql - - CREATE TABLE test( - i integer primary key, ! will look up a converter named "integer" - p point, ! will look up a converter named "point" - n number(10) ! will look up a converter named "number" - ) - - This flag may be combined with :const:`PARSE_COLNAMES` using the ``|`` - (bitwise or) operator. - - -.. data:: PARSE_COLNAMES - - Pass this flag value to the *detect_types* parameter of - :func:`connect` to look up a converter function by - using the type name, parsed from the query column name, - as the converter dictionary key. - The type name must be wrapped in square brackets (``[]``). - - .. code-block:: sql - - SELECT p as "p [point]" FROM test; ! will look up converter "point" - - This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|`` - (bitwise or) operator. - - - -.. function:: connect(database, timeout=5.0, detect_types=0, isolation_level="DEFERRED", check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False) +.. function:: connect(database, timeout=5.0, detect_types=0, + isolation_level="DEFERRED", check_same_thread=True, + factory=sqlite3.Connection, cached_statements=128, uri=False) Open a connection to an SQLite database. @@ -368,30 +240,6 @@ Module functions and constants .. versionadded:: 3.10 The ``sqlite3.connect/handle`` auditing event. - -.. function:: register_converter(typename, converter, /) - - Register the *converter* callable to convert SQLite objects of type - *typename* into a Python object of a specific type. - The converter is invoked for all SQLite values of type *typename*; - it is passed a :class:`bytes` object and should return an object of the - desired Python type. - Consult the parameter *detect_types* of - :func:`connect` for information regarding how type detection works. - - Note: *typename* and the name of the type in your query are matched - case-insensitively. - - -.. function:: register_adapter(type, adapter, /) - - Register an *adapter* callable to adapt the Python type *type* into an - SQLite type. - The adapter is called with a Python object of type *type* as its sole - argument, and must return a value of a - :ref:`type that SQLite natively understands`. - - .. function:: complete_statement(statement) Returns ``True`` if the string *statement* contains one or more complete SQL @@ -401,10 +249,8 @@ Module functions and constants This can be used to build a shell for SQLite, as in the following example: - .. literalinclude:: ../includes/sqlite3/complete_statement.py - .. function:: enable_callback_tracebacks(flag, /) Enable or disable callback tracebacks. @@ -432,6 +278,149 @@ Module functions and constants UnraisableHookArgs(exc_type=, exc_value=ZeroDivisionError('division by zero'), exc_traceback=, err_msg=None, object= at 0x10b4e3ee0>) +.. function:: register_adapter(type, adapter, /) + + Register an *adapter* callable to adapt the Python type *type* into an + SQLite type. + The adapter is called with a Python object of type *type* as its sole + argument, and must return a value of a + :ref:`type that SQLite natively understands`. + +.. function:: register_converter(typename, converter, /) + + Register the *converter* callable to convert SQLite objects of type + *typename* into a Python object of a specific type. + The converter is invoked for all SQLite values of type *typename*; + it is passed a :class:`bytes` object and should return an object of the + desired Python type. + Consult the parameter *detect_types* of + :func:`connect` for information regarding how type detection works. + + Note: *typename* and the name of the type in your query are matched + case-insensitively. + +.. data:: PARSE_COLNAMES + + Pass this flag value to the *detect_types* parameter of + :func:`connect` to look up a converter function by + using the type name, parsed from the query column name, + as the converter dictionary key. + The type name must be wrapped in square brackets (``[]``). + + .. code-block:: sql + + SELECT p as "p [point]" FROM test; ! will look up converter "point" + + This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|`` + (bitwise or) operator. + +.. data:: PARSE_DECLTYPES + + Pass this flag value to the *detect_types* parameter of + :func:`connect` to look up a converter function using + the declared types for each column. + The types are declared when the database table is created. + ``sqlite3`` will look up a converter function using the first word of the + declared type as the converter dictionary key. + For example: + + + .. code-block:: sql + + CREATE TABLE test( + i integer primary key, ! will look up a converter named "integer" + p point, ! will look up a converter named "point" + n number(10) ! will look up a converter named "number" + ) + + This flag may be combined with :const:`PARSE_COLNAMES` using the ``|`` + (bitwise or) operator. + +.. data:: apilevel + + String constant stating the supported DB-API level. Required by the DB-API. + Hard-coded to ``"2.0"``. + +.. data:: paramstyle + + String constant stating the type of parameter marker formatting expected by + the :mod:`sqlite3` module. Required by the DB-API. Hard-coded to + ``"qmark"``. + + .. note:: + + The :mod:`sqlite3` module supports both ``qmark`` and ``numeric`` DB-API + parameter styles, because that is what the underlying SQLite library + supports. However, the DB-API does not allow multiple values for + the ``paramstyle`` attribute. + +.. data:: sqlite_version + + Version number of the runtime SQLite library as a :class:`string `. + +.. data:: sqlite_version_info + + Version number of the runtime SQLite library as a :class:`tuple` of + :class:`integers `. + +.. data:: threadsafety + + Integer constant required by the DB-API 2.0, stating the level of thread + safety the :mod:`sqlite3` module supports. This attribute is set based on + the default `threading mode `_ the + underlying SQLite library is compiled with. The SQLite threading modes are: + + 1. **Single-thread**: In this mode, all mutexes are disabled and SQLite is + unsafe to use in more than a single thread at once. + 2. **Multi-thread**: In this mode, SQLite can be safely used by multiple + threads provided that no single database connection is used + simultaneously in two or more threads. + 3. **Serialized**: In serialized mode, SQLite can be safely used by + multiple threads with no restriction. + + The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels + are as follows: + + +------------------+-----------------+----------------------+-------------------------------+ + | SQLite threading | `threadsafety`_ | `SQLITE_THREADSAFE`_ | DB-API 2.0 meaning | + | mode | | | | + +==================+=================+======================+===============================+ + | single-thread | 0 | 0 | Threads may not share the | + | | | | module | + +------------------+-----------------+----------------------+-------------------------------+ + | multi-thread | 1 | 2 | Threads may share the module, | + | | | | but not connections | + +------------------+-----------------+----------------------+-------------------------------+ + | serialized | 3 | 1 | Threads may share the module, | + | | | | connections and cursors | + +------------------+-----------------+----------------------+-------------------------------+ + + .. _threadsafety: https://peps.python.org/pep-0249/#threadsafety + .. _SQLITE_THREADSAFE: https://sqlite.org/compile.html#threadsafe + + .. versionchanged:: 3.11 + Set *threadsafety* dynamically instead of hard-coding it to ``1``. + +.. data:: version + + Version number of this module as a :class:`string `. + This is not the version of the SQLite library. + + .. deprecated-removed:: 3.12 3.14 + This constant used to reflect the version number of the ``pysqlite`` + package, a third-party library which used to upstream changes to + ``sqlite3``. Today, it carries no meaning or practical value. + +.. data:: version_info + + Version number of this module as a :class:`tuple` of :class:`integers `. + This is not the version of the SQLite library. + + .. deprecated-removed:: 3.12 3.14 + This constant used to reflect the version number of the ``pysqlite`` + package, a third-party library which used to upstream changes to + ``sqlite3``. Today, it carries no meaning or practical value. + .. _sqlite3-connection-objects: From a3bb1bb3be68d839768b95933e92903f14127f27 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 Aug 2022 21:05:15 +0200 Subject: [PATCH 2/9] Address review: fix formatting --- Doc/library/sqlite3.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index e83b32aaf416f1..579d83fca3eb3c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -155,9 +155,10 @@ Reference Module functions and constants ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. function:: connect(database, timeout=5.0, detect_types=0, - isolation_level="DEFERRED", check_same_thread=True, - factory=sqlite3.Connection, cached_statements=128, uri=False) +.. function:: connect(database, timeout=5.0, detect_types=0, \ + isolation_level="DEFERRED", check_same_thread=True, \ + factory=sqlite3.Connection, cached_statements=128, \ + uri=False) Open a connection to an SQLite database. From c4036fdf35f60b6976b84ace7e184f064b5fccb2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 Aug 2022 21:09:11 +0200 Subject: [PATCH 3/9] Address review: split module level stuff into two subsubsections --- Doc/library/sqlite3.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 579d83fca3eb3c..f3d7ab410bd7d4 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -150,10 +150,13 @@ both styles: Reference --------- +.. We keep the old sqlite3-module-contents ref to prevent breaking links. .. _sqlite3-module-contents: -Module functions and constants -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _sqlite3-module-functions: + +Module functions +^^^^^^^^^^^^^^^^ .. function:: connect(database, timeout=5.0, detect_types=0, \ isolation_level="DEFERRED", check_same_thread=True, \ @@ -300,6 +303,11 @@ Module functions and constants Note: *typename* and the name of the type in your query are matched case-insensitively. +.. _sqlite3-module-variables: + +Module variables +^^^^^^^^^^^^^^^^ + .. data:: PARSE_COLNAMES Pass this flag value to the *detect_types* parameter of From 7a25c11115d5c6914047bfcd48f769809a0cdc12 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Thu, 4 Aug 2022 22:16:00 +0200 Subject: [PATCH 4/9] Update Doc/library/sqlite3.rst Co-authored-by: Ezio Melotti --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f3d7ab410bd7d4..494c62b2a827c6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -288,7 +288,7 @@ Module functions SQLite type. The adapter is called with a Python object of type *type* as its sole argument, and must return a value of a - :ref:`type that SQLite natively understands`. + :ref:`type that SQLite natively understands `. .. function:: register_converter(typename, converter, /) From 3f8f0a68325ceb4f7c2bb2ba83d1952f9602d728 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 5 Aug 2022 08:22:10 +0200 Subject: [PATCH 5/9] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 494c62b2a827c6..fb8ad46b014781 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -333,7 +333,6 @@ Module variables declared type as the converter dictionary key. For example: - .. code-block:: sql CREATE TABLE test( From dba48f4c0ff0e4849300a53476816035829aa4b7 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 5 Aug 2022 08:22:38 +0200 Subject: [PATCH 6/9] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index fb8ad46b014781..fbf94f6cbb93bc 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -303,6 +303,7 @@ Module functions Note: *typename* and the name of the type in your query are matched case-insensitively. + .. _sqlite3-module-variables: Module variables From 3c3bc79c63622c789bb0dfb3e928cdaff2d3272c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 6 Aug 2022 21:16:03 +0200 Subject: [PATCH 7/9] Module variables => Module constants --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 16e371088ec4ad..a3bbdcb30b870c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -280,9 +280,9 @@ Module functions case-insensitively. -.. _sqlite3-module-variables: +.. _sqlite3-module-constants: -Module variables +Module constants ^^^^^^^^^^^^^^^^ .. data:: PARSE_COLNAMES From 8f1f1029217a9d8310deac1a73f2aabefc3ede48 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 6 Aug 2022 21:18:29 +0200 Subject: [PATCH 8/9] Fixup merge --- Doc/library/sqlite3.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index a3bbdcb30b870c..eaaaf477ae5a0c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1,4 +1,4 @@ -:mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases +:mod:`!sqlite3` --- DB-API 2.0 interface for SQLite databases ============================================================ .. module:: sqlite3 @@ -306,7 +306,7 @@ Module constants :func:`connect` to look up a converter function using the declared types for each column. The types are declared when the database table is created. - ``sqlite3`` will look up a converter function using the first word of the + :mod:`!sqlite3` will look up a converter function using the first word of the declared type as the converter dictionary key. For example: @@ -329,12 +329,12 @@ Module constants .. data:: paramstyle String constant stating the type of parameter marker formatting expected by - the :mod:`sqlite3` module. Required by the DB-API. Hard-coded to + the :mod:`!sqlite3` module. Required by the DB-API. Hard-coded to ``"qmark"``. .. note:: - The :mod:`sqlite3` module supports both ``qmark`` and ``numeric`` DB-API + The :mod:`!sqlite3` module supports both ``qmark`` and ``numeric`` DB-API parameter styles, because that is what the underlying SQLite library supports. However, the DB-API does not allow multiple values for the ``paramstyle`` attribute. @@ -351,7 +351,7 @@ Module constants .. data:: threadsafety Integer constant required by the DB-API 2.0, stating the level of thread - safety the :mod:`sqlite3` module supports. This attribute is set based on + safety the :mod:`!sqlite3` module supports. This attribute is set based on the default `threading mode `_ the underlying SQLite library is compiled with. The SQLite threading modes are: @@ -394,7 +394,7 @@ Module constants .. deprecated-removed:: 3.12 3.14 This constant used to reflect the version number of the ``pysqlite`` package, a third-party library which used to upstream changes to - ``sqlite3``. Today, it carries no meaning or practical value. + :mod:`!sqlite3`. Today, it carries no meaning or practical value. .. data:: version_info @@ -404,7 +404,7 @@ Module constants .. deprecated-removed:: 3.12 3.14 This constant used to reflect the version number of the ``pysqlite`` package, a third-party library which used to upstream changes to - ``sqlite3``. Today, it carries no meaning or practical value. + :mod:`!sqlite3`. Today, it carries no meaning or practical value. .. _sqlite3-connection-objects: From b5f6805fc48581422c857726011c0ce290144114 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 6 Aug 2022 21:20:51 +0200 Subject: [PATCH 9/9] Facepalm --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index eaaaf477ae5a0c..5efceb3cb7e860 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1,4 +1,4 @@ -:mod:`!sqlite3` --- DB-API 2.0 interface for SQLite databases +:mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases ============================================================ .. module:: sqlite3