Skip to content

Commit

Permalink
gh-95273: Improve sqlite3 class descriptions (GH-95379)
Browse files Browse the repository at this point in the history
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e003b64)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
  • Loading branch information
miss-islington and Erlend Egeberg Aasland committed Jul 29, 2022
1 parent 2278dc7 commit a41b51d
Showing 1 changed file with 34 additions and 8 deletions.
42 changes: 34 additions & 8 deletions Doc/library/sqlite3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -380,6 +380,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
Expand Down Expand Up @@ -761,6 +771,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.
Expand Down Expand Up @@ -926,13 +952,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

Expand Down Expand Up @@ -1355,8 +1379,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`
Expand Down

0 comments on commit a41b51d

Please sign in to comment.