From 3c69446433626607e900aff68daa3decfa0b1bf2 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Wed, 3 Aug 2022 22:21:15 +0200 Subject: [PATCH] [3.10] gh-95273: Align sqlite3 const doc refs with the devguide recommendations (GH-95525). (cherry picked from commit 4d02572f8c39b16c83c0883917db4e31efc1048e) Co-authored-by: Erlend Egeberg Aasland --- Doc/library/sqlite3.rst | 64 ++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 2b08040a00e64b..b1c8166a64b8ec 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 ` 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 `. - 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 `_, 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