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

[3.10] Docs: use parameter list for sqlite3.Cursor.execute* (GH-101782) #101808

Merged
merged 1 commit into from
Feb 10, 2023
Merged
Changes from all 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
47 changes: 35 additions & 12 deletions Doc/library/sqlite3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1044,30 +1044,53 @@ 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:`Warning`. 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 Warning:
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* is not a DML statment.

:raises Warning:
If *sql* contains more than one SQL statement.

Example:

.. testcode:: sqlite3.cursor
Expand Down