diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index d493f5fd95631d..0920037f84060c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -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 @@ -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 + `. + + Cursor objects are :term:`iterators `, + 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. @@ -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, + 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 @@ -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