From 84aa8650870d2350d93b759d4c9e3845e8ac3566 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 10 Feb 2023 14:22:12 +0100 Subject: [PATCH 1/5] Docs: use parameter list for sqlite3.Cursor.execute* --- Doc/library/sqlite3.rst | 45 ++++++++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bbdc891c930cf4..95ec0a75a2d1b6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1418,15 +1418,22 @@ Cursor objects .. method:: execute(sql, parameters=(), /) - Execute SQL statement *sql*. - Bind values to the statement using :ref:`placeholders - ` that map to the :term:`sequence` or :class:`dict` - *parameters*. + Execute SQL a single SQL statement, + optionally binding Python values using + :ref:`placeholders `. - :meth:`execute` will only execute a single SQL statement. If you try to execute - more than one statement with it, it will raise a :exc:`ProgrammingError`. Use - :meth:`executescript` if you want to execute multiple SQL statements with one - call. + :param unicode sql: + A single SQL statement. + + :param parameters: + Python values to bind to placeholders in *sql*. + A :class:`!dict` if named placeholders are used. + A :term:`!sequence` if unnamed placeholders are used. + See :ref:`sqlite3-placeholders`. + :type parameters: :class:`dict` | :term:`sequence` + + :raises ProgrammingError: + If *sql* contains more than one SQL statement. If :attr:`~Connection.autocommit` is :data:`LEGACY_TRANSACTION_CONTROL`, @@ -1435,15 +1442,29 @@ Cursor objects and there is no open transaction, a transaction is implicitly opened before executing *sql*. + Use :meth:`executescript` to execute multiple SQL statements. .. method:: executemany(sql, parameters, /) - Execute :ref:`parameterized ` SQL statement *sql* - against all parameter sequences or mappings found in the sequence - *parameters*. It is also possible to use an - :term:`iterator` yielding parameters instead of a sequence. + For every item in *parameters*, + repeatedly execute the :ref:`parameterized ` + SQL statement *sql*. + Uses the same implicit transaction handling as :meth:`~Cursor.execute`. + :param unicode sql: + A single SQL :abbr:`DML (Data Manipulation Language)` statement. + + :param parameters: + A :term:`sequence` or :term:`iterator` of parameters + to bind with the placeholders in *sql*. + See :ref:`sqlite3-placeholders`. + :type parameters: :term:`sequence` | :term:`iterator` + + :raises ProgrammingError: + If *sql* contains more than one SQL statement, + or is not a DML statment. + Example: .. testcode:: sqlite3.cursor From 9d1fb1df8c1f3f5c5930bd5a518167b659679d03 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 10 Feb 2023 17:50:31 +0100 Subject: [PATCH 2/5] Address review --- Doc/library/sqlite3.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 95ec0a75a2d1b6..029d328afacccc 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1422,7 +1422,7 @@ Cursor objects optionally binding Python values using :ref:`placeholders `. - :param unicode sql: + :param str sql: A single SQL statement. :param parameters: @@ -1452,14 +1452,14 @@ Cursor objects Uses the same implicit transaction handling as :meth:`~Cursor.execute`. - :param unicode sql: + :param str sql: A single SQL :abbr:`DML (Data Manipulation Language)` statement. :param parameters: A :term:`sequence` or :term:`iterator` of parameters to bind with the placeholders in *sql*. See :ref:`sqlite3-placeholders`. - :type parameters: :term:`sequence` | :term:`iterator` + :type parameters: :term:`iterable` :raises ProgrammingError: If *sql* contains more than one SQL statement, From bedcfd3382b2e89c2c79bce888183302add00322 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 10 Feb 2023 17:58:55 +0100 Subject: [PATCH 3/5] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- 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 029d328afacccc..fa0803de5af5f3 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1456,7 +1456,7 @@ Cursor objects A single SQL :abbr:`DML (Data Manipulation Language)` statement. :param parameters: - A :term:`sequence` or :term:`iterator` of parameters + An :term:`iterable` or :term:`iterator` of parameters to bind with the placeholders in *sql*. See :ref:`sqlite3-placeholders`. :type parameters: :term:`iterable` From ed08eabb8d59a5c05ed61934b99b9ae0ba23c135 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 10 Feb 2023 18:04:16 +0100 Subject: [PATCH 4/5] ... or iterator there's a slight difference --- 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 fa0803de5af5f3..e240adf7cf438a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1459,7 +1459,7 @@ Cursor objects An :term:`iterable` or :term:`iterator` of parameters to bind with the placeholders in *sql*. See :ref:`sqlite3-placeholders`. - :type parameters: :term:`iterable` + :type parameters: :term:`iterable` | :term:`iterator` :raises ProgrammingError: If *sql* contains more than one SQL statement, From 9dcc5da76c81c414b3db5999dfe8b77b9a627cbe Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 10 Feb 2023 18:43:58 +0100 Subject: [PATCH 5/5] Amend --- Doc/library/sqlite3.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index e240adf7cf438a..8ffc0aad91995c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1456,10 +1456,10 @@ Cursor objects A single SQL :abbr:`DML (Data Manipulation Language)` statement. :param parameters: - An :term:`iterable` or :term:`iterator` of parameters - to bind with the placeholders in *sql*. + An :term:`!iterable` of parameters to bind with + the placeholders in *sql*. See :ref:`sqlite3-placeholders`. - :type parameters: :term:`iterable` | :term:`iterator` + :type parameters: :term:`iterable` :raises ProgrammingError: If *sql* contains more than one SQL statement,