Skip to content

Commit 2037ebf

Browse files
Docs: use parameter list for sqlite3.Cursor.execute* (#101782)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent e1aaded commit 2037ebf

File tree

1 file changed

+33
-12
lines changed

1 file changed

+33
-12
lines changed

Doc/library/sqlite3.rst

+33-12
Original file line numberDiff line numberDiff line change
@@ -1418,15 +1418,22 @@ Cursor objects
14181418

14191419
.. method:: execute(sql, parameters=(), /)
14201420

1421-
Execute SQL statement *sql*.
1422-
Bind values to the statement using :ref:`placeholders
1423-
<sqlite3-placeholders>` that map to the :term:`sequence` or :class:`dict`
1424-
*parameters*.
1421+
Execute SQL a single SQL statement,
1422+
optionally binding Python values using
1423+
:ref:`placeholders <sqlite3-placeholders>`.
14251424

1426-
:meth:`execute` will only execute a single SQL statement. If you try to execute
1427-
more than one statement with it, it will raise a :exc:`ProgrammingError`. Use
1428-
:meth:`executescript` if you want to execute multiple SQL statements with one
1429-
call.
1425+
:param str sql:
1426+
A single SQL statement.
1427+
1428+
:param parameters:
1429+
Python values to bind to placeholders in *sql*.
1430+
A :class:`!dict` if named placeholders are used.
1431+
A :term:`!sequence` if unnamed placeholders are used.
1432+
See :ref:`sqlite3-placeholders`.
1433+
:type parameters: :class:`dict` | :term:`sequence`
1434+
1435+
:raises ProgrammingError:
1436+
If *sql* contains more than one SQL statement.
14301437

14311438
If :attr:`~Connection.autocommit` is
14321439
:data:`LEGACY_TRANSACTION_CONTROL`,
@@ -1435,15 +1442,29 @@ Cursor objects
14351442
and there is no open transaction,
14361443
a transaction is implicitly opened before executing *sql*.
14371444

1445+
Use :meth:`executescript` to execute multiple SQL statements.
14381446

14391447
.. method:: executemany(sql, parameters, /)
14401448

1441-
Execute :ref:`parameterized <sqlite3-placeholders>` SQL statement *sql*
1442-
against all parameter sequences or mappings found in the sequence
1443-
*parameters*. It is also possible to use an
1444-
:term:`iterator` yielding parameters instead of a sequence.
1449+
For every item in *parameters*,
1450+
repeatedly execute the :ref:`parameterized <sqlite3-placeholders>`
1451+
SQL statement *sql*.
1452+
14451453
Uses the same implicit transaction handling as :meth:`~Cursor.execute`.
14461454

1455+
:param str sql:
1456+
A single SQL :abbr:`DML (Data Manipulation Language)` statement.
1457+
1458+
:param parameters:
1459+
An :term:`!iterable` of parameters to bind with
1460+
the placeholders in *sql*.
1461+
See :ref:`sqlite3-placeholders`.
1462+
:type parameters: :term:`iterable`
1463+
1464+
:raises ProgrammingError:
1465+
If *sql* contains more than one SQL statement,
1466+
or is not a DML statment.
1467+
14471468
Example:
14481469

14491470
.. testcode:: sqlite3.cursor

0 commit comments

Comments
 (0)