[Python-checkins] bpo-45677: Reword first section of `sqlite3` docs (GH-29326) (GH-29567)

[willingc]

https://github.com/python/cpython/commit/a40d066e8ef548b52eca2b0e27c219ddd7e11592
commit: a40d066e8ef548b52eca2b0e27c219ddd7e11592
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: willingc <carolcode at willingconsulting.com>
date: 2021-11-15T15:32:31-08:00
summary:

bpo-45677: Reword first section of `sqlite3` docs (GH-29326) (GH-29567)

* bpo-45677: Avoid addressing the reader as 'you' in sqlite3 docs

* Adjust wording

* Adjust wording again

* Typo

* Update Doc/library/sqlite3.rst

Co-authored-by: Jacob Walls <jacobtylerwalls at gmail.com>

* Address review: adjust wording

* Update Doc/library/sqlite3.rst

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Update Lib/sqlite3/__init__.py

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Update Doc/library/sqlite3.rst

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Update Doc/library/sqlite3.rst

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Update Lib/sqlite3/__init__.py

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Update Doc/library/sqlite3.rst

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

* Apply Alex' suggestion, and apply 80 char limit to PR

* Minor adjustment

Co-authored-by: Jacob Walls <jacobtylerwalls at gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
(cherry picked from commit 6c5a312fb6d92e879bf4c570b94e18bb9ffe5970)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at innova.no>

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at innova.no>

files:
M Doc/library/sqlite3.rst
M Lib/sqlite3/__init__.py

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index b24a2f0985489..3f4f8536c1c6b 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -20,16 +20,17 @@ PostgreSQL or Oracle.
 The sqlite3 module was written by Gerhard Häring.  It provides a SQL interface
 compliant with the DB-API 2.0 specification described by :pep:`249`.
 
-To use the module, you must first create a :class:`Connection` object that
+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::
 
    import sqlite3
    con = sqlite3.connect('example.db')
 
-You can also supply the special name ``:memory:`` to create a database in RAM.
+The special path name ``:memory:`` can be provided to create a temporary
+database in RAM.
 
-Once you have a :class:`Connection`, you can create a :class:`Cursor`  object
+Once a :class:`Connection` has been established, create a :class:`Cursor` object
 and call its :meth:`~Cursor.execute` method to perform SQL commands::
 
    cur = con.cursor()
@@ -48,16 +49,17 @@ and call its :meth:`~Cursor.execute` method to perform SQL commands::
    # Just be sure any changes have been committed or they will be lost.
    con.close()
 
-The data you've saved is persistent and is available in subsequent sessions::
+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()
 
-To retrieve data after executing a SELECT statement, you can 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.
+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.
 
 This example uses the iterator form::
 
@@ -72,27 +74,27 @@ This example uses the iterator form::
 
 .. _sqlite3-placeholders:
 
-Usually your SQL operations will need to use values from Python variables.  You
-shouldn't assemble your query using Python's string operations because doing so
-is insecure; it makes your program vulnerable to an SQL injection attack
-(see the `xkcd webcomic <https://xkcd.com/327/>`_ for a humorous example of
-what can go wrong)::
+SQL operations usually need to use values from Python variables. However,
+beware of using Python's string operations to assemble queries, as they
+are vulnerable to SQL injection attacks (see the `xkcd webcomic
+<https://xkcd.com/327/>`_ for a humorous example of what can go wrong)::
 
    # Never do this -- insecure!
    symbol = 'RHAT'
    cur.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)
 
-Instead, use the DB-API's parameter substitution. Put a placeholder wherever
-you want to use a value, and then provide a tuple of values as the second
-argument to the cursor's :meth:`~Cursor.execute` method. An SQL statement may
+Instead, use the DB-API's parameter substitution. To insert a variable into a
+query string, use a placeholder in the string, and substitute the actual values
+into the query by providing them as a :class:`tuple` of values to the second
+argument of the cursor's :meth:`~Cursor.execute` method. An SQL statement may
 use one of two kinds of placeholders: question marks (qmark style) or named
 placeholders (named style). For the qmark style, ``parameters`` must be a
 :term:`sequence <sequence>`. For the named style, it can be either a
 :term:`sequence <sequence>` or :class:`dict` instance. The length of the
 :term:`sequence <sequence>` must match the number of placeholders, or a
 :exc:`ProgrammingError` is raised. If a :class:`dict` is given, it must contain
-keys for all named parameters. Any extra items are ignored. Here's an example
-of both styles:
+keys for all named parameters. Any extra items are ignored. Here's an example of
+both styles:
 
 .. literalinclude:: ../includes/sqlite3/execute_1.py
 
diff --git a/Lib/sqlite3/__init__.py b/Lib/sqlite3/__init__.py
index efdb7f2ba20f1..1e717450c29bf 100644
--- a/Lib/sqlite3/__init__.py
+++ b/Lib/sqlite3/__init__.py
@@ -24,18 +24,18 @@
 The sqlite3 extension module provides a DB-API 2.0 (PEP 249) compilant
 interface to the SQLite library, and requires SQLite 3.7.15 or newer.
 
-To use the module, you must first create a database Connection object:
+To use the module, start by creating a database Connection object:
 
     import sqlite3
     cx = sqlite3.connect("test.db")  # test.db will be created or opened
 
-You can also use the special database name ":memory:" to connect to a transient
+The special path name ":memory:" can be provided to connect to a transient
 in-memory database:
 
     cx = sqlite3.connect(":memory:")  # connect to a database in RAM
 
-Once you have a Connection object, you can create a Cursor object and call its
-execute() method to perform SQL queries:
+Once a connection has been established, create a Cursor object and call
+its execute() method to perform SQL queries:
 
     cu = cx.cursor()