From 8dc623169e4db60e5e92d816e9a16290ff5306bb Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 20 Aug 2022 03:24:16 -0500 Subject: [PATCH 1/3] sqlite3 doc: Move default adapters and converters to Reference section --- Doc/library/sqlite3.rst | 70 ++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6413d8859180da..ddadbdd3f6a6ed 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1526,6 +1526,41 @@ and you can let the :mod:`!sqlite3` module convert SQLite types to Python types via :ref:`converters `. +.. _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 ` in + `ISO 8601`_ format. +* An adapter for :class:`datetime.datetime` objects to strings in + ISO 8601 format. +* A converter for :ref:`declared ` "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-cli: Command-line interface @@ -1669,41 +1704,6 @@ 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 ` in - `ISO 8601`_ format. -* An adapter for :class:`datetime.datetime` objects to strings in - ISO 8601 format. -* A converter for :ref:`declared ` "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 From 5eb1abca3eb7c210dc7e1d7e0523234417b71834 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 20 Aug 2022 03:33:13 -0500 Subject: [PATCH 2/3] Reframe How-To section headers in terms of how-to per Diataxis Co-authored-by: Erlend E. Aasland --- Doc/library/sqlite3.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index ddadbdd3f6a6ed..5ceba8af36dfb9 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1620,8 +1620,8 @@ both styles: .. _sqlite3-adapters: -Using adapters to store custom Python types in SQLite databases -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How to adapt custom Python types to SQLite values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLite supports only a limited set of data types natively. To store custom Python types in SQLite databases, *adapt* them to one of the @@ -1638,8 +1638,8 @@ registering custom adapter functions. .. _sqlite3-conform: -Letting your object adapt itself -"""""""""""""""""""""""""""""""" +Let your object adapt itself +"""""""""""""""""""""""""""" Suppose we have a :class:`!Point` class that represents a pair of coordinates, ``x`` and ``y``, in a Cartesian coordinate system. @@ -1652,8 +1652,8 @@ The object passed to *protocol* will be of type :class:`PrepareProtocol`. .. literalinclude:: ../includes/sqlite3/adapter_point_1.py -Registering an adapter callable -""""""""""""""""""""""""""""""" +Register an adapter callable +"""""""""""""""""""""""""""" The other possibility is to create a function that converts the Python object to an SQLite-compatible type. @@ -1664,8 +1664,8 @@ This function can then be registered using :func:`register_adapter`. .. _sqlite3-converters: -Converting SQLite values to custom Python types -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How to convert SQLite values to custom Python types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Writing an adapter lets you convert *from* custom Python types *to* SQLite values. @@ -1751,8 +1751,8 @@ This section shows recipes for common adapters and converters. .. _sqlite3-connection-shortcuts: -Using connection shortcut methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How to use connection shortcut methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using the :meth:`~Connection.execute`, :meth:`~Connection.executemany`, and :meth:`~Connection.executescript` @@ -1768,8 +1768,8 @@ directly using only a single call on the :class:`Connection` object. .. _sqlite3-columns-by-name: -Accessing columns by name instead of by index -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Hwo to access columns by name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One useful feature of the :mod:`!sqlite3` module is the built-in :class:`sqlite3.Row` class designed to be used as a row factory. @@ -1782,8 +1782,8 @@ case-insensitively by name: .. _sqlite3-connection-context-manager: -Using the connection as a context manager -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How to use a 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 @@ -1807,8 +1807,8 @@ the context manager is a no-op. .. _sqlite3-uri-tricks: -Working with SQLite URIs -^^^^^^^^^^^^^^^^^^^^^^^^ +How to work with SQLite URIs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some useful URI tricks include: From bcd79138df4a4d8d9ab116f50bc46af5e9e451a9 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 23 Aug 2022 12:03:28 -0500 Subject: [PATCH 3/3] Apply reviewer feedback on sqlite3 doc heading wording Co-authored-by: Ezio Melotti --- Doc/library/sqlite3.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 87f62c0adeb4d7..eba913a81bba73 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1614,8 +1614,8 @@ registering custom adapter functions. .. _sqlite3-conform: -Let your object adapt itself -"""""""""""""""""""""""""""" +How to write adaptable objects +"""""""""""""""""""""""""""""" Suppose we have a :class:`!Point` class that represents a pair of coordinates, ``x`` and ``y``, in a Cartesian coordinate system. @@ -1628,8 +1628,8 @@ The object passed to *protocol* will be of type :class:`PrepareProtocol`. .. literalinclude:: ../includes/sqlite3/adapter_point_1.py -Register an adapter callable -"""""""""""""""""""""""""""" +How to register adapter callables +""""""""""""""""""""""""""""""""" The other possibility is to create a function that converts the Python object to an SQLite-compatible type. @@ -1744,8 +1744,8 @@ directly using only a single call on the :class:`Connection` object. .. _sqlite3-connection-context-manager: -How to use a connection as a context manager -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How to use the connection 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