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

* 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@gmail.com>

* Address review: adjust wording

* Update Doc/library/sqlite3.rst

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

* Update Lib/sqlite3/__init__.py

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

* Update Doc/library/sqlite3.rst

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

* Update Doc/library/sqlite3.rst

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

* Update Lib/sqlite3/__init__.py

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

* Update Doc/library/sqlite3.rst

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

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

* Minor adjustment

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Erlend Egeberg Aasland 2021-11-15 23:22:42 +01:00 committed by GitHub
parent ec382fac0d
commit 6c5a312fb6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 24 additions and 22 deletions

View File

@ -21,16 +21,17 @@ 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`, and
requires SQLite 3.7.15 or newer.
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()
@ -49,16 +50,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::
@ -73,27 +75,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

View File

@ -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()