From 6a5cb6105fac60e6904827f0eed66c11744bee1d Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend.aasland@protonmail.com>
Date: Thu, 28 Jul 2022 00:41:00 +0200
Subject: [PATCH] gh-95273: Move sqlite3 executemany examples from reference to
 tutorial

---
 Doc/includes/sqlite3/executemany_1.py | 26 ------------------------
 Doc/includes/sqlite3/executemany_2.py | 17 ----------------
 Doc/library/sqlite3.rst               | 29 +++++++++++++++++----------
 3 files changed, 18 insertions(+), 54 deletions(-)
 delete mode 100644 Doc/includes/sqlite3/executemany_1.py
 delete mode 100644 Doc/includes/sqlite3/executemany_2.py

diff --git a/Doc/includes/sqlite3/executemany_1.py b/Doc/includes/sqlite3/executemany_1.py
deleted file mode 100644
index edf6f8b7ebe61a..00000000000000
--- a/Doc/includes/sqlite3/executemany_1.py
+++ /dev/null
@@ -1,26 +0,0 @@
-import sqlite3
-
-class IterChars:
-    def __init__(self):
-        self.count = ord('a')
-
-    def __iter__(self):
-        return self
-
-    def __next__(self):
-        if self.count > ord('z'):
-            raise StopIteration
-        self.count += 1
-        return (chr(self.count - 1),) # this is a 1-tuple
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-cur.execute("create table characters(c)")
-
-theIter = IterChars()
-cur.executemany("insert into characters(c) values (?)", theIter)
-
-cur.execute("select c from characters")
-print(cur.fetchall())
-
-con.close()
diff --git a/Doc/includes/sqlite3/executemany_2.py b/Doc/includes/sqlite3/executemany_2.py
deleted file mode 100644
index 02a594c861e15b..00000000000000
--- a/Doc/includes/sqlite3/executemany_2.py
+++ /dev/null
@@ -1,17 +0,0 @@
-import sqlite3
-import string
-
-def char_generator():
-    for c in string.ascii_lowercase:
-        yield (c,)
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-cur.execute("create table characters(c)")
-
-cur.executemany("insert into characters(c) values (?)", char_generator())
-
-cur.execute("select c from characters")
-print(cur.fetchall())
-
-con.close()
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index d493f5fd95631d..c9b53adecb64f7 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -67,12 +67,25 @@ after restarting the Python interpreter::
    con = sqlite3.connect('example.db')
    cur = con.cursor()
 
-To retrieve data after executing a SELECT statement, either treat the cursor as
-an :term:`iterator`, call the cursor's :meth:`~Cursor.fetchone` method to
-retrieve a single matching row, or call :meth:`~Cursor.fetchall` to get a list
-of the matching rows.
+At this point, our database only contains one row::
 
-This example uses the iterator form::
+   >>> res = cur.execute('SELECT count(rowid) FROM stocks')
+   >>> print(res.fetchone())
+   (1,)
+
+The result is a one-item :class:`tuple`;
+one row, with one column.
+Now, let us insert three more rows of data,
+using :meth:`~Cursor.executemany`::
+
+   >>> data = [
+       ('2006-03-28', 'BUY', 'IBM', 1000, 45.0),
+       ('2006-04-05', 'BUY', 'MSFT', 1000, 72.0),
+       ('2006-04-06', 'SELL', 'IBM', 500, 53.0),
+   ]
+   >>> cur.executemany('INSERT INTO stocks VALUES(?, ?, ?, ?)', data)
+
+Now, retrieve the data by iterating over the result of a SELECT statement::
 
    >>> for row in cur.execute('SELECT * FROM stocks ORDER BY price'):
            print(row)
@@ -990,12 +1003,6 @@ Cursor Objects
       :term:`iterator` yielding parameters instead of a sequence.
       Uses the same implicit transaction handling as :meth:`~Cursor.execute`.
 
-      .. literalinclude:: ../includes/sqlite3/executemany_1.py
-
-      Here's a shorter example using a :term:`generator`:
-
-      .. literalinclude:: ../includes/sqlite3/executemany_2.py
-
 
    .. method:: executescript(sql_script, /)