[3.11] gh-94635: Add Reference, How-to, and Explanation headings to sqlite3 docs (GH-94636) (#95482)

erlend-aasland · web-flow · commit c7ac8b65884a · 2022-07-31T08:48:13.000+02:00
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>. (cherry picked from commit 6c439b9) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com> * Fix refs
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -25,6 +25,15 @@ 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 functions this module
+  defines.
+* :ref:`sqlite3-howtos` details how to handle specific tasks.
+* :ref:`sqlite3-explanation` provides in-depth background on
+  transaction control.
+
 
 .. _sqlite3-tutorial:
 
@@ -136,10 +145,15 @@ both styles:
       PEP written by Marc-André Lemburg.
 
 
+.. _sqlite3-reference:
+
+Reference
+---------
+
 .. _sqlite3-module-contents:
 
 Module functions and constants
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 .. data:: apilevel
@@ -411,8 +425,8 @@ Module functions and constants
 
 .. _sqlite3-connection-objects:
 
-Connection Objects
-------------------
+Connection objects
+^^^^^^^^^^^^^^^^^^
 
 .. class:: Connection
 
@@ -972,8 +986,8 @@ Connection Objects
 
 .. _sqlite3-cursor-objects:
 
-Cursor Objects
---------------
+Cursor objects
+^^^^^^^^^^^^^^
 
    A ``Cursor`` object represents a `database cursor`_
    which is used to execute SQL statements,
@@ -1149,8 +1163,8 @@ Cursor Objects
 
 .. _sqlite3-row-objects:
 
-Row Objects
------------
+Row objects
+^^^^^^^^^^^
 
 .. class:: Row
 
@@ -1212,8 +1226,10 @@ Now we plug :class:`Row` in::
    35.14
 
 
-Blob Objects
-------------
+.. _sqlite3-blob-objects:
+
+Blob objects
+^^^^^^^^^^^^
 
 .. versionadded:: 3.11
 
@@ -1264,8 +1280,8 @@ Blob Objects
       end).
 
 
-PrepareProtocol Objects
------------------------
+PrepareProtocol objects
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. class:: PrepareProtocol
 
@@ -1277,7 +1293,7 @@ PrepareProtocol Objects
 .. _sqlite3-exceptions:
 
 Exceptions
-----------
+^^^^^^^^^^
 
 The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
 
@@ -1364,16 +1380,10 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
    ``NotSupportedError`` is a subclass of :exc:`DatabaseError`.
 
 
-.. _sqlite3-blob-objects:
-
 .. _sqlite3-types:
 
 SQLite and Python types
------------------------
-
-
-Introduction
-^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^
 
 SQLite natively supports the following types: ``NULL``, ``INTEGER``,
 ``REAL``, ``TEXT``, ``BLOB``.
@@ -1413,10 +1423,18 @@ This is how SQLite types are converted to Python types by default:
 +-------------+----------------------------------------------+
 
 The type system of the :mod:`sqlite3` module is extensible in two ways: you can
-store additional Python types in an SQLite database via object adaptation, and
-you can let the :mod:`sqlite3` module convert SQLite types to different Python
-types via converters.
+store additional Python types in an SQLite database via
+:ref:`object adapters <sqlite3-adapters>`,
+and you can let the ``sqlite3`` module convert SQLite types to
+Python types via :ref:`converters <sqlite3-converters>`.
+
 
+.. _sqlite3-howtos:
+
+How-to guides
+-------------
+
+.. _sqlite3-adapters:
 
 Using adapters to store custom Python types in SQLite databases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1460,6 +1478,8 @@ This function can then be registered using :func:`register_adapter`.
 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py
 
 
+.. _sqlite3-converters:
+
 Converting SQLite values to custom Python types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1532,7 +1552,7 @@ timestamp converter.
 
 .. _sqlite3-adapter-converter-recipes:
 
-Adapter and Converter Recipes
+Adapter and converter recipes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This section shows recipes for common adapters and converters.
@@ -1575,83 +1595,6 @@ This section shows recipes for common adapters and converters.
    sqlite3.register_converter("timestamp", convert_timestamp)
 
 
