Address reviews

python · erlend-aasland · Jul 30, 2022 · Jul 1, 2022 · Jul 27, 2022 · Jul 27, 2022
commit 3ed9049668f998df53c3d647db4043fdca270ade
@@ -25,6 +25,14 @@ The sqlite3 module was written by Gerhard Häring.  It provides an SQL interface
 compliant with the DB-API 2.0 specification described by :pep:`249`, and
 requires SQLite 3.7.15 or newer.
 
+This document includes four main sections:
+* :ref:`sqlite3-tutorial`: teaches how to use the sqlite3 module
+* :ref:`sqlite3-reference`: describes the classes and methods defined in the
+  module
+* :ref:`sqlite3-howtos`: explains how to solve specific problems
+* :ref:`sqlites-concepts`: provides more background and insights about the
+  design of the module
+
 
 .. _sqlite3-tutorial:
 
@@ -131,7 +139,7 @@ Reference
 .. _sqlite3-module-contents:
 
 Module functions and constants
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 .. data:: apilevel
@@ -411,8 +419,8 @@ Module functions and constants
 
 .. _sqlite3-connection-objects:
 
-Connection Objects
-~~~~~~~~~~~~~~~~~~
+Connection objects
+^^^^^^^^^^^^^^^^^^
 
 .. class:: Connection
 
@@ -958,8 +966,8 @@ Connection Objects
 
 .. _sqlite3-cursor-objects:
 
-Cursor Objects
-~~~~~~~~~~~~~~
+Cursor objects
+^^^^^^^^^^^^^^
 
 .. class:: Cursor
 
@@ -1109,8 +1117,8 @@ Cursor Objects
 
 .. _sqlite3-row-objects:
 
-Row Objects
-~~~~~~~~~~~
+Row objects
+^^^^^^^^^^^
 
 .. class:: Row
 
@@ -1175,8 +1183,8 @@ Now we plug :class:`Row` in::
 
 .. _sqlite3-blob-objects:
 
-Blob Objects
-~~~~~~~~~~~~
+Blob objects
+^^^^^^^^^^^^
 
 .. versionadded:: 3.11
 
@@ -1227,8 +1235,8 @@ Blob Objects
       end).
 
 
-PrepareProtocol Objects
------------------------
+PrepareProtocol objects
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. class:: PrepareProtocol
 
@@ -1240,7 +1248,7 @@ PrepareProtocol Objects
 .. _sqlite3-exceptions:
 
 Exceptions
-~~~~~~~~~~
+^^^^^^^^^^
 
 The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
 
@@ -1327,15 +1335,64 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
    ``NotSupportedError`` is a subclass of :exc:`DatabaseError`.
 
 
-.. _sqlite3-guides:
+.. _sqlite3-types:
+
+SQLite and Python types
+^^^^^^^^^^^^^^^^^^^^^^^
+
+SQLite natively supports the following types: ``NULL``, ``INTEGER``,
+``REAL``, ``TEXT``, ``BLOB``.
+
+The following Python types can thus be sent to SQLite without any problem:
+
++-------------------------------+-------------+
+| Python type                   | SQLite type |
++===============================+=============+
+| :const:`None`                 | ``NULL``    |
++-------------------------------+-------------+
+| :class:`int`                  | ``INTEGER`` |
++-------------------------------+-------------+
+| :class:`float`                | ``REAL``    |
++-------------------------------+-------------+
+| :class:`str`                  | ``TEXT``    |
++-------------------------------+-------------+
+| :class:`bytes`                | ``BLOB``    |
++-------------------------------+-------------+
+
+
+This is how SQLite types are converted to Python types by default:
+
++-------------+----------------------------------------------+
+| SQLite type | Python type                                  |
++=============+==============================================+
+| ``NULL``    | :const:`None`                                |
++-------------+----------------------------------------------+
+| ``INTEGER`` | :class:`int`                                 |
++-------------+----------------------------------------------+
+| ``REAL``    | :class:`float`                               |
++-------------+----------------------------------------------+
+| ``TEXT``    | depends on :attr:`~Connection.text_factory`, |
+|             | :class:`str` by default                      |
++-------------+----------------------------------------------+
+| ``BLOB``    | :class:`bytes`                               |
++-------------+----------------------------------------------+
+
+The type system of the :mod:`sqlite3` module is extensible in two ways: you can
+store additional Python types in an SQLite database via
+:ref:`object adapters <sqlite3-adapters>`,
+and you can let the :mod:`sqlite3` module convert SQLite types to
+Python types via :ref:`converters <sqlite3-converters>`.
+
+
+.. _sqlite3-howtos:
 
 Guides
 ------
 
 .. _sqlite3-adapters:
 
 Using adapters to store custom Python types in SQLite databases
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 SQLite supports only a limited set of data types natively.
 To store custom Python types in SQLite databases, *adapt* them to one of the
