[Python-checkins] Docs: use parameter list for sqlite3.Cursor.execute* (GH-101782)
miss-islington
webhook-mailer at python.org
Fri Feb 10 13:01:55 EST 2023
https://github.com/python/cpython/commit/18313ecb09fe29849724738ddd3cde9510ffd50b
commit: 18313ecb09fe29849724738ddd3cde9510ffd50b
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2023-02-10T10:01:38-08:00
summary:
Docs: use parameter list for sqlite3.Cursor.execute* (GH-101782)
(cherry picked from commit 2037ebf81bd4bbe5421421b822bd57cfd665a1e9)
Co-authored-by: Erlend E. Aasland <erlend.aasland at protonmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 8a0d84d1c4b1..fd8a032aff73 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1335,30 +1335,51 @@ Cursor objects
.. method:: execute(sql, parameters=(), /)
- Execute SQL statement *sql*.
- Bind values to the statement using :ref:`placeholders
- <sqlite3-placeholders>` that map to the :term:`sequence` or :class:`dict`
- *parameters*.
+ Execute SQL a single SQL statement,
+ optionally binding Python values using
+ :ref:`placeholders <sqlite3-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 str 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.isolation_level` is not ``None``,
*sql* is an ``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statement,
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 <sqlite3-placeholders>` 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 <sqlite3-placeholders>`
+ SQL statement *sql*.
+
Uses the same implicit transaction handling as :meth:`~Cursor.execute`.
+ :param str sql:
+ A single SQL :abbr:`DML (Data Manipulation Language)` statement.
+
+ :param parameters:
+ An :term:`!iterable` of parameters to bind with
+ the placeholders in *sql*.
+ See :ref:`sqlite3-placeholders`.
+ :type parameters: :term:`iterable`
+
+ :raises ProgrammingError:
+ If *sql* contains more than one SQL statement,
+ or is not a DML statment.
+
Example:
.. testcode:: sqlite3.cursor
More information about the Python-checkins
mailing list