mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-05 06:31:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.11] gh-95273: Improve documented return values and exceptions raised for sqlite3 class methods (GH-95530) (#95673)

Browse source 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 12d92c733c)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
This commit is contained in:
Erlend Egeberg Aasland 2022-08-04 22:13:22 +02:00 • committed by GitHub
parent 6d83441442
commit c9986be733
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 72 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

134
Doc/library/sqlite3.rst
View file

@ -285,15 +285,14 @@ Module functions and constants
in RAM instead of on disk.
:type database: :term:`path-like object`
:param timeout:
:param float timeout:
How many seconds the connection should wait before raising
an exception, if the database is locked by another connection.
If another connection opens a transaction to modify the database,
it will be locked until that transaction is committed.
Default five seconds.
:type timeout: float
:param detect_types:
:param int detect_types:
Control whether and how data types not
:ref:`natively supported by SQLite <sqlite3-types>`
are looked up to be converted to Python types,
@ -306,7 +305,6 @@ Module functions and constants
even when the *detect_types* parameter is set; :class:`str` will be
returned instead.
By default (``0``), type detection is disabled.
:type detect_types: int
:param isolation_level:
The :attr:`~Connection.isolation_level` of the connection,
@ -316,25 +314,22 @@ Module functions and constants
See :ref:`sqlite3-controlling-transactions` for more.
:type isolation_level: str | None
:param check_same_thread:
:param bool check_same_thread:
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
:param factory:
:param Connection factory:
A custom subclass of :class:`Connection` to create the connection with,
if not the default :class:`Connection` class.
:type factory: :class:`Connection`
:param cached_statements:
:param int cached_statements:
The number of statements that ``sqlite3``
should internally cache for this connection, to avoid parsing overhead.
By default, 128 statements.
:type cached_statements: int
:param uri:
:param bool uri:
If set to ``True``, *database* is interpreted as a
:abbr:`URI (Uniform Resource Identifier)` with a file path
and an optional query string.
@ -342,7 +337,6 @@ Module functions and constants
and the path can be relative or absolute.
The query string allows passing parameters to SQLite,
enabling various :ref:`sqlite3-uri-tricks`.
:type uri: bool
:rtype: Connection
@ -477,28 +471,23 @@ Connection objects
Open a :class:`Blob` handle to an existing
:abbr:`BLOB (Binary Large OBject)`.
:param table:
:param str table:
The name of the table where the blob is located.
:type table: str
:param column:
:param str column:
The name of the column where the blob is located.
:type column: str
:param row:
:param str row:
The name of the row where the blob is located.
:type row: str
:param readonly:
:param bool readonly:
Set to ``True`` if the blob should be opened without write
permissions.
Defaults to ``False``.
:type readonly: bool
:param name:
:param str name:
The name of the database where the blob is located.
Defaults to ``"main"``.
:type name: str
:raises OperationalError:
When trying to open a blob in a ``WITHOUT ROWID`` table.
@ -551,14 +540,12 @@ Connection objects
Create or remove a user-defined SQL function.
:param name:
:param str name:
The name of the SQL function.
:type name: str
:param narg:
:param int 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.
@ -567,11 +554,10 @@ Connection objects
Set to ``None`` to remove an existing SQL function.
:type func: :term:`callback` | None
:param deterministic:
:param bool deterministic:
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
:raises NotSupportedError:
If *deterministic* is used with SQLite versions older than 3.8.3.
@ -588,14 +574,12 @@ Connection objects
Create or remove a user-defined SQL aggregate function.
:param name:
:param str name:
The name of the SQL aggregate function.
:type name: str
:param n_arg:
:param int 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:
@ -619,14 +603,12 @@ Connection objects
Create or remove a user-defined aggregate window function.
:param name:
:param str name:
The name of the SQL aggregate window function to create or remove.
:type name: str
:param num_params:
:param int num_params:
The number of arguments the SQL aggregate window function can accept.
If ``-1``, it may take any number of arguments.
:type num_params: int
:param aggregate_class:
A class that must implement the following methods:
@ -852,16 +834,14 @@ Connection objects
Works even if the database is being accessed by other clients
or concurrently by the same connection.
:param target:
:param Connection target:
The database connection to save the backup to.
:type target: Connection
:param pages:
:param int 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
:param progress:
If set to a callable, it is invoked with three integer arguments for
@ -872,18 +852,16 @@ Connection objects
Defaults to ``None``.
:type progress: :term:`callback` | None
:param name:
:param str 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 statement.
:type name: str
:param sleep:
:param float 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::
@ -909,11 +887,17 @@ Connection objects
.. versionadded:: 3.7
.. method:: getlimit(category, /)
Get a connection runtime limit. *category* is the limit category to be
queried.
Get a connection runtime limit.
:param int category:
The `SQLite limit category`_ to be queried.
:rtype: int
:raises ProgrammingError:
If *category* is not recognised by the underlying SQLite library.
Example, query the maximum length of an SQL statement::
@ -927,14 +911,23 @@ Connection objects
.. method:: setlimit(category, limit, /)
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.
Set a connection runtime limit.
Attempts to increase a limit above its hard upper bound are silently
truncated to the hard upper bound. Regardless of whether or not the limit
was changed, the prior value of the limit is returned.
:param int category:
The `SQLite limit category`_ to be set.
:param int limit:
The value of the new limit.
If negative, the current limit is unchanged.
:rtype: int
:raises ProgrammingError:
If *category* is not recognised by the underlying SQLite library.
Example, limit the number of attached databases to 1::
import sqlite3
@ -943,6 +936,8 @@ Connection objects
.. versionadded:: 3.11
.. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html
.. method:: serialize(*, name="main")
@ -952,8 +947,11 @@ Connection objects
serialization is the same sequence of bytes which would be written to
disk if that database were backed up to disk.
*name* is the database to be serialized, and defaults to the main
database.
:param str name:
The database name to be serialized.
Defaults to ``"main"``.
:rtype: bytes
.. note::
@ -969,12 +967,24 @@ Connection objects
: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
:exc:`OperationalError` if the database connection is currently involved
in a read transaction or a backup operation. :exc:`OverflowError` will be
raised if ``len(data)`` is larger than ``2**63 - 1``, and
:exc:`DatabaseError` will be raised if *data* does not contain a valid
SQLite database.
serialization contained in *data*.
:param bytes data:
A serialized database.
:param str name:
The database name to deserialize into.
Defaults to ``"main"``.
:raises OperationalError:
If the database connection is currently involved in a read
transaction or a backup operation.
:raises DatabaseError:
If *data* does not contain a valid SQLite database.
:raises OverflowError:
If :func:`len(data) <len>` is larger than ``2**63 - 1``.
.. note::
@ -1071,13 +1081,13 @@ Cursor objects
.. method:: fetchone()
Fetch the next row of a query result set as a :class:`tuple`.
Return the next row of a query result set as a :class:`tuple`.
Return ``None`` if no more data is available.
.. method:: fetchmany(size=cursor.arraysize)
Fetch the next set of rows of a query result as a :class:`list`.
Return the next set of rows of a query result as a :class:`list`.
Return an empty list if no more rows are available.
The number of rows to fetch per call is specified by the *size* parameter.
@ -1093,7 +1103,7 @@ Cursor objects
.. method:: fetchall()
Fetch all (remaining) rows of a query result as a :class:`list`.
Return all (remaining) rows of a query result as a :class:`list`.
Return an empty list if no rows are available.
Note that the :attr:`arraysize` attribute can affect the performance of
this operation.