@@ -1379,7 +1436,7 @@ This function can then be registered using :func:`register_adapter`.
 .. _sqlite3-converters:
 
 Converting SQLite values to custom Python types
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Writing an adapter lets you convert *from* custom Python types *to* SQLite
 values.
@@ -1418,10 +1475,45 @@ The following example illustrates the implicit and explicit approaches:
 .. literalinclude:: ../includes/sqlite3/converter_point.py
 
 
+.. _sqlite3-default-converters:
+
+Default adapters and converters (deprecated)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   The default adapters and converters are deprecated as of Python 3.12.
+   Instead, use the :ref:`sqlite3-adapter-converter-recipes`
+   and tailor them to your needs.
+
+The deprecated default adapters and converters consist of:
+
+* An adapter for :class:`datetime.date` objects to :class:`strings <str>` in
+  `ISO 8601`_ format.
+* An adapter for :class:`datetime.datetime` objects to strings in
+  ISO 8601 format.
+* A converter for :ref:`declared <sqlite3-converters>` "date" types to
+  :class:`datetime.date` objects.
+* A converter for declared "timestamp" types to
+  :class:`datetime.datetime` objects.
+  Fractional parts will be truncated to 6 digits (microsecond precision).
+
+.. note::
+
+   The default "timestamp" converter ignores UTC offsets in the database and
+   always returns a naive :class:`datetime.datetime` object. To preserve UTC
+   offsets in timestamps, either leave converters disabled, or register an
+   offset-aware converter with :func:`register_converter`.
+
+.. deprecated:: 3.12
+
+.. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601
+
+
 .. _sqlite3-adapter-converter-recipes:
 
-Adapter and Converter Recipes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Adapter and converter recipes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This section shows recipes for common adapters and converters.
 
@@ -1463,42 +1555,10 @@ This section shows recipes for common adapters and converters.
    sqlite3.register_converter("timestamp", convert_timestamp)
 
 
-.. _sqlite3-default-adapters:
-
-Default adapters and converters
-"""""""""""""""""""""""""""""""
-
-There are default adapters for the date and datetime types in the datetime
-module. They will be sent as ISO dates/ISO timestamps to SQLite.
-
-The default converters are registered under the name "date" for
-:class:`datetime.date` and under the name "timestamp" for
-:class:`datetime.datetime`.
-
-This way, you can use date/timestamps from Python without any additional
-fiddling in most cases. The format of the adapters is also compatible with the
-experimental SQLite date/time functions.
-
-The following example demonstrates this.
-
-.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
-
-If a timestamp stored in SQLite has a fractional part longer than 6
-numbers, its value will be truncated to microsecond precision by the
-timestamp converter.
-
-.. note::
-
-   The default "timestamp" converter ignores UTC offsets in the database and
-   always returns a naive :class:`datetime.datetime` object. To preserve UTC
-   offsets in timestamps, either leave converters disabled, or register an
-   offset-aware converter with :func:`register_converter`.
-
-
 .. _sqlite3-shortcut-methods:
 
 Using shortcut methods
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 Using the nonstandard :meth:`execute`, :meth:`executemany` and
 :meth:`executescript` methods of the :class:`Connection` object, your code can
