From 4130c33faabc2fa1f4a8b5d5b606dfa27bb7d015 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 13:22:55 +0200 Subject: [PATCH 01/10] gh-95273: Normalise sqlite3 reference wording --- Doc/library/sqlite3.rst | 88 +++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 43 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index b75549448d4032..7f04ccc6124191 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -139,8 +139,8 @@ Module functions and constants .. data:: version - The version number of this module, as a string. This is not the version of - the SQLite library. + Version number of this module as a :class:`string `. + This is not the version of the SQLite library. .. deprecated-removed:: 3.12 3.14 This constant used to reflect the version number of the ``pysqlite`` @@ -150,8 +150,8 @@ Module functions and constants .. data:: version_info - The version number of this module, as a tuple of integers. This is not the - version of the SQLite library. + Version number of this module as a :class:`tuple` of :class:`integers `. + This is not the version of the SQLite library. .. deprecated-removed:: 3.12 3.14 This constant used to reflect the version number of the ``pysqlite`` @@ -161,12 +161,13 @@ Module functions and constants .. data:: sqlite_version - The version number of the run-time SQLite library, as a string. + Version number of the run-time SQLite library as a :class:`string `. .. data:: sqlite_version_info - The version number of the run-time SQLite library, as a tuple of integers. + Version number of the run-time SQLite library as a :class:`tuple` of + :class`integers `. .. data:: threadsafety @@ -369,6 +370,7 @@ Module functions and constants .. function:: enable_callback_tracebacks(flag, /) + Enable or disable callback tracebacks. By default you will not get any tracebacks in user-defined functions, aggregates, converters, authorizer callbacks etc. If you want to debug them, you can call this function with *flag* set to :const:`True`. Afterwards, you @@ -428,6 +430,7 @@ Connection Objects .. method:: cursor(factory=Cursor) + Create and return a :class:`Cursor` object. The cursor method accepts a single optional parameter *factory*. If supplied, this must be a callable returning an instance of :class:`Cursor` or its subclasses. @@ -638,9 +641,9 @@ Connection Objects .. method:: interrupt() - You can call this method from a different thread to abort any queries that might - be executing on the connection. The query will then abort and the caller will - get an exception. + Call this method from a different thread to abort any queries that might + be executing on the connection. + Aborted queries will raise an exception. .. method:: set_authorizer(authorizer_callback) @@ -745,10 +748,9 @@ Connection Objects .. attribute:: row_factory - You can change this attribute to a callable that accepts the cursor and the - original row as a tuple and will return the real result row. This way, you can - implement more advanced ways of returning results, such as returning an object - that can also access columns by name. + A callable that accepts two arguments, + a :class`Cursor` object and the raw row results as a :class:`tuple`, + and return any object that fit the application programmers need. Example: @@ -766,31 +768,28 @@ Connection Objects .. attribute:: text_factory - Using this attribute you can control what objects are returned for the ``TEXT`` - data type. By default, this attribute is set to :class:`str` and the - :mod:`sqlite3` module will return :class:`str` objects for ``TEXT``. - If you want to return :class:`bytes` instead, you can set it to :class:`bytes`. + A callable that accept a :class:`bytes` parameter and return a text + representation of it. + The callable is invoked for SQLite values with the ``TEXT``data type. + By default, this attribute is set to :class:`str`. + If you want to return ``bytes`` instead, set *text_factory* to ``bytes``. - You can also set it to any other callable that accepts a single bytestring - parameter and returns the resulting object. - - See the following example code for illustration: + Example: .. literalinclude:: ../includes/sqlite3/text_factory.py .. attribute:: total_changes - Returns the total number of database rows that have been modified, inserted, or + Return the total number of database rows that have been modified, inserted, or deleted since the database connection was opened. .. method:: iterdump - Returns an iterator to dump the database in an SQL text format. Useful when - saving an in-memory database for later restoration. This function provides - the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3` - shell. + Return an :term:`iterator` to dump the database as SQL source code. + Useful when saving an in-memory database for later restoration. + Similar to the :kbd:`.dump` command in the :program:`sqlite3` shell. Example:: @@ -905,7 +904,7 @@ Connection Objects .. method:: serialize(*, name="main") - This method serializes a database into a :class:`bytes` object. For an + Serialize a database into a :class:`bytes` object. For an ordinary on-disk database file, the serialization is just a copy of the disk file. For an in-memory database or a "temp" database, the serialization is the same sequence of bytes which would be written to @@ -924,6 +923,8 @@ Connection Objects .. method:: deserialize(data, /, *, name="main") + Deserialize a :meth:`serialized ` database into a + :class`Connection`. This method causes the database connection to disconnect from database *name*, and reopen *name* as an in-memory database based on the serialization contained in *data*. Deserialization will raise @@ -1003,20 +1004,19 @@ Cursor Objects .. method:: fetchone() - Fetches the next row of a query result set, returning a single sequence, - or :const:`None` when no more data is available. + Fetch the next row of a query result set as a :class:`tuple`. + Return :const:`None` when no more data is available. .. method:: fetchmany(size=cursor.arraysize) - Fetches the next set of rows of a query result, returning a list. An empty - list is returned when no more rows are available. + Fetch the next set of rows of a query result as a :class:`list`. + Return an empty list is when no more rows are available. The number of rows to fetch per call is specified by the *size* parameter. - If it is not given, the cursor's arraysize determines the number of rows - to be fetched. The method should try to fetch as many rows as indicated by - the size parameter. If this is not possible due to the specified number of - rows not being available, fewer rows may be returned. + If *size* is not given, :attr:`arraysize` determines the number of rows + to be fetched. + If fewer than *size* rows are available, fewer rows are returned. Note there are performance considerations involved with the *size* parameter. For optimal performance, it is usually best to use the arraysize attribute. @@ -1025,9 +1025,10 @@ Cursor Objects .. method:: fetchall() - Fetches all (remaining) rows of a query result, returning a list. Note that - the cursor's arraysize attribute can affect the performance of this operation. - An empty list is returned when no rows are available. + Fetch all (remaining) rows of a query result as a :class:`list`. + Return an empty list when no rows are available. + Note that the :attr:`arraysize` attribute can affect the performance of + this operation. .. method:: close() @@ -1054,7 +1055,7 @@ Cursor Objects .. attribute:: lastrowid - This read-only attribute provides the row id of the last inserted row. It + Read-only attribute that provides the row id of the last inserted row. It is only updated after successful ``INSERT`` or ``REPLACE`` statements using the :meth:`execute` method. For other statements, after :meth:`executemany` or :meth:`executescript`, or if the insertion failed, @@ -1074,7 +1075,7 @@ Cursor Objects .. attribute:: description - This read-only attribute provides the column names of the last query. To + Read-only attribute that provides the column names of the last query. To remain compatible with the Python DB API, it returns a 7-tuple for each column where the last six items of each tuple are :const:`None`. @@ -1082,8 +1083,8 @@ Cursor Objects .. attribute:: connection - This read-only attribute provides the SQLite database :class:`Connection` - used by the :class:`Cursor` object. A :class:`Cursor` object created by + Read-only attribute that provides the SQLite database :class:`Connection` + belonging to the cursor. A :class:`Cursor` object created by calling :meth:`con.cursor() ` will have a :attr:`connection` attribute that refers to *con*:: @@ -1111,7 +1112,8 @@ Row Objects .. method:: keys - This method returns a list of column names. Immediately after a query, + Return a :class:`list` of column names as :class:`strings `. + Immediately after a query, it is the first member of each tuple in :attr:`Cursor.description`. .. versionchanged:: 3.5 From ba083e80661da2d5cd68b3bd7ceecf4771405594 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 13:24:12 +0200 Subject: [PATCH 02/10] Syntax --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 7f04ccc6124191..7cfa1b37247f26 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -167,7 +167,7 @@ Module functions and constants .. data:: sqlite_version_info Version number of the run-time SQLite library as a :class:`tuple` of - :class`integers `. + :class:`integers `. .. data:: threadsafety From 413c54e924cc2dbbd2f23074c294062011a478cf Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 13:25:02 +0200 Subject: [PATCH 03/10] More syntax --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 7cfa1b37247f26..38f62e00736617 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -749,7 +749,7 @@ Connection Objects .. attribute:: row_factory A callable that accepts two arguments, - a :class`Cursor` object and the raw row results as a :class:`tuple`, + a :class:`Cursor` object and the raw row results as a :class:`tuple`, and return any object that fit the application programmers need. Example: From 8eb1c20b2de0ee0c16077708d04f47d4fedceeb9 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 13:25:54 +0200 Subject: [PATCH 04/10] Even more syntax --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 38f62e00736617..22b5dcddcb8e47 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -770,7 +770,7 @@ Connection Objects A callable that accept a :class:`bytes` parameter and return a text representation of it. - The callable is invoked for SQLite values with the ``TEXT``data type. + The callable is invoked for SQLite values with the ``TEXT`` data type. By default, this attribute is set to :class:`str`. If you want to return ``bytes`` instead, set *text_factory* to ``bytes``. From d446d749ffc99f3020366678c01b874f9f311ccd Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 13:27:42 +0200 Subject: [PATCH 05/10] Guess what, even more syntax --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 22b5dcddcb8e47..eb070f9021083c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -924,7 +924,7 @@ Connection Objects .. method:: deserialize(data, /, *, name="main") Deserialize a :meth:`serialized ` database into a - :class`Connection`. + :class:`Connection`. This method causes the database connection to disconnect from database *name*, and reopen *name* as an in-memory database based on the serialization contained in *data*. Deserialization will raise From 5ac3e267f39931682158749c36116fcf5d28482c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 27 Jul 2022 13:46:45 +0200 Subject: [PATCH 06/10] Address CAM's review --- Doc/library/sqlite3.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index eb070f9021083c..6eff77ffd13d9f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -768,7 +768,7 @@ Connection Objects .. attribute:: text_factory - A callable that accept a :class:`bytes` parameter and return a text + A callable that accepts a :class:`bytes` parameter and returns a text representation of it. The callable is invoked for SQLite values with the ``TEXT`` data type. By default, this attribute is set to :class:`str`. @@ -789,7 +789,7 @@ Connection Objects Return an :term:`iterator` to dump the database as SQL source code. Useful when saving an in-memory database for later restoration. - Similar to the :kbd:`.dump` command in the :program:`sqlite3` shell. + Similar to the ``.dump` command in the :program:`sqlite3` shell. Example:: @@ -1011,7 +1011,7 @@ Cursor Objects .. method:: fetchmany(size=cursor.arraysize) Fetch the next set of rows of a query result as a :class:`list`. - Return an empty list is when no more rows are available. + Return an empty list when no more rows are available. The number of rows to fetch per call is specified by the *size* parameter. If *size* is not given, :attr:`arraysize` determines the number of rows From cf109b08b27c7109a2087baac0918137f5c67193 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 27 Jul 2022 13:54:24 +0200 Subject: [PATCH 07/10] syntax --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6eff77ffd13d9f..4310ed239d5bc8 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -789,7 +789,7 @@ Connection Objects Return an :term:`iterator` to dump the database as SQL source code. Useful when saving an in-memory database for later restoration. - Similar to the ``.dump` command in the :program:`sqlite3` shell. + Similar to the ``.dump`` command in the :program:`sqlite3` shell. Example:: From e92290afdc0379784c7262fdcfe89a58985bff5a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 27 Jul 2022 14:43:14 +0200 Subject: [PATCH 08/10] Address Alex' review --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4310ed239d5bc8..2e8fc4e509364f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -750,7 +750,7 @@ Connection Objects A callable that accepts two arguments, a :class:`Cursor` object and the raw row results as a :class:`tuple`, - and return any object that fit the application programmers need. + and returns a custom object representing an SQLite row. Example: From fdc49d29f14db9650687c24047a8b68692062698 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 27 Jul 2022 14:59:38 +0200 Subject: [PATCH 09/10] Address Alex's full review --- Doc/library/sqlite3.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 2e8fc4e509364f..0c3ad2296d44ab 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -161,12 +161,12 @@ Module functions and constants .. data:: sqlite_version - Version number of the run-time SQLite library as a :class:`string `. + Version number of the runtime SQLite library as a :class:`string `. .. data:: sqlite_version_info - Version number of the run-time SQLite library as a :class:`tuple` of + Version number of the runtime SQLite library as a :class:`tuple` of :class:`integers `. @@ -870,7 +870,7 @@ Connection Objects .. method:: getlimit(category, /) - Get a connection run-time limit. *category* is the limit category to be + Get a connection runtime limit. *category* is the limit category to be queried. Example, query the maximum length of an SQL statement:: @@ -885,7 +885,7 @@ Connection Objects .. method:: setlimit(category, limit, /) - Set a connection run-time limit. *category* is the limit category to be + Set a connection runtime limit. *category* is the limit category to be set. *limit* is the new limit. If the new limit is a negative number, the limit is unchanged. @@ -1011,12 +1011,13 @@ Cursor Objects .. method:: fetchmany(size=cursor.arraysize) Fetch the next set of rows of a query result as a :class:`list`. - Return an empty list when no more rows are available. + Return an empty list if no more rows are available. The number of rows to fetch per call is specified by the *size* parameter. If *size* is not given, :attr:`arraysize` determines the number of rows to be fetched. - If fewer than *size* rows are available, fewer rows are returned. + If fewer than *size* rows are available, + as many rows as are available are returned. Note there are performance considerations involved with the *size* parameter. For optimal performance, it is usually best to use the arraysize attribute. @@ -1026,7 +1027,7 @@ Cursor Objects .. method:: fetchall() Fetch all (remaining) rows of a query result as a :class:`list`. - Return an empty list when no rows are available. + Return an empty list if no rows are available. Note that the :attr:`arraysize` attribute can affect the performance of this operation. From 4cf5af419e63a874c7df30bc36310903c384140b Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Wed, 27 Jul 2022 15:12:27 +0200 Subject: [PATCH 10/10] Missed one spot Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 0c3ad2296d44ab..1128f7f9fe2fe8 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1005,7 +1005,7 @@ Cursor Objects .. method:: fetchone() Fetch the next row of a query result set as a :class:`tuple`. - Return :const:`None` when no more data is available. + Return :const:`None` if no more data is available. .. method:: fetchmany(size=cursor.arraysize)