[Python-checkins] gh-95273: Improve sqlite3 class descriptions (GH-95379)
miss-islington
webhook-mailer at python.org
Fri Jul 29 06:02:21 EDT 2022
https://github.com/python/cpython/commit/c26470f0cc900dccf2a7ce4a915fc36596cdf289
commit: c26470f0cc900dccf2a7ce4a915fc36596cdf289
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-07-29T03:02:16-07:00
summary:
gh-95273: Improve sqlite3 class descriptions (GH-95379)
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>
(cherry picked from commit e003b64f40fa28954ec967024fa811adff6cffe7)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at innova.no>
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index d8ecc24d034b5..720330fe3f1eb 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -416,6 +416,16 @@ Connection Objects
.. class:: Connection
+ Each open SQLite database is represented by a ``Connection`` object,
+ which is created using :func:`sqlite3.connect`.
+ Their main purpose is creating :class:`Cursor` objects,
+ and :ref:`sqlite3-controlling-transactions`.
+
+ .. seealso::
+
+ * :ref:`sqlite3-connection-shortcuts`
+ * :ref:`sqlite3-connection-context-manager`
+
An SQLite database connection has the following attributes and methods:
.. attribute:: isolation_level
@@ -960,6 +970,22 @@ Connection Objects
Cursor Objects
--------------
+ A ``Cursor`` object represents a `database cursor`_
+ which is used to execute SQL statements,
+ and manage the context of a fetch operation.
+ Cursors are created using :meth:`Connection.cursor`,
+ or by using any of the :ref:`connection shortcut methods
+ <sqlite3-connection-shortcuts>`.
+
+ Cursor objects are :term:`iterators <iterator>`,
+ meaning that if you :meth:`~Cursor.execute` a ``SELECT`` query,
+ you can simply iterate over the cursor to fetch the resulting rows::
+
+ for row in cur.execute("select * from data"):
+ print(row)
+
+ .. _database cursor: https://en.wikipedia.org/wiki/Cursor_(databases)
+
.. class:: Cursor
A :class:`Cursor` instance has the following attributes and methods.
@@ -1125,13 +1151,11 @@ Row Objects
A :class:`Row` instance serves as a highly optimized
:attr:`~Connection.row_factory` for :class:`Connection` objects.
- It tries to mimic a tuple in most of its features.
+ It tries to mimic a :class:`tuple` in most of its features,
+ and supports iteration, :func:`repr`, equality testing, :func:`len`,
+ and :term:`mapping` access by column name and index.
- It supports mapping access by column name and index, iteration,
- representation, equality testing and :func:`len`.
-
- If two :class:`Row` objects have exactly the same columns and their
- members are equal, they compare equal.
+ Two row objects compare equal if have equal columns and equal members.
.. method:: keys
@@ -1623,8 +1647,10 @@ Using :mod:`sqlite3` efficiently
--------------------------------
-Using shortcut methods
-^^^^^^^^^^^^^^^^^^^^^^
+.. _sqlite3-connection-shortcuts:
+
+Using connection shortcut methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using the :meth:`~Connection.execute`,
:meth:`~Connection.executemany`, and :meth:`~Connection.executescript`
More information about the Python-checkins
mailing list