-.. _sqlite3-controlling-transactions:
-
-Controlling Transactions
-------------------------
-
-The ``sqlite3`` module does not adhere to the transaction handling recommended
-by :pep:`249`.
-
-If the connection attribute :attr:`~Connection.isolation_level`
-is not :const:`None`,
-new transactions are implicitly opened before
-:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes
-``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements.
-Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods
-to respectively commit and roll back pending transactions.
-You can choose the underlying `SQLite transaction behaviour`_ —
-that is, whether and what type of ``BEGIN`` statements ``sqlite3``
-implicitly executes –
-via the :attr:`~Connection.isolation_level` attribute.
-
-If :attr:`~Connection.isolation_level` is set to :const:`None`,
-no transactions are implicitly opened at all.
-This leaves the underlying SQLite library in `autocommit mode`_,
-but also allows the user to perform their own transaction handling
-using explicit SQL statements.
-The underlying SQLite library autocommit mode can be queried using the
-:attr:`~Connection.in_transaction` attribute.
-
-The :meth:`~Cursor.executescript` method implicitly commits
-any pending transaction before execution of the given SQL script,
-regardless of the value of :attr:`~Connection.isolation_level`.
-
-.. versionchanged:: 3.6
-   :mod:`sqlite3` used to implicitly commit an open transaction before DDL
-   statements.  This is no longer the case.
-
-.. _autocommit mode:
-   https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions
-
-.. _SQLite transaction behaviour:
-   https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
-
-
-.. _sqlite3-uri-tricks:
-
-SQLite URI tricks
------------------
-
-Some useful URI tricks include:
-
-* Open a database in read-only mode::
-
-    con = sqlite3.connect("file:template.db?mode=ro", uri=True)
-
-* 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::
-
-    con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
-
-* Create a shared named in-memory database::
-
-    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()
-
-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
-
-Using :mod:`sqlite3` efficiently
---------------------------------
-
-
 .. _sqlite3-connection-shortcuts:
 
 Using connection shortcut methods
@@ -1669,6 +1612,8 @@ directly using only a single call on the :class:`Connection` object.
 .. literalinclude:: ../includes/sqlite3/shortcut_methods.py
 
 
+.. _sqlite3-columns-by-name:
+
 Accessing columns by name instead of by index
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1704,3 +1649,82 @@ the context manager is a no-op.
    nor closes the connection.
 
 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
+
+
+.. _sqlite3-uri-tricks:
+
+Working with SQLite URIs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some useful URI tricks include:
+
+* Open a database in read-only mode::
+
+    con = sqlite3.connect("file:template.db?mode=ro", uri=True)
+
+* 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::
+
+    con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
+
+* Create a shared named in-memory database::
+
+    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()
+
+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
+
+
+.. _sqlite3-explanation:
+
+Explanation
+-----------
+
+.. _sqlite3-controlling-transactions:
+
+Transaction control
+^^^^^^^^^^^^^^^^^^^
+
+The ``sqlite3`` module does not adhere to the transaction handling recommended
+by :pep:`249`.
+
+If the connection attribute :attr:`~Connection.isolation_level`
+is not :const:`None`,
+new transactions are implicitly opened before
+:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes
+``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements.
+Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods
+to respectively commit and roll back pending transactions.
+You can choose the underlying `SQLite transaction behaviour`_ —
+that is, whether and what type of ``BEGIN`` statements ``sqlite3``
+implicitly executes –
+via the :attr:`~Connection.isolation_level` attribute.
+
+If :attr:`~Connection.isolation_level` is set to :const:`None`,
+no transactions are implicitly opened at all.
+This leaves the underlying SQLite library in `autocommit mode`_,
+but also allows the user to perform their own transaction handling
+using explicit SQL statements.
+The underlying SQLite library autocommit mode can be queried using the
+:attr:`~Connection.in_transaction` attribute.
+
+The :meth:`~Cursor.executescript` method implicitly commits
+any pending transaction before execution of the given SQL script,
+regardless of the value of :attr:`~Connection.isolation_level`.
+
+.. versionchanged:: 3.6
+   :mod:`sqlite3` used to implicitly commit an open transaction before DDL
+   statements.  This is no longer the case.
+
+.. _autocommit mode:
+   https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions
+
+.. _SQLite transaction behaviour:
+   https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
