Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Docs: use parameter list for sqlite3.Cursor.execute*
  • Loading branch information
erlend-aasland committed Feb 10, 2023
commit 84aa8650870d2350d93b759d4c9e3845e8ac3566
45 changes: 33 additions & 12 deletions Doc/library/sqlite3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1418,15 +1418,22 @@ 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 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`,
Expand All @@ -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 <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 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
Expand Down