Skip to content

Commit a565cd5

Browse files
[3.10] Docs: use parameter list for sqlite3.Cursor.execute* (GH-101782) (#101808)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> (cherry picked from commit 2037ebf)
1 parent 6d8ef96 commit a565cd5

File tree

1 file changed

+35
-12
lines changed

1 file changed

+35
-12
lines changed

Doc/library/sqlite3.rst

+35-12
Original file line numberDiff line numberDiff line change
@@ -1044,30 +1044,53 @@ Cursor objects
10441044

10451045
.. method:: execute(sql, parameters=(), /)
10461046

1047-
Execute SQL statement *sql*.
1048-
Bind values to the statement using :ref:`placeholders
1049-
<sqlite3-placeholders>` that map to the :term:`sequence` or :class:`dict`
1050-
*parameters*.
1047+
Execute SQL a single SQL statement,
1048+
optionally binding Python values using
1049+
:ref:`placeholders <sqlite3-placeholders>`.
10511050

1052-
:meth:`execute` will only execute a single SQL statement. If you try to execute
1053-
more than one statement with it, it will raise a :exc:`Warning`. Use
1054-
:meth:`executescript` if you want to execute multiple SQL statements with one
1055-
call.
1051+
:param str sql:
1052+
A single SQL statement.
1053+
1054+
:param parameters:
1055+
Python values to bind to placeholders in *sql*.
1056+
A :class:`!dict` if named placeholders are used.
1057+
A :term:`!sequence` if unnamed placeholders are used.
1058+
See :ref:`sqlite3-placeholders`.
1059+
:type parameters: :class:`dict` | :term:`sequence`
1060+
1061+
:raises Warning:
1062+
If *sql* contains more than one SQL statement.
10561063

10571064
If :attr:`~Connection.isolation_level` is not ``None``,
10581065
*sql* is an ``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statement,
10591066
and there is no open transaction,
10601067
a transaction is implicitly opened before executing *sql*.
10611068

1069+
Use :meth:`executescript` to execute multiple SQL statements.
10621070

10631071
.. method:: executemany(sql, parameters, /)
10641072

1065-
Execute :ref:`parameterized <sqlite3-placeholders>` SQL statement *sql*
1066-
against all parameter sequences or mappings found in the sequence
1067-
*parameters*. It is also possible to use an
1068-
:term:`iterator` yielding parameters instead of a sequence.
1073+
For every item in *parameters*,
1074+
repeatedly execute the :ref:`parameterized <sqlite3-placeholders>`
1075+
SQL statement *sql*.
1076+
10691077
Uses the same implicit transaction handling as :meth:`~Cursor.execute`.
10701078

1079+
:param str sql:
1080+
A single SQL :abbr:`DML (Data Manipulation Language)` statement.
1081+
1082+
:param parameters:
1083+
An :term:`!iterable` of parameters to bind with
1084+
the placeholders in *sql*.
1085+
See :ref:`sqlite3-placeholders`.
1086+
:type parameters: :term:`iterable`
1087+
1088+
:raises ProgrammingError:
1089+
If *sql* is not a DML statment.
1090+
1091+
:raises Warning:
1092+
If *sql* contains more than one SQL statement.
1093+
10711094
Example:
10721095

10731096
.. testcode:: sqlite3.cursor

0 commit comments

Comments
 (0)