[Python-checkins] [3.11] gh-94635: Add Reference, How-to, and Explanation headings to sqlite3 docs (GH-94636) (#95482)
erlend-aasland
webhook-mailer at python.org
Sun Jul 31 02:48:29 EDT 2022
https://github.com/python/cpython/commit/c7ac8b65884a79e6a976811bca10527613b1396a
commit: c7ac8b65884a79e6a976811bca10527613b1396a
branch: 3.11
author: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2022-07-31T08:48:13+02:00
summary:
[3.11] gh-94635: Add Reference, How-to, and Explanation headings to sqlite3 docs (GH-94636) (#95482)
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>.
(cherry picked from commit 6c439b978bf55b29f21c595e9375202d63c8208d)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>
* Fix refs
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 9437bafa5a281..332e3b0b79a1e 100644
--- 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
More information about the Python-checkins
mailing list