[Python-checkins] [3.10] gh-95273: Align sqlite3 const doc refs with the devguide recommendations (GH-95525). (#95618)
erlend-aasland
webhook-mailer at python.org
Wed Aug 3 17:04:49 EDT 2022
https://github.com/python/cpython/commit/ac005ea8606e34c71b9a6a84ff4fd5d688422bd0
commit: ac005ea8606e34c71b9a6a84ff4fd5d688422bd0
branch: 3.10
author: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2022-08-03T23:04:35+02:00
summary:
[3.10] gh-95273: Align sqlite3 const doc refs with the devguide recommendations (GH-95525). (#95618)
(cherry picked from commit 4d02572f8c39b16c83c0883917db4e31efc1048e)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 2b08040a00e..b1c8166a64b 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -294,13 +294,13 @@ Module functions and constants
The :attr:`~Connection.isolation_level` of the connection,
controlling whether and how transactions are implicitly opened.
Can be ``"DEFERRED"`` (default), ``"EXCLUSIVE"`` or ``"IMMEDIATE"``;
- or :const:`None` to disable opening transactions implicitly.
+ or ``None`` to disable opening transactions implicitly.
See :ref:`sqlite3-controlling-transactions` for more.
- :type isolation_level: str | :const:`None`
+ :type isolation_level: str | None
:param check_same_thread:
- If :const:`True` (default), only the creating thread may use the connection.
- If :const:`False`, the connection may be shared across multiple threads;
+ If ``True`` (default), only the creating thread may use the connection.
+ If ``False``, the connection may be shared across multiple threads;
if so, write operations should be serialized by the user to avoid data
corruption.
:type check_same_thread: bool
@@ -317,7 +317,7 @@ Module functions and constants
:type cached_statements: int
:param uri:
- If set to :const:`True`, *database* is interpreted as a
+ If set to ``True``, *database* is interpreted as a
:abbr:`URI (Uniform Resource Identifier)` with a file path
and an optional query string.
The scheme part *must* be ``"file:"``,
@@ -366,7 +366,7 @@ Module functions and constants
.. function:: complete_statement(statement)
- Returns :const:`True` if the string *statement* contains one or more complete SQL
+ Returns ``True`` if the string *statement* contains one or more complete SQL
statements terminated by semicolons. It does not verify that the SQL is
syntactically correct, only that there are no unclosed string literals and the
statement is terminated by a semicolon.
@@ -383,7 +383,7 @@ Module functions and constants
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 ``True``. Afterwards, you will
- get tracebacks from callbacks on ``sys.stderr``. Use :const:`False` to
+ get tracebacks from callbacks on ``sys.stderr``. Use ``False`` to
disable the feature again.
@@ -410,7 +410,7 @@ Connection objects
This attribute controls the :ref:`transaction handling
<sqlite3-controlling-transactions>` performed by ``sqlite3``.
- If set to :const:`None`, transactions are never implicitly opened.
+ If set to ``None``, transactions are never implicitly opened.
If set to one of ``"DEFERRED"``, ``"IMMEDIATE"``, or ``"EXCLUSIVE"``,
corresponding to the underlying `SQLite transaction behaviour`_,
implicit :ref:`transaction management
@@ -424,8 +424,8 @@ Connection objects
This read-only attribute corresponds to the low-level SQLite
`autocommit mode`_.
- :const:`True` if a transaction is active (there are uncommitted changes),
- :const:`False` otherwise.
+ ``True`` if a transaction is active (there are uncommitted changes),
+ ``False`` otherwise.
.. versionadded:: 3.2
@@ -488,11 +488,11 @@ Connection objects
A callable that is called when the SQL function is invoked.
The callable must return :ref:`a type natively supported by SQLite
<sqlite3-types>`.
- Set to :const:`None` to remove an existing SQL function.
- :type func: :term:`callback` | :const:`None`
+ Set to ``None`` to remove an existing SQL function.
+ :type func: :term:`callback` | None
:param deterministic:
- If :const:`True`, the created SQL function is marked as
+ If ``True``, the created SQL function is marked as
`deterministic <https://sqlite.org/deterministic.html>`_,
which allows SQLite to perform additional optimizations.
:type deterministic: bool
@@ -531,8 +531,8 @@ Connection objects
The number of arguments that the ``step()`` method must accept
is controlled by *n_arg*.
- Set to :const:`None` to remove an existing SQL aggregate function.
- :type aggregate_class: :term:`class` | :const:`None`
+ Set to ``None`` to remove an existing SQL aggregate function.
+ :type aggregate_class: :term:`class` | None
Example:
@@ -553,7 +553,7 @@ Connection objects
.. literalinclude:: ../includes/sqlite3/collation_reverse.py
- Remove a collation function by setting *callable* to :const:`None`.
+ Remove a collation function by setting *callable* to ``None``.
.. method:: interrupt()
@@ -573,11 +573,11 @@ Connection objects
:mod:`sqlite3` module.
The first argument to the callback signifies what kind of operation is to be
- authorized. The second and third argument will be arguments or :const:`None`
+ authorized. The second and third argument will be arguments or ``None``
depending on the first argument. The 4th argument is the name of the database
("main", "temp", etc.) if applicable. The 5th argument is the name of the
inner-most trigger or view that is responsible for the access attempt or
- :const:`None` if this access attempt is directly from input SQL code.
+ ``None`` if this access attempt is directly from input SQL code.
Please consult the SQLite documentation about the possible values for the first
argument and the meaning of the second and third argument depending on the first
@@ -592,7 +592,7 @@ Connection objects
a GUI.
If you want to clear any previously installed progress handler, call the
- method with :const:`None` for *progress_handler*.
+ method with ``None`` for *progress_handler*.
Returning a non-zero value from the handler function will terminate the
currently executing query and cause it to raise an :exc:`OperationalError`
@@ -612,7 +612,7 @@ Connection objects
sqlite3 module and the execution of triggers defined in the current
database.
- Passing :const:`None` as *trace_callback* will disable the trace callback.
+ Passing ``None`` as *trace_callback* will disable the trace callback.
.. note::
Exceptions raised in the trace callback are not propagated. As a
@@ -626,7 +626,7 @@ Connection objects
.. method:: enable_load_extension(enabled, /)
Enable the SQLite engine to load SQLite extensions from shared libraries
- if *enabled* is :const:`True`;
+ if *enabled* is ``True``;
else, disallow loading SQLite extensions.
SQLite extensions can define new functions,
aggregates or whole new virtual table implementations. One well-known
@@ -744,8 +744,8 @@ Connection objects
the *status* of the last iteration,
the *remaining* number of pages still to be copied,
and the *total* number of pages.
- Defaults to :const:`None`.
- :type progress: :term:`callback` | :const:`None`
+ Defaults to ``None``.
+ :type progress: :term:`callback` | None
:param name:
The name of the database to back up.
@@ -825,7 +825,7 @@ Cursor objects
:meth:`executescript` if you want to execute multiple SQL statements with one
call.
- If :attr:`~Connection.isolation_level` is not :const:`None`,
+ If :attr:`~Connection.isolation_level` is not ``None``,
*sql* is an ``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statement,
and there is no open transaction,
a transaction is implicitly opened before executing *sql*.
@@ -873,7 +873,7 @@ Cursor objects
.. method:: fetchone()
Fetch the next row of a query result set as a :class:`tuple`.
- Return :const:`None` if no more data is available.
+ Return ``None`` if no more data is available.
.. method:: fetchmany(size=cursor.arraysize)
@@ -929,7 +929,7 @@ Cursor objects
using the :meth:`execute` method. For other statements, after
:meth:`executemany` or :meth:`executescript`, or if the insertion failed,
the value of ``lastrowid`` is left unchanged. The initial value of
- ``lastrowid`` is :const:`None`.
+ ``lastrowid`` is ``None``.
.. note::
Inserts into ``WITHOUT ROWID`` tables are not recorded.
@@ -946,7 +946,7 @@ Cursor objects
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`.
+ column where the last six items of each tuple are ``None``.
It is set for ``SELECT`` statements without any matching rows as well.
@@ -1107,7 +1107,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
Exception raised in case a method or database API is not supported by the
underlying SQLite library. For example, setting *deterministic* to
- :const:`True` in :meth:`~Connection.create_function`, if the underlying SQLite library
+ ``True`` in :meth:`~Connection.create_function`, if the underlying SQLite library
does not support deterministic functions.
``NotSupportedError`` is a subclass of :exc:`DatabaseError`.
@@ -1125,7 +1125,7 @@ The following Python types can thus be sent to SQLite without any problem:
+-------------------------------+-------------+
| Python type | SQLite type |
+===============================+=============+
-| :const:`None` | ``NULL`` |
+| ``None`` | ``NULL`` |
+-------------------------------+-------------+
| :class:`int` | ``INTEGER`` |
+-------------------------------+-------------+
@@ -1142,7 +1142,7 @@ This is how SQLite types are converted to Python types by default:
+-------------+----------------------------------------------+
| SQLite type | Python type |
+=============+==============================================+
-| ``NULL`` | :const:`None` |
+| ``NULL`` | ``None`` |
+-------------+----------------------------------------------+
| ``INTEGER`` | :class:`int` |
+-------------+----------------------------------------------+
@@ -1428,7 +1428,7 @@ 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`,
+is not ``None``,
new transactions are implicitly opened before
:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes
``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements.
@@ -1439,7 +1439,7 @@ 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`,
+If :attr:`~Connection.isolation_level` is set to ``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
More information about the Python-checkins
mailing list