[Python-checkins] [3.11] gh-100021: Document that sqlite3's executemany() discards resulting rows (#103939) (#103966)

[erlend-aasland]

https://github.com/python/cpython/commit/b3faf8ceec872a912442b88cf4322b224a48e170
commit: b3faf8ceec872a912442b88cf4322b224a48e170
branch: 3.11
author: Erlend E. Aasland <erlend.aasland at protonmail.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-04-28T08:05:14Z
summary:

[3.11] gh-100021: Document that sqlite3's executemany() discards resulting rows (#103939) (#103966)

files:
M Doc/library/sqlite3.rst

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 165bac4c0f70..4dbbfe21ff66 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1363,12 +1363,12 @@ Cursor objects
 
       For every item in *parameters*,
       repeatedly execute the :ref:`parameterized <sqlite3-placeholders>`
-      SQL statement *sql*.
+      :abbr:`DML (Data Manipulation Language)` 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.
+         A single SQL DML statement.
 
       :param parameters:
          An :term:`!iterable` of parameters to bind with
@@ -1391,6 +1391,13 @@ Cursor objects
          # cur is an sqlite3.Cursor object
          cur.executemany("INSERT INTO data VALUES(?)", rows)
 
+      .. note::
+
+         Any resulting rows are discarded,
+         including DML statements with `RETURNING clauses`_.
+
+      .. _RETURNING clauses: https://www.sqlite.org/lang_returning.html
+
    .. method:: executescript(sql_script, /)
 
       Execute the SQL statements in *sql_script*.