From f9dc7d60fda97aab3da5c3435cf1293b66445130 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 1 Aug 2022 13:29:37 +0200 Subject: [PATCH 1/5] gh-95273: Improve return values and exceptions raised for sqlite3 class methods --- Doc/library/sqlite3.rst | 69 +++++++++++++++++++++++++++++++---------- 1 file changed, 52 insertions(+), 17 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 35eb404513b4d1..4603cc750ce77e 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -919,11 +919,20 @@ Connection objects .. versionadded:: 3.7 +.. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html .. method:: getlimit(category, /) - Get a connection runtime limit. *category* is the limit category to be - queried. + Get a connection runtime limit. + + :param category: + The `SQLite limit category` to be queried. + :type category: int + + :rtype: int + + :raises ProgrammingError: + If *category* is not recognised by the underlying SQLite library. Example, query the maximum length of an SQL statement:: @@ -937,13 +946,25 @@ 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. + truncated to the hard upper bound. + Regardless of whether or not the limit was changed, + the prior value of the limit is returned. + + :param category: + The `SQLite limit category` to be set. + :type category: int + + :param limit: + The value of the new limit. + If negative, the current limit is unchanged. + :type limit: int + + :rtype: int + + :raises ProgrammingError: + If *category* is not recognised by the underlying SQLite library. Example, limit the number of attached databases to 1:: @@ -979,12 +1000,26 @@ 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 data: + A serialized database. + :type data: bytes + + :param name: + The database name to deserialize into. + Defaults to ``"main"``. + :type name: str + + :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) ` is larger than ``2**63 - 1``. .. note:: @@ -1081,13 +1116,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 :const:`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. @@ -1103,7 +1138,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. From ccc8469702359b77c3c69b2bb928641b041c9d34 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 1 Aug 2022 13:33:43 +0200 Subject: [PATCH 2/5] Fix html links --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4603cc750ce77e..eed92659d08165 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -926,7 +926,7 @@ Connection objects Get a connection runtime limit. :param category: - The `SQLite limit category` to be queried. + The `SQLite limit category`_ to be queried. :type category: int :rtype: int @@ -953,7 +953,7 @@ Connection objects the prior value of the limit is returned. :param category: - The `SQLite limit category` to be set. + The `SQLite limit category`_ to be set. :type category: int :param limit: From a5ff4e60a159474729b696a34d810bbe52a27e70 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 Aug 2022 13:03:05 +0200 Subject: [PATCH 3/5] Address review, and expand PR to include more stuff --- Doc/library/sqlite3.rst | 121 +++++++++++++++------------------------- 1 file changed, 44 insertions(+), 77 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index efd071f4a1c86c..bef427b913eb03 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -295,15 +295,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 ` are looked up to be converted to Python types, @@ -316,7 +315,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, @@ -326,25 +324,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. @@ -352,7 +347,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 @@ -487,28 +481,18 @@ Connection objects Open a :class:`Blob` handle to an existing :abbr:`BLOB (Binary Large OBject)`. - :param table: - The name of the table where the blob is located. - :type table: str + :param str table: The name of the table where the blob is located. + :param str column: The name of the column where the blob is located. + :param str row: The name of the row where the blob is located. - :param column: - The name of the column where the blob is located. - :type column: str - - :param 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. @@ -561,14 +545,11 @@ Connection objects Create or remove a user-defined SQL function. - :param name: - The name of the SQL function. - :type name: str + :param str name: The name of the SQL function. - :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. @@ -577,11 +558,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 `_, which allows SQLite to perform additional optimizations. - :type deterministic: bool :raises NotSupportedError: If *deterministic* is used with SQLite versions older than 3.8.3. @@ -598,14 +578,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: @@ -629,14 +607,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: @@ -862,16 +838,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 @@ -882,18 +856,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 statment. - :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:: @@ -919,20 +891,16 @@ Connection objects .. versionadded:: 3.7 -.. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html - .. method:: getlimit(category, /) Get a connection runtime limit. - :param category: - The `SQLite limit category`_ to be queried. - :type category: int + :param int category: The `SQLite limit category`_ to be queried. :rtype: int :raises ProgrammingError: - If *category* is not recognised by the underlying SQLite library. + If *category* is not recognised by the underlying SQLite library. Example, query the maximum length of an SQL statement:: @@ -952,19 +920,16 @@ Connection objects Regardless of whether or not the limit was changed, the prior value of the limit is returned. - :param category: - The `SQLite limit category`_ to be set. - :type category: int + :param int category: The `SQLite limit category`_ to be set. - :param limit: - The value of the new limit. - If negative, the current limit is unchanged. - :type limit: int + :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. + If *category* is not recognised by the underlying SQLite library. Example, limit the number of attached databases to 1:: @@ -974,6 +939,8 @@ Connection objects .. versionadded:: 3.11 +.. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html + .. method:: serialize(*, name="main") @@ -983,8 +950,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:: @@ -1002,24 +972,21 @@ Connection objects *name*, and reopen *name* as an in-memory database based on the serialization contained in *data*. - :param data: - A serialized database. - :type data: bytes + :param bytes data: A serialized database. - :param name: - The database name to deserialize into. - Defaults to ``"main"``. - :type name: str + :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. + 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. + If *data* does not contain a valid SQLite database. :raises OverflowError: - If :func:`len(data) ` is larger than ``2**63 - 1``. + If :func:`len(data) ` is larger than ``2**63 - 1``. .. note:: From c4ae7faad90f148cc760e801891699e906bc82c6 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Thu, 4 Aug 2022 13:50:19 +0200 Subject: [PATCH 4/5] Revert unneeded reflow Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bef427b913eb03..ff2a9b3ebd21c2 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -916,9 +916,8 @@ Connection objects 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. + 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. From 8f3c1d68312eea67fff039b7f4afe051459be726 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 Aug 2022 13:58:12 +0200 Subject: [PATCH 5/5] Be tidy: Keep descriptions on separate lines --- Doc/library/sqlite3.rst | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index ff2a9b3ebd21c2..b7aa5d00a259d5 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -481,9 +481,14 @@ Connection objects Open a :class:`Blob` handle to an existing :abbr:`BLOB (Binary Large OBject)`. - :param str table: The name of the table where the blob is located. - :param str column: The name of the column where the blob is located. - :param str row: The name of the row where the blob is located. + :param str table: + The name of the table where the blob is located. + + :param str column: + The name of the column where the blob is located. + + :param str row: + The name of the row where the blob is located. :param bool readonly: Set to ``True`` if the blob should be opened without write @@ -545,7 +550,8 @@ Connection objects Create or remove a user-defined SQL function. - :param str name: The name of the SQL function. + :param str name: + The name of the SQL function. :param int narg: The number of arguments the SQL function can accept. @@ -895,7 +901,8 @@ Connection objects Get a connection runtime limit. - :param int category: The `SQLite limit category`_ to be queried. + :param int category: + The `SQLite limit category`_ to be queried. :rtype: int @@ -919,7 +926,8 @@ Connection objects 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 category: + The `SQLite limit category`_ to be set. :param int limit: The value of the new limit. @@ -971,7 +979,8 @@ Connection objects *name*, and reopen *name* as an in-memory database based on the serialization contained in *data*. - :param bytes data: A serialized database. + :param bytes data: + A serialized database. :param str name: The database name to deserialize into.