gh-95273: Improve sqlite3 class descriptions (GH-95379)

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e003b64f40)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
This commit is contained in:
Miss Islington (bot) 2022-07-29 03:00:29 -07:00 committed by GitHub
parent 2278dc7442
commit a41b51d2ea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 8 deletions

View File

@ -380,6 +380,16 @@ Connection Objects
.. class:: Connection .. 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: An SQLite database connection has the following attributes and methods:
.. attribute:: isolation_level .. attribute:: isolation_level
@ -761,6 +771,22 @@ Connection Objects
Cursor 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 .. class:: Cursor
A :class:`Cursor` instance has the following attributes and methods. A :class:`Cursor` instance has the following attributes and methods.
@ -926,13 +952,11 @@ Row Objects
A :class:`Row` instance serves as a highly optimized A :class:`Row` instance serves as a highly optimized
:attr:`~Connection.row_factory` for :class:`Connection` objects. :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, Two row objects compare equal if have equal columns and equal members.
representation, equality testing and :func:`len`.
If two :class:`Row` objects have exactly the same columns and their
members are equal, they compare equal.
.. method:: keys .. method:: keys
@ -1355,8 +1379,10 @@ Using :mod:`sqlite3` efficiently
-------------------------------- --------------------------------
Using shortcut methods .. _sqlite3-connection-shortcuts:
^^^^^^^^^^^^^^^^^^^^^^
Using connection shortcut methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using the :meth:`~Connection.execute`, Using the :meth:`~Connection.execute`,
:meth:`~Connection.executemany`, and :meth:`~Connection.executescript` :meth:`~Connection.executemany`, and :meth:`~Connection.executescript`