gh-95273: Move sqlite3 executemany examples from reference to tutorial (

GH-95351) (cherry picked from commit f0bf795) Co-authored-by: Erlend Egeberg Aasland <[email protected]>
python · Jul 29, 2022 · f59a5c5 · f59a5c5
1 parent 5632c98
commit f59a5c5
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 54 deletions.
diff --git a/Doc/includes/sqlite3/executemany_1.py b/Doc/includes/sqlite3/executemany_1.py
diff --git a/Doc/includes/sqlite3/executemany_2.py b/Doc/includes/sqlite3/executemany_2.py
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -67,15 +67,28 @@ 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)
+
+Then, 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)
+   ...     print(row)
 
    ('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
    ('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
@@ -781,12 +794,14 @@ 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
+      Example::
 
+          data = [
+              ("row1",),
+              ("row2",),
+          ]
+          # cur is an sqlite3.Cursor object
+          cur.executemany("insert into t values(?)", data)
 
    .. method:: executescript(sql_script, /)