Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: use parameter list for sqlite3.Cursor.execute* #101782

Merged
Changes from 4 commits
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
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 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`
AlexWaygood marked this conversation as resolved.
Show resolved Hide resolved

:raises ProgrammingError:
If *sql* contains more than one SQL statement.
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved

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 str sql:
A single SQL :abbr:`DML (Data Manipulation Language)` statement.

:param parameters:
An :term:`iterable` or :term:`iterator` of parameters
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved
to bind with the placeholders in *sql*.
See :ref:`sqlite3-placeholders`.
:type parameters: :term:`iterable` | :term:`iterator`
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved

:raises ProgrammingError:
If *sql* contains more than one SQL statement,
or is not a DML statment.

Example:

.. testcode:: sqlite3.cursor
Expand Down