Skip to content
Snippets Groups Projects
Unverified Commit 6c439b97 authored by Erlend Egeberg Aasland's avatar Erlend Egeberg Aasland Committed by GitHub
Browse files

gh-94635: Add Reference, How-to, and Concepts headings to sqlite3 docs (#94636)

parent 82814624
Branches
Tags
No related merge requests found
...@@ -25,6 +25,15 @@ The sqlite3 module was written by Gerhard Häring. It provides an SQL interface ...@@ -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 compliant with the DB-API 2.0 specification described by :pep:`249`, and
requires SQLite 3.7.15 or newer. 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: .. _sqlite3-tutorial:
...@@ -136,10 +145,15 @@ both styles: ...@@ -136,10 +145,15 @@ both styles:
PEP written by Marc-André Lemburg. PEP written by Marc-André Lemburg.
.. _sqlite3-reference:
Reference
---------
.. _sqlite3-module-contents: .. _sqlite3-module-contents:
Module functions and constants Module functions and constants
------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. data:: apilevel .. data:: apilevel
...@@ -421,8 +435,8 @@ Module functions and constants ...@@ -421,8 +435,8 @@ Module functions and constants
.. _sqlite3-connection-objects: .. _sqlite3-connection-objects:
Connection Objects Connection objects
------------------ ^^^^^^^^^^^^^^^^^^
.. class:: Connection .. class:: Connection
...@@ -982,8 +996,8 @@ Connection Objects ...@@ -982,8 +996,8 @@ Connection Objects
.. _sqlite3-cursor-objects: .. _sqlite3-cursor-objects:
Cursor Objects Cursor objects
-------------- ^^^^^^^^^^^^^^
A ``Cursor`` object represents a `database cursor`_ A ``Cursor`` object represents a `database cursor`_
which is used to execute SQL statements, which is used to execute SQL statements,
...@@ -1159,8 +1173,8 @@ Cursor Objects ...@@ -1159,8 +1173,8 @@ Cursor Objects
.. _sqlite3-row-objects: .. _sqlite3-row-objects:
Row Objects Row objects
----------- ^^^^^^^^^^^
.. class:: Row .. class:: Row
...@@ -1224,8 +1238,8 @@ Now we plug :class:`Row` in:: ...@@ -1224,8 +1238,8 @@ Now we plug :class:`Row` in::
.. _sqlite3-blob-objects: .. _sqlite3-blob-objects:
Blob Objects Blob objects
------------ ^^^^^^^^^^^^
.. versionadded:: 3.11 .. versionadded:: 3.11
...@@ -1276,8 +1290,8 @@ Blob Objects ...@@ -1276,8 +1290,8 @@ Blob Objects
end). end).
PrepareProtocol Objects PrepareProtocol objects
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
.. class:: PrepareProtocol .. class:: PrepareProtocol
...@@ -1289,7 +1303,7 @@ PrepareProtocol Objects ...@@ -1289,7 +1303,7 @@ PrepareProtocol Objects
.. _sqlite3-exceptions: .. _sqlite3-exceptions:
Exceptions Exceptions
---------- ^^^^^^^^^^
The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
...@@ -1379,11 +1393,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). ...@@ -1379,11 +1393,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
.. _sqlite3-types: .. _sqlite3-types:
SQLite and Python types SQLite and Python types
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
Introduction
^^^^^^^^^^^^
SQLite natively supports the following types: ``NULL``, ``INTEGER``, SQLite natively supports the following types: ``NULL``, ``INTEGER``,
``REAL``, ``TEXT``, ``BLOB``. ``REAL``, ``TEXT``, ``BLOB``.
...@@ -1423,10 +1433,18 @@ This is how SQLite types are converted to Python types by default: ...@@ -1423,10 +1433,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 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 store additional Python types in an SQLite database via
you can let the :mod:`sqlite3` module convert SQLite types to different Python :ref:`object adapters <sqlite3-adapters>`,
types via converters. 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 Using adapters to store custom Python types in SQLite databases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -1549,7 +1567,7 @@ The deprecated default adapters and converters consist of: ...@@ -1549,7 +1567,7 @@ The deprecated default adapters and converters consist of:
.. _sqlite3-adapter-converter-recipes: .. _sqlite3-adapter-converter-recipes:
Adapter and Converter Recipes Adapter and converter recipes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section shows recipes for common adapters and converters. This section shows recipes for common adapters and converters.
...@@ -1592,83 +1610,6 @@ This section shows recipes for common adapters and converters. ...@@ -1592,83 +1610,6 @@ This section shows recipes for common adapters and converters.
sqlite3.register_converter("timestamp", convert_timestamp) 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: .. _sqlite3-connection-shortcuts:
Using connection shortcut methods Using connection shortcut methods
...@@ -1686,6 +1627,8 @@ directly using only a single call on the :class:`Connection` object. ...@@ -1686,6 +1627,8 @@ directly using only a single call on the :class:`Connection` object.
.. literalinclude:: ../includes/sqlite3/shortcut_methods.py .. literalinclude:: ../includes/sqlite3/shortcut_methods.py
.. _sqlite3-columns-by-name:
Accessing columns by name instead of by index Accessing columns by name instead of by index
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -1721,3 +1664,82 @@ the context manager is a no-op. ...@@ -1721,3 +1664,82 @@ the context manager is a no-op.
nor closes the connection. nor closes the connection.
.. literalinclude:: ../includes/sqlite3/ctx_manager.py .. 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
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment