FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

[3.11] gh-95273: Improve documented return values and exceptions raised for sqlite3 class methods (GH-95530) by erlend-aasland · Pull Request #95673 · python/cpython · GitHub

/ cpython Public

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erlend-aasland merged 1 commit into from
Aug 4, 2022
Conversation 0 Commits 1 Checks 0 Files changed
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension .rst  (1) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
134 changes: 72 additions & 62 deletions Doc/library/sqlite3.rst
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -316,33 +314,29 @@ 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.
The scheme part *must* be ``"file:"``,
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

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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::

Expand All @@ -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::

Expand All @@ -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
Expand All @@ -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")

Expand All @@ -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::

Expand All @@ -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::

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
Back | FazBrowse Home | New Git URL