mirror of
https://github.com/python/cpython.git
synced 2026-02-13 19:04:37 +00:00
[3.10] gh-95235: Add explicit parameter list to some sqlite3 methods (GH-95240) (#95268)
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 5012bedc7c)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
This commit is contained in:
Erlend Egeberg Aasland
GitHub
parent
dd0c1a3577
commit
a4fd732155
1 changed files with 83 additions and 41 deletions
|
|
@ -258,7 +258,7 @@ Module functions and constants
|
|||
Can be ``"DEFERRED"`` (default), ``"EXCLUSIVE"`` or ``"IMMEDIATE"``;
|
||||
or :const:`None` to disable opening transactions implicitly.
|
||||
See :ref:`sqlite3-controlling-transactions` for more.
|
||||
:type isolation_level: str | None
|
||||
:type isolation_level: str | :const:`None`
|
||||
|
||||
:param check_same_thread:
|
||||
If :const:`True` (default), only the creating thread may use the connection.
|
||||
|
|
@ -288,7 +288,7 @@ Module functions and constants
|
|||
enabling various :ref:`sqlite3-uri-tricks`.
|
||||
:type uri: bool
|
||||
|
||||
:rtype: sqlite3.Connection
|
||||
:rtype: Connection
|
||||
|
||||
.. audit-event:: sqlite3.connect database sqlite3.connect
|
||||
.. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
|
||||
|
|
@ -423,21 +423,35 @@ Connection Objects
|
|||
|
||||
.. method:: create_function(name, narg, func, *, deterministic=False)
|
||||
|
||||
Creates a user-defined function that you can later use from within SQL
|
||||
statements under the function name *name*. *narg* is the number of
|
||||
parameters the function accepts (if *narg* is -1, the function may
|
||||
take any number of arguments), and *func* is a Python callable that is
|
||||
called as the SQL function. If *deterministic* is true, the created function
|
||||
is marked as `deterministic <https://sqlite.org/deterministic.html>`_, which
|
||||
allows SQLite to perform additional optimizations. This flag is supported by
|
||||
SQLite 3.8.3 or higher, :exc:`NotSupportedError` will be raised if used
|
||||
with older versions.
|
||||
Create or remove a user-defined SQL function.
|
||||
|
||||
The function can return any of
|
||||
:ref:`the types natively supported by SQLite <sqlite3-types>`.
|
||||
:param name:
|
||||
The name of the SQL function.
|
||||
:type name: str
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
The *deterministic* parameter was added.
|
||||
:param narg:
|
||||
The number of arguments the SQL function can accept.
|
||||
If ``-1``, it may take any number of arguments.
|
||||
:type narg: int
|
||||
|
||||
:param func:
|
||||
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`
|
||||
|
||||
:param deterministic:
|
||||
If :const:`True`, the created SQL function is marked as
|
||||
`deterministic <https://sqlite.org/deterministic.html>`_,
|
||||
which allows SQLite to perform additional optimizations.
|
||||
:type deterministic: bool
|
||||
|
||||
:raises NotSupportedError:
|
||||
If *deterministic* is used with SQLite versions older than 3.8.3.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
The *deterministic* parameter.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -446,15 +460,29 @@ Connection Objects
|
|||
|
||||
.. method:: create_aggregate(name, /, n_arg, aggregate_class)
|
||||
|
||||
Creates a user-defined aggregate function.
|
||||
Create or remove a user-defined SQL aggregate function.
|
||||
|
||||
The aggregate class must implement a ``step`` method, which accepts the number
|
||||
of parameters *n_arg* (if *n_arg* is -1, the function may take
|
||||
any number of arguments), and a ``finalize`` method which will return the
|
||||
final result of the aggregate.
|
||||
:param name:
|
||||
The name of the SQL aggregate function.
|
||||
:type name: str
|
||||
|
||||
The ``finalize`` method can return any of
|
||||
:ref:`the types natively supported by SQLite <sqlite3-types>`.
|
||||
:param n_arg:
|
||||
The number of arguments the SQL aggregate function can accept.
|
||||
If ``-1``, it may take any number of arguments.
|
||||
:type n_arg: int
|
||||
|
||||
:param aggregate_class:
|
||||
A class must implement the following methods:
|
||||
|
||||
* ``step()``: Add a row to the aggregate.
|
||||
* ``finalize()``: Return the final result of the aggregate as
|
||||
:ref:`a type natively supported by SQLite <sqlite3-types>`.
|
||||
|
||||
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`
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -643,29 +671,43 @@ Connection Objects
|
|||
|
||||
.. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)
|
||||
|
||||
This method makes a backup of an SQLite database even while it's being accessed
|
||||
by other clients, or concurrently by the same connection. The copy will be
|
||||
written into the mandatory argument *target*, that must be another
|
||||
:class:`Connection` instance.
|
||||
Create a backup of an SQLite database.
|
||||
|
||||
By default, or when *pages* is either ``0`` or a negative integer, the entire
|
||||
database is copied in a single step; otherwise the method performs a loop
|
||||
copying up to *pages* pages at a time.
|
||||
Works even if the database is being accessed by other clients
|
||||
or concurrently by the same connection.
|
||||
|
||||
If *progress* is specified, it must either be ``None`` or a callable object that
|
||||
will be executed at each iteration with three integer arguments, respectively
|
||||
the *status* of the last iteration, the *remaining* number of pages still to be
|
||||
copied and the *total* number of pages.
|
||||
:param target:
|
||||
The database connection to save the backup to.
|
||||
:type target: Connection
|
||||
|
||||
The *name* argument specifies the database name that will be copied: it must be
|
||||
a string containing either ``"main"``, the default, to indicate the main
|
||||
database, ``"temp"`` to indicate the temporary database or the name specified
|
||||
after the ``AS`` keyword in an ``ATTACH DATABASE`` statement for an attached
|
||||
database.
|
||||
:param pages:
|
||||
The number of pages to copy at a time.
|
||||
If equal to or less than ``0``,
|
||||
the entire database is copied in a single step.
|
||||
Defaults to ``-1``.
|
||||
:type pages: int
|
||||
|
||||
The *sleep* argument specifies the number of seconds to sleep by between
|
||||
successive attempts to backup remaining pages, can be specified either as an
|
||||
integer or a floating point value.
|
||||
:param progress:
|
||||
If set to a callable, it is invoked with three integer arguments for
|
||||
every backup iteration:
|
||||
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`
|
||||
|
||||
:param name:
|
||||
The name of the database to back up.
|
||||
Either ``"main"`` (the default) for the main database,
|
||||
``"temp"`` for the temporary database,
|
||||
or the name of a custom database as attached using the
|
||||
``ATTACH DATABASE`` SQL statment.
|
||||
:type name: str
|
||||
|
||||
:param sleep:
|
||||
The number of seconds to sleep between successive attempts
|
||||
to back up remaining pages.
|
||||
:type sleep: float
|
||||
|
||||
Example 1, copy an existing database into another::
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue