From 896053bcbca25578d415a72fd38df73be2e1e688 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 7 Jul 2022 23:16:12 +0200 Subject: [PATCH 1/2] gh-94635: Normalise sqlite3 doc headings --- Doc/library/sqlite3.rst | 45 +++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 2f4e2aeef93994..92fbd720dfc226 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -115,7 +115,7 @@ both styles: .. _sqlite3-module-contents: -Module functions and constants +Module Functions and Constants ------------------------------ @@ -1241,7 +1241,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). .. _sqlite3-types: -SQLite and Python types +SQLite and Python Types ----------------------- @@ -1291,8 +1291,8 @@ you can let the :mod:`sqlite3` module convert SQLite types to different Python types via converters. -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 @@ -1309,8 +1309,8 @@ registering custom adapter functions. .. _sqlite3-conform: -Letting your object adapt itself -"""""""""""""""""""""""""""""""" +Let your object adapt itself +"""""""""""""""""""""""""""" Suppose we have a ``Point`` class that represents a pair of coordinates, ``x`` and ``y``, in a Cartesian coordinate system. @@ -1323,8 +1323,8 @@ The object passed to *protocol* will be of type :class:`PrepareProtocol`. .. literalinclude:: ../includes/sqlite3/adapter_point_1.py -Registering an adapter callable -""""""""""""""""""""""""""""""" +Use an adapter callable +""""""""""""""""""""""" The other possibility is to create a function that converts the Python object to an SQLite-compatible type. @@ -1333,8 +1333,8 @@ This function can then be registered using :func:`register_adapter`. .. literalinclude:: ../includes/sqlite3/adapter_point_2.py -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. @@ -1373,7 +1373,7 @@ The following example illustrates the implicit and explicit approaches: .. literalinclude:: ../includes/sqlite3/converter_point.py -Default adapters and converters +Default Adapters and Converters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are default adapters for the date and datetime types in the datetime @@ -1450,8 +1450,8 @@ This section shows recipes for common adapters and converters. .. _sqlite3-controlling-transactions: -Controlling Transactions ------------------------- +Transaction Control +------------------- The ``sqlite3`` module does not adhere to the transaction handling recommended by :pep:`249`. @@ -1493,7 +1493,7 @@ regardless of the value of :attr:`~Connection.isolation_level`. .. _sqlite3-uri-tricks: -SQLite URI tricks +SQLite URI Tricks ----------------- Some useful URI tricks include: @@ -1521,12 +1521,13 @@ can be found in the `SQLite URI documentation`_. .. _SQLite URI documentation: https://www.sqlite.org/uri.html -Using :mod:`sqlite3` efficiently --------------------------------- +How to Use ``sqlite3`` Efficiently +---------------------------------- -Using shortcut methods -^^^^^^^^^^^^^^^^^^^^^^ + +How to Use Shortcut Methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using the nonstandard :meth:`execute`, :meth:`executemany` and :meth:`executescript` methods of the :class:`Connection` object, your code can @@ -1539,8 +1540,8 @@ directly using only a single call on the :class:`Connection` object. .. literalinclude:: ../includes/sqlite3/shortcut_methods.py -Accessing columns by name instead of by index -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How 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. @@ -1553,8 +1554,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 From 26dc7507ad68ac5d9ed01d36d8bd7b7637e8a109 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 21 Jul 2022 00:11:22 +0200 Subject: [PATCH 2/2] Address review: use sentence case, as per the devguide --- Doc/library/sqlite3.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 128c540e812f91..33ed6429e67624 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -115,7 +115,7 @@ both styles: .. _sqlite3-module-contents: -Module Functions and Constants +Module functions and constants ------------------------------ @@ -396,7 +396,7 @@ Module Functions and Constants .. _sqlite3-connection-objects: -Connection Objects +Connection objects ------------------ .. class:: Connection @@ -865,7 +865,7 @@ Connection Objects .. _sqlite3-cursor-objects: -Cursor Objects +Cursor objects -------------- .. class:: Cursor @@ -1021,7 +1021,7 @@ Cursor Objects .. _sqlite3-row-objects: -Row Objects +Row objects ----------- .. class:: Row @@ -1087,7 +1087,7 @@ Now we plug :class:`Row` in:: .. _sqlite3-blob-objects: -Blob Objects +Blob objects ------------ .. versionadded:: 3.11 @@ -1139,7 +1139,7 @@ Blob Objects end). -PrepareProtocol Objects +PrepareProtocol objects ----------------------- .. class:: PrepareProtocol @@ -1241,7 +1241,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). .. _sqlite3-types: -SQLite and Python Types +SQLite and Python types ----------------------- @@ -1291,7 +1291,7 @@ you can let the :mod:`sqlite3` module convert SQLite types to different Python types via converters. -How to Adapt Custom Python Types to SQLite Values +How to adapt custom Python types to SQLite values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLite supports only a limited set of data types natively. @@ -1333,7 +1333,7 @@ This function can then be registered using :func:`register_adapter`. .. literalinclude:: ../includes/sqlite3/adapter_point_2.py -How to Convert 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 @@ -1373,7 +1373,7 @@ The following example illustrates the implicit and explicit approaches: .. literalinclude:: ../includes/sqlite3/converter_point.py -Default Adapters and Converters +Default adapters and converters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are default adapters for the date and datetime types in the datetime @@ -1405,7 +1405,7 @@ timestamp converter. .. _sqlite3-adapter-converter-recipes: -Adapter and Converter Recipes +Adapter and converter recipes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This section shows recipes for common adapters and converters. @@ -1450,7 +1450,7 @@ This section shows recipes for common adapters and converters. .. _sqlite3-controlling-transactions: -Transaction Control +Transaction control ------------------- The ``sqlite3`` module does not adhere to the transaction handling recommended @@ -1493,7 +1493,7 @@ regardless of the value of :attr:`~Connection.isolation_level`. .. _sqlite3-uri-tricks: -SQLite URI Tricks +SQLite URI tricks ----------------- Some useful URI tricks include: @@ -1522,11 +1522,11 @@ can be found in the `SQLite URI documentation`_. .. _SQLite URI documentation: https://www.sqlite.org/uri.html -How to Use ``sqlite3`` Efficiently +How to use ``sqlite3`` efficiently ---------------------------------- -How to Use Shortcut Methods +How to use shortcut methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using the nonstandard :meth:`execute`, :meth:`executemany` and @@ -1540,7 +1540,7 @@ directly using only a single call on the :class:`Connection` object. .. literalinclude:: ../includes/sqlite3/shortcut_methods.py -How to Access Columns by Name +How to access columns by name ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One useful feature of the :mod:`sqlite3` module is the built-in @@ -1554,7 +1554,7 @@ case-insensitively by name: .. _sqlite3-connection-context-manager: -How to Use a 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