Skip to content

Commit a41b51d

Browse files
miss-islingtonErlend Egeberg Aasland
and
Erlend Egeberg Aasland
authored
gh-95273: Improve sqlite3 class descriptions (GH-95379)
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit e003b64) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
1 parent 2278dc7 commit a41b51d

File tree

1 file changed

+34
-8
lines changed

1 file changed

+34
-8
lines changed

Doc/library/sqlite3.rst

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,16 @@ Connection Objects
380380

381381
.. class:: Connection
382382

383+
Each open SQLite database is represented by a ``Connection`` object,
384+
which is created using :func:`sqlite3.connect`.
385+
Their main purpose is creating :class:`Cursor` objects,
386+
and :ref:`sqlite3-controlling-transactions`.
387+
388+
.. seealso::
389+
390+
* :ref:`sqlite3-connection-shortcuts`
391+
* :ref:`sqlite3-connection-context-manager`
392+
383393
An SQLite database connection has the following attributes and methods:
384394

385395
.. attribute:: isolation_level
@@ -761,6 +771,22 @@ Connection Objects
761771
Cursor Objects
762772
--------------
763773

774+
A ``Cursor`` object represents a `database cursor`_
775+
which is used to execute SQL statements,
776+
and manage the context of a fetch operation.
777+
Cursors are created using :meth:`Connection.cursor`,
778+
or by using any of the :ref:`connection shortcut methods
779+
<sqlite3-connection-shortcuts>`.
780+
781+
Cursor objects are :term:`iterators <iterator>`,
782+
meaning that if you :meth:`~Cursor.execute` a ``SELECT`` query,
783+
you can simply iterate over the cursor to fetch the resulting rows::
784+
785+
for row in cur.execute("select * from data"):
786+
print(row)
787+
788+
.. _database cursor: https://en.wikipedia.org/wiki/Cursor_(databases)
789+
764790
.. class:: Cursor
765791

766792
A :class:`Cursor` instance has the following attributes and methods.
@@ -926,13 +952,11 @@ Row Objects
926952

927953
A :class:`Row` instance serves as a highly optimized
928954
:attr:`~Connection.row_factory` for :class:`Connection` objects.
929-
It tries to mimic a tuple in most of its features.
955+
It tries to mimic a :class:`tuple` in most of its features,
956+
and supports iteration, :func:`repr`, equality testing, :func:`len`,
957+
and :term:`mapping` access by column name and index.
930958

931-
It supports mapping access by column name and index, iteration,
932-
representation, equality testing and :func:`len`.
933-
934-
If two :class:`Row` objects have exactly the same columns and their
935-
members are equal, they compare equal.
959+
Two row objects compare equal if have equal columns and equal members.
936960

937961
.. method:: keys
938962

@@ -1355,8 +1379,10 @@ Using :mod:`sqlite3` efficiently
13551379
--------------------------------
13561380

13571381

1358-
Using shortcut methods
1359-
^^^^^^^^^^^^^^^^^^^^^^
1382+
.. _sqlite3-connection-shortcuts:
1383+
1384+
Using connection shortcut methods
1385+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13601386

13611387
Using the :meth:`~Connection.execute`,
13621388
:meth:`~Connection.executemany`, and :meth:`~Connection.executescript`

0 commit comments

Comments
 (0)