@@ -1514,7 +1574,7 @@ directly using only a single call on the :class:`Connection` object.
 .. _sqlite3-columns-by-name:
 
 Accessing columns by name instead of by index
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One useful feature of the :mod:`sqlite3` module is the built-in
 :class:`sqlite3.Row` class designed to be used as a row factory.
@@ -1528,7 +1588,7 @@ case-insensitively by name:
 .. _sqlite3-connection-context-manager:
 
 Using the connection as a context manager
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A :class:`Connection` object can be used as a context manager that
 automatically commits or rolls back open transactions when leaving the body of
@@ -1550,64 +1610,46 @@ the context manager is a no-op.
 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
 
 
-.. _sqlite3-concepts:
+.. _sqlite3-uri-tricks:
 
-Concepts
---------
+SQLite URI tricks
+^^^^^^^^^^^^^^^^^
 
-.. _sqlite3-types:
+Some useful URI tricks include:
 
-SQLite and Python types
-~~~~~~~~~~~~~~~~~~~~~~~
+* Open a database in read-only mode::
 
-SQLite natively supports the following types: ``NULL``, ``INTEGER``,
-``REAL``, ``TEXT``, ``BLOB``.
+    con = sqlite3.connect("file:template.db?mode=ro", uri=True)
 
-The following Python types can thus be sent to SQLite without any problem:
+* Do not implicitly create a new database file if it does not already exist;
+  will raise :exc:`~sqlite3.OperationalError` if unable to create a new file::
 
-+-------------------------------+-------------+
-| Python type                   | SQLite type |
-+===============================+=============+
-| :const:`None`                 | ``NULL``    |
-+-------------------------------+-------------+
-| :class:`int`                  | ``INTEGER`` |
-+-------------------------------+-------------+
-| :class:`float`                | ``REAL``    |
-+-------------------------------+-------------+
-| :class:`str`                  | ``TEXT``    |
-+-------------------------------+-------------+
-| :class:`bytes`                | ``BLOB``    |
-+-------------------------------+-------------+
+    con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
 
+* Create a shared named in-memory database::
 
-This is how SQLite types are converted to Python types by default:
+    con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
+    con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
+    con1.execute("create table t(t)")
+    con1.execute("insert into t values(28)")
+    con1.commit()
+    rows = con2.execute("select * from t").fetchall()
 
-+-------------+----------------------------------------------+
-| SQLite type | Python type                                  |
-+=============+==============================================+
-| ``NULL``    | :const:`None`                                |
-+-------------+----------------------------------------------+
-| ``INTEGER`` | :class:`int`                                 |
-+-------------+----------------------------------------------+
-| ``REAL``    | :class:`float`                               |
-+-------------+----------------------------------------------+
-| ``TEXT``    | depends on :attr:`~Connection.text_factory`, |
-|             | :class:`str` by default                      |
-+-------------+----------------------------------------------+
-| ``BLOB``    | :class:`bytes`                               |
-+-------------+----------------------------------------------+
+More information about this feature, including a list of parameters,
+can be found in the `SQLite URI documentation`_.
+
+.. _SQLite URI documentation: https://www.sqlite.org/uri.html
 
-The type system of the :mod:`sqlite3` module is extensible in two ways: you can
-store additional Python types in an SQLite database via
-:ref:`object adapters <sqlite3-adapters>`,
-and you can let the :mod:`sqlite3` module convert SQLite types to
-Python types via :ref:`converters <sqlite3-converters>`.
 
+.. _sqlite3-concepts:
+
+Concepts
+--------
 
 .. _sqlite3-controlling-transactions:
 
-Controlling Transactions
-~~~~~~~~~~~~~~~~~~~~~~~~
+Transaction control
+^^^^^^^^^^^^^^^^^^^
 
 The ``sqlite3`` module does not adhere to the transaction handling recommended
 by :pep:`249`.