From 4e72a1ab3d4aaa1783b42e7261c92cd2c2c970f4 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 28 Jul 2022 14:33:18 +0200 Subject: [PATCH 1/4] gh-95273: Improve sqlite3 class descriptions --- Doc/library/sqlite3.rst | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index d493f5fd95631d..bd4a79a15792d1 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -413,6 +413,17 @@ Connection Objects .. class:: Connection + Each open SQLite database is represented by a connection object. + A connection object is created with :func:`sqlite3.connect`. + The main purpose of connection objects is creating + :class:`cursors 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 +968,20 @@ 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 with :meth:`Connection.cursor`, + or by using any of the :ref:`connection shortcut methods + `. + + Cursors objects are :term:`iterators `, + meaning that if you :meth:`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) + .. class:: Cursor A :class:`Cursor` instance has the following attributes and methods. @@ -1111,15 +1136,13 @@ Row Objects .. class:: Row - A :class:`Row` instance serves as a highly optimized + A :class:`Row` instance that 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 supports mapping access by column name and index, iteration, + It tries to mimic a :class:`tuple` in most of its features, + and supports :term:`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 are equal if they have equal columns and equal members. .. method:: keys @@ -1618,8 +1641,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 From 7407e05f1c6a074b678c78167b908633fe7e8965 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 29 Jul 2022 09:59:40 +0200 Subject: [PATCH 2/4] Address review --- Doc/library/sqlite3.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bd4a79a15792d1..058def35fe89f4 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -413,10 +413,9 @@ Connection Objects .. class:: Connection - Each open SQLite database is represented by a connection object. - A connection object is created with :func:`sqlite3.connect`. - The main purpose of connection objects is creating - :class:`cursors objects `, + 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:: @@ -968,7 +967,7 @@ Connection Objects Cursor Objects -------------- - A cursor object represents a database cursor, + 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 with :meth:`Connection.cursor`, @@ -976,12 +975,14 @@ Cursor Objects `. Cursors objects are :term:`iterators `, - meaning that if you :meth:`execute` a ``SELECT`` query, + 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. @@ -1136,13 +1137,13 @@ Row Objects .. class:: Row - A :class:`Row` instance that serves as a highly optimized + A :class:`Row` instance serves as a highly optimized :attr:`~Connection.row_factory` for :class:`Connection` objects. It tries to mimic a :class:`tuple` in most of its features, - and supports :term:`mapping` access by column name and index, iteration, - representation, equality testing and :func:`len`. + and supports iteration, :func:`repr`, equality testing, :func:`len`, + and :term:`mapping` access by column name and index. - Two row objects are equal if they have equal columns and equal members. + Two row objects compare equal if have equal columns and equal members. .. method:: keys From dd332be472e989e65a9f22b3cd55f1fe94da8047 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 29 Jul 2022 11:41:06 +0200 Subject: [PATCH 3/4] Update Doc/library/sqlite3.rst --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 058def35fe89f4..ff35974fa9f2c6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -970,7 +970,7 @@ 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 with :meth:`Connection.cursor`, + Cursors are created using :meth:`Connection.cursor`, or by using any of the :ref:`connection shortcut methods `. From 9d083233044f38a1d71296bf138b85aa6119d520 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 29 Jul 2022 11:41:43 +0200 Subject: [PATCH 4/4] Update Doc/library/sqlite3.rst --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index ff35974fa9f2c6..0920037f84060c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -974,7 +974,7 @@ Cursor Objects or by using any of the :ref:`connection shortcut methods `. - Cursors objects are :term:`iterators `, + 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::