From 1d030fadbfb1ae430d55469c060469ef66e9370a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 13:40:14 +0200 Subject: [PATCH 1/8] gh-95235: Add explicit parameter list to some sqlite3 methods --- Doc/library/sqlite3.rst | 193 +++++++++++++++++++++++++++------------- 1 file changed, 133 insertions(+), 60 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 583a36d1ef46d6..1c04909e5403ee 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -286,7 +286,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. @@ -434,11 +434,34 @@ Connection Objects .. method:: blobopen(table, column, row, /, *, readonly=False, name="main") - Open a :class:`Blob` handle to the :abbr:`BLOB (Binary Large OBject)` - located in table name *table*, column name *column*, and row index *row* - of database *name*. - When *readonly* is :const:`True` the blob is opened without write - permissions. + 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 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: + Set to :const:`True` if the blob should be opened without write + permissions. + Defaults to :const:`False`. + :type readonly: bool + + :param name: + The name of the database where the blob is located. + Defaults to ``"main"``. + :type name: str + + :rtype: sqlite3.Blob + Trying to open a blob in a ``WITHOUT ROWID`` table will raise :exc:`OperationalError`. @@ -486,18 +509,31 @@ 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 `_, 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 a user-defined SQL function. + + :param name: + The name of the SQL function. + :type name: str + + :param narg: + The number of parameters the SQL function can accept. + If ``-1``, it may take any number of arguments. + :type narg: int - The function can return any of - :ref:`the types natively supported by SQLite `. + :param func: + 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 the SQL function. + :type func: :term:`callback` | :const:`None` + + :param deterministic: + If :const:`True`, the created SQL function is marked as + `deterministic `_, + 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. + :type deterministic: bool .. versionchanged:: 3.8 The *deterministic* parameter was added. @@ -509,15 +545,30 @@ Connection Objects .. method:: create_aggregate(name, /, n_arg, aggregate_class) - Creates a user-defined aggregate function. + Create a user-defined SQL aggregate function. + + :param name: + The name of the SQL aggregate function. + :type name: str + + :param narg: + The number of parameters the SQL aggregate function can accept. + If ``-1``, it may take any number of arguments. + :type narg: int - 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 aggregate_class: + A class that implements the following methods: - The ``finalize`` method can return any of - :ref:`the types natively supported by SQLite `. + * ``step()``: Add a row to the aggregate. + * ``finalize()``: Return the final result of the aggregate as + :ref:`a type natively supported by SQLite `. + + The ``step()`` method accept *n_arg* number of parameters, + unless *n_arg* is ``-1``, + in which case it may take any number of arguments. + + Set to :const:`None` to remove the SQL aggregate function. + :type aggregate_class: :term:`class` | :const:`None` Example: @@ -526,22 +577,33 @@ Connection Objects .. method:: create_window_function(name, num_params, aggregate_class, /) - Creates user-defined aggregate window function *name*. + Create a user-defined aggregate window function. + + :param name: + The name of the SQL aggregate window function. + :type name: str + + :param narg: + The number of parameters the SQL aggregate window function can accept. + If ``-1``, it may take any number of arguments. + :type narg: int + + :param aggregate_class: + A class that implements the following methods: + + * ``step()``: Add a row to the current window. + * ``value()``: Return the current value of the aggregate. + * ``inverse()``: Remove a row from the current window. + * ``finalize()``: Return the final result of the aggregate as + :ref:`a type natively supported by SQLite `. - *aggregate_class* must implement the following methods: + The ``step()`` and ``value()`` methods accept *num_params* number of + parameters, unless *num_params* is ``-1``, + in which case they may take any number of arguments. - * ``step``: adds a row to the current window - * ``value``: returns the current value of the aggregate - * ``inverse``: removes a row from the current window - * ``finalize``: returns the final value of the aggregate + Set to :const:`None` to remove the SQL aggregate window function. - ``step`` and ``value`` accept *num_params* number of parameters, - unless *num_params* is ``-1``, in which case they may take any number of - arguments. - ``finalize`` and ``value`` can return any of - :ref:`the types natively supported by SQLite `. - Call :meth:`create_window_function` with - *aggregate_class* set to :const:`None` to clear window function *name*. + :type aggregate_class: :term:`class` | :const:`None` Aggregate window functions are supported by SQLite 3.25.0 and higher. :exc:`NotSupportedError` will be raised if used with older versions. @@ -742,29 +804,40 @@ 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. - - 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. - - 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. - - 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. - - 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. + Create a backup of an SQLite database. + + :param target: + The database connection to save the backup to. + :type target: sqlite3.Connection + + :param pages: + If equal to or less than ``0``, + the entire database is copied in a single step; + otherwise the backup is performed *pages* pages at a time. + Defaults to ``-1``. + :type pages: int + + :param progress: + If set to a callable, it is invoked with three integer argument 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 backup. + 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 backup + remaining pages. + :type sleep: int | float Example 1, copy an existing database into another:: From f20107fd23cd106c1310c005b58271dacb16e01d Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 13:45:41 +0200 Subject: [PATCH 2/8] Fix n_arg param of create_aggregate --- 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 1c04909e5403ee..d5abebb973a23d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -551,10 +551,10 @@ Connection Objects The name of the SQL aggregate function. :type name: str - :param narg: + :param n_arg: The number of parameters the SQL aggregate function can accept. If ``-1``, it may take any number of arguments. - :type narg: int + :type na_rg: int :param aggregate_class: A class that implements the following methods: From 3a9b6f2dd046c59cb901d0acf2ab3ad8d0fd2c67 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 13:46:14 +0200 Subject: [PATCH 3/8] Fix num_params of create_window_func --- 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 d5abebb973a23d..d752b9eee86f0d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -583,10 +583,10 @@ Connection Objects The name of the SQL aggregate window function. :type name: str - :param narg: + :param num_params: The number of parameters the SQL aggregate window function can accept. If ``-1``, it may take any number of arguments. - :type narg: int + :type num_params: int :param aggregate_class: A class that implements the following methods: From c49508c0269cb4430909c22385fc49488386161c Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Mon, 25 Jul 2022 20:52:30 +0200 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 72 +++++++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index d752b9eee86f0d..1eab5b1e18f354 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -460,10 +460,10 @@ Connection Objects Defaults to ``"main"``. :type name: str - :rtype: sqlite3.Blob + :raises OperationalError: + When trying to open a blob in a ``WITHOUT ROWID`` table. - Trying to open a blob in a ``WITHOUT ROWID`` table will raise - :exc:`OperationalError`. + :rtype: sqlite3.Blob .. note:: @@ -509,14 +509,14 @@ Connection Objects .. method:: create_function(name, narg, func, *, deterministic=False) - Create a user-defined SQL function. + Create or remove a user-defined SQL function. :param name: The name of the SQL function. :type name: str :param narg: - The number of parameters the SQL function can accept. + The number of arguments the SQL function can accept. If ``-1``, it may take any number of arguments. :type narg: int @@ -524,19 +524,19 @@ 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 the SQL function. + 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 `_, which allows SQLite to perform additional optimizations. - This flag is supported by SQLite 3.8.3 or higher, + This flag is supported by SQLite 3.8.3 or higher; :exc:`NotSupportedError` will be raised if used with older versions. :type deterministic: bool - .. versionchanged:: 3.8 - The *deterministic* parameter was added. + .. versionadded:: 3.8 + The *deterministic* parameter. Example: @@ -545,7 +545,7 @@ Connection Objects .. method:: create_aggregate(name, /, n_arg, aggregate_class) - Create a user-defined SQL aggregate function. + Create or remove a user-defined SQL aggregate function. :param name: The name of the SQL aggregate function. @@ -554,20 +554,19 @@ Connection Objects :param n_arg: The number of parameters the SQL aggregate function can accept. If ``-1``, it may take any number of arguments. - :type na_rg: int + :type n_arg: int :param aggregate_class: - A class that implements the following methods: + 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 `. - The ``step()`` method accept *n_arg* number of parameters, - unless *n_arg* is ``-1``, - in which case it may take any number of arguments. + The number of arguments that the ``step()`` method must accept + is controlled by *n_arg*. - Set to :const:`None` to remove the SQL aggregate function. + Set to :const:`None` to remove an existing SQL aggregate function. :type aggregate_class: :term:`class` | :const:`None` Example: @@ -577,19 +576,19 @@ Connection Objects .. method:: create_window_function(name, num_params, aggregate_class, /) - Create a user-defined aggregate window function. + Create or remove a user-defined aggregate window function. :param name: - The name of the SQL aggregate window function. + The name of the SQL aggregate window function to create or remove. :type name: str :param num_params: - The number of parameters the SQL aggregate window function can accept. + 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 implements the following methods: + A class that must implement the following methods: * ``step()``: Add a row to the current window. * ``value()``: Return the current value of the aggregate. @@ -597,16 +596,16 @@ Connection Objects * ``finalize()``: Return the final result of the aggregate as :ref:`a type natively supported by SQLite `. - The ``step()`` and ``value()`` methods accept *num_params* number of - parameters, unless *num_params* is ``-1``, - in which case they may take any number of arguments. + The number of arguments that the ``step()`` and ``value()`` methods + must accept is controlled by *num_params*. - Set to :const:`None` to remove the SQL aggregate window function. + Set to :const:`None` to remove an existing SQL aggregate window function. - :type aggregate_class: :term:`class` | :const:`None` + :raises NotSupportedError: + If used with a version of SQLite older than 3.25.0, + which does not support aggregate window functions. - Aggregate window functions are supported by SQLite 3.25.0 and higher. - :exc:`NotSupportedError` will be raised if used with older versions. + :type aggregate_class: :term:`class` | :const:`None` .. versionadded:: 3.11 @@ -805,20 +804,23 @@ Connection Objects .. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250) Create a backup of an SQLite database. + + Works even if the database is being accessed by other clients + or concurrently by the same connection. :param target: The database connection to save the backup to. - :type target: sqlite3.Connection + :type target: Connection :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; - otherwise the backup is performed *pages* pages at a time. + 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 argument for + 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, @@ -827,7 +829,7 @@ Connection Objects :type progress: :term:`callback` | :const:`None` :param name: - The name of the database to backup. + 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 @@ -835,9 +837,9 @@ Connection Objects :type name: str :param sleep: - The number of seconds to sleep between successive attempts to backup - remaining pages. - :type sleep: int | float + 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:: From 0b2bc5375d2e6ef5d960ed46828935d2313cb55c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 21:01:34 +0200 Subject: [PATCH 5/8] Whitespace lint and fixup connect() --- 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 1eab5b1e18f354..a2eb9bbe46eaed 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -316,7 +316,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 @@ -804,7 +804,7 @@ Connection Objects .. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250) Create a backup of an SQLite database. - + Works even if the database is being accessed by other clients or concurrently by the same connection. From 5e6f614e9ea5f208de4729ee61191abe81737cdf Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 21:02:56 +0200 Subject: [PATCH 6/8] Fixup rtype of blobopen --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index a2eb9bbe46eaed..87f7c8f7e1d42c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -463,7 +463,7 @@ Connection Objects :raises OperationalError: When trying to open a blob in a ``WITHOUT ROWID`` table. - :rtype: sqlite3.Blob + :rtype: Blob .. note:: From 4875741205371e3f65c78d609de83ac9d9bd7acb Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Mon, 25 Jul 2022 21:05:29 +0200 Subject: [PATCH 7/8] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 87f7c8f7e1d42c..f107641a4730f1 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -552,7 +552,7 @@ Connection Objects :type name: str :param n_arg: - The number of parameters the SQL aggregate function can accept. + The number of arguments the SQL aggregate function can accept. If ``-1``, it may take any number of arguments. :type n_arg: int From 6d1aeab5e47dacfa575d0e39a12339950aebca0e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 26 Jul 2022 00:06:21 +0200 Subject: [PATCH 8/8] Add :raises: for create_function --- Doc/library/sqlite3.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f107641a4730f1..718ea35126bc31 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -531,10 +531,11 @@ Connection Objects If :const:`True`, the created SQL function is marked as `deterministic `_, 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. :type deterministic: bool + :raises NotSupportedError: + If *deterministic* is used with SQLite versions older than 3.8.3. + .. versionadded:: 3.8 The *deterministic* parameter.