gh-95271: Improve sqlite3 tutorial wording

Doc/library/sqlite3.rst

@@ -52,51 +52,54 @@ This document includes four main sections:
 Tutorial
 --------
 
-To use the module, start by creating a :class:`Connection` object that
-represents the database.  Here the data will be stored in the
-:file:`example.db` file::
+In this tutorial you will learn the basics of the :mod:`!sqlite3` API
+by creating an on-disk database :file:`example.db`,
+and executing SQL queries against it.
+A fundamental understanding of database concepts,
+like transactions and cursors, is assumed.
+
+Start by using the :func:`sqlite3.connect` function to
+open a database :class:`Connection` to :file:`example.db`;
+SQLite will implicitly create the database file :file:`example`
+in the current working directory, if it does not exist.
+The returned :class:`!Connection` object represents our
+connection to the on-disk SQLite database::
 
    import sqlite3
    con = sqlite3.connect('example.db')
 
-The special path name ``:memory:`` can be provided to create a temporary
-database in RAM.
-
-Once a :class:`Connection` has been established, create a :class:`Cursor` object
-and call its :meth:`~Cursor.execute` method to perform SQL commands::
+Now, create a :class:`Cursor` object using :meth:`~Connection.cursor`.
+Call its :meth:`~Cursor.execute` method to perform SQL queries::
 
    cur = con.cursor()
 
-   # Create table
+   # Create table, then insert a row of data.
    cur.execute('''CREATE TABLE stocks
                   (date text, trans text, symbol text, qty real, price real)''')
-
-   # Insert a row of data
    cur.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
 
-   # Save (commit) the changes
-   con.commit()
+The ``INSERT`` statement implicitly opens a transaction
+that needs to be committed before changes are saved in the database.
+For more details, see the :ref:`sqlite3-controlling-transactions` how-to.
+Use the connection object to :meth:`~Connection.commit` the transaction::
 
-   # We can also close the connection if we are done with it.
-   # Just be sure any changes have been committed or they will be lost.
-   con.close()
+   con.commit()  # Save the changes.
 
-The saved data is persistent: it can be reloaded in a subsequent session even
-after restarting the Python interpreter::
-
-   import sqlite3
-   con = sqlite3.connect('example.db')
-   cur = con.cursor()
-
-At this point, our database only contains one row::
+Verify that data has been committed and written to disk:
+close the connection, open a new connection,
+create a new cursor,
+then use a ``SELECT`` query to read from the database::
 
+   >>> con.close()
+   >>> con = sqlite3.connect('example.db')
+   >>> cur = con.cursor()
    >>> 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,
+Now, insert three more rows of data,
 using :meth:`~Cursor.executemany`::
 
    >>> data = [
@@ -112,7 +115,7 @@ to bind Python values to SQL statements,
 to avoid `SQL injection attacks`_.
 See the :ref:`placeholders how-to <sqlite3-placeholders>` for more details.
 
-Then, retrieve the data by iterating over the result of a ``SELECT`` statement::
+Now, retrieve the rows by iterating over the result of a ``SELECT`` query::
 
    >>> for row in cur.execute('SELECT * FROM stocks ORDER BY price'):
    ...     print(row)
@@ -122,6 +125,7 @@ Then, retrieve the data by iterating over the result of a ``SELECT`` statement::
    ('2006-04-06', 'SELL', 'IBM', 500, 53.0)
    ('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)
 
+Each row is a five-item :class:`!tuple`.
 You've now created an SQLite database using the :mod:`!sqlite3` module.
 
 .. _SQL injection attacks: https://en.wikipedia.org/wiki/SQL_injection