Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-95273: Improve sqlite3 class descriptions #95379

Merged
merged 4 commits into from
Jul 29, 2022
Merged

gh-95273: Improve sqlite3 class descriptions #95379

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4e72a1a
gh-95273: Improve sqlite3 class descriptions
erlend-aasland Jul 28, 2022
7407e05
Address review
erlend-aasland Jul 29, 2022
dd332be
Update Doc/library/sqlite3.rst
Jul 29, 2022
9d08323
Update Doc/library/sqlite3.rst
Jul 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 34 additions & 8 deletions Doc/library/sqlite3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,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 @@ -957,6 +967,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 @@ -1113,13 +1139,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,
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -1618,8 +1642,10 @@ Using :mod:`sqlite3` efficiently
--------------------------------


Using shortcut methods
^^^^^^^^^^^^^^^^^^^^^^
.. _sqlite3-connection-shortcuts:

Using connection shortcut methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the nonstandard :meth:`execute`, :meth:`executemany` and
:meth:`executescript` methods of the :class:`Connection` object, your code can
Expand Down