From d2188bfe8a7d04d3cfd0ef7f790a966b9e664d59 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 19 Aug 2022 14:21:48 +0200 Subject: [PATCH 1/6] Merge sqlite3.Row examples --- Doc/includes/sqlite3/rowclass.py | 14 ------ Doc/library/sqlite3.rst | 73 ++++++++++---------------------- 2 files changed, 23 insertions(+), 64 deletions(-) delete mode 100644 Doc/includes/sqlite3/rowclass.py diff --git a/Doc/includes/sqlite3/rowclass.py b/Doc/includes/sqlite3/rowclass.py deleted file mode 100644 index fc60287069a854..00000000000000 --- a/Doc/includes/sqlite3/rowclass.py +++ /dev/null @@ -1,14 +0,0 @@ -import sqlite3 - -con = sqlite3.connect(":memory:") -con.row_factory = sqlite3.Row - -cur = con.cursor() -cur.execute("select 'John' as name, 42 as age") -for row in cur: - assert row[0] == row["name"] - assert row["name"] == row["nAmE"] - assert row[1] == row["age"] - assert row[1] == row["AgE"] - -con.close() diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6413d8859180da..863116fa4b448b 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1262,7 +1262,7 @@ Row objects .. class:: Row - A :class:`Row` instance 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 iteration, :func:`repr`, equality testing, :func:`len`, @@ -1270,6 +1270,10 @@ Row objects Two row objects compare equal if have equal columns and equal members. + .. seealso:: + + :ref:`sqlite3-columns-by-name` + .. method:: keys Return a :class:`list` of column names as :class:`strings `. @@ -1279,46 +1283,6 @@ Row objects .. versionchanged:: 3.5 Added support of slicing. -Let's assume we initialize a table as in the example given above:: - - con = sqlite3.connect(":memory:") - cur = con.cursor() - cur.execute('''create table stocks - (date text, trans text, symbol text, - qty real, price real)''') - cur.execute("""insert into stocks - values ('2006-01-05','BUY','RHAT',100,35.14)""") - con.commit() - cur.close() - -Now we plug :class:`Row` in:: - - >>> con.row_factory = sqlite3.Row - >>> cur = con.cursor() - >>> cur.execute('select * from stocks') - - >>> r = cur.fetchone() - >>> type(r) - - >>> tuple(r) - ('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14) - >>> len(r) - 5 - >>> r[2] - 'RHAT' - >>> r.keys() - ['date', 'trans', 'symbol', 'qty', 'price'] - >>> r['qty'] - 100.0 - >>> for member in r: - ... print(member) - ... - 2006-01-05 - BUY - RHAT - 100.0 - 35.14 - .. _sqlite3-blob-objects: @@ -1768,16 +1732,25 @@ directly using only a single call on the :class:`Connection` object. .. _sqlite3-columns-by-name: -Accessing columns by name instead of by index -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One useful feature of the :mod:`!sqlite3` module is the built-in -:class:`sqlite3.Row` class designed to be used as a row factory. - -Rows wrapped with this class can be accessed both by index (like tuples) and -case-insensitively by name: +How to access columns by name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../includes/sqlite3/rowclass.py +Use the :class:`~sqlite3.Row` class as a :attr:`~Connection.row_factory` +in order to access columns either by index or case-insensitively by name:: + + >>> con.row_factory = sqlite3.Row # con is an sqlite3.Connection object. + >>> res = con.execute("select 'Tellus' as name, 6378 as radius") + >>> row = res.fetchone() + >>> row.keys() + ['name', 'radius'] + >>> row[0] + 'Tellus' + >>> row["name"] + 'Tellus' + >>> row["RADIUS"] + 6378 + >>> "Tellus" in row + True .. _sqlite3-connection-context-manager: From e1540d53f2c2e09c66137dc1a7d619d13a33733a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 19 Aug 2022 14:31:15 +0200 Subject: [PATCH 2/6] Remove the how-to and incorporate it into the reference --- Doc/library/sqlite3.rst | 50 ++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 863116fa4b448b..1ebac55692511f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -207,7 +207,6 @@ inserted data and retrieved values from it in multiple ways. * :ref:`sqlite3-placeholders` * :ref:`sqlite3-adapters` * :ref:`sqlite3-converters` - * :ref:`sqlite3-columns-by-name` * :ref:`sqlite3-connection-context-manager` * :ref:`sqlite3-explanation` for in-depth background on transaction control. @@ -1255,6 +1254,12 @@ Cursor objects >>> cur.connection == con True +.. The sqlite3.Row example used to be a how-to. It has now been incorporated + into the Row reference. We keep the anchor here in order not to break + existing links. + +.. _sqlite3-columns-by-name: + .. _sqlite3-row-objects: Row objects @@ -1270,10 +1275,6 @@ Row objects Two row objects compare equal if have equal columns and equal members. - .. seealso:: - - :ref:`sqlite3-columns-by-name` - .. method:: keys Return a :class:`list` of column names as :class:`strings `. @@ -1283,6 +1284,22 @@ Row objects .. versionchanged:: 3.5 Added support of slicing. + Example:: + + >>> con.row_factory = sqlite3.Row # con is an sqlite3.Connection object. + >>> res = con.execute("select 'Tellus' as name, 6378 as radius") + >>> row = res.fetchone() + >>> row.keys() + ['name', 'radius'] + >>> row[0] + 'Tellus' + >>> row["name"] + 'Tellus' + >>> row["RADIUS"] + 6378 + >>> "Tellus" in row + True + .. _sqlite3-blob-objects: @@ -1730,29 +1747,6 @@ directly using only a single call on the :class:`Connection` object. .. literalinclude:: ../includes/sqlite3/shortcut_methods.py -.. _sqlite3-columns-by-name: - -How to access columns by name -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use the :class:`~sqlite3.Row` class as a :attr:`~Connection.row_factory` -in order to access columns either by index or case-insensitively by name:: - - >>> con.row_factory = sqlite3.Row # con is an sqlite3.Connection object. - >>> res = con.execute("select 'Tellus' as name, 6378 as radius") - >>> row = res.fetchone() - >>> row.keys() - ['name', 'radius'] - >>> row[0] - 'Tellus' - >>> row["name"] - 'Tellus' - >>> row["RADIUS"] - 6378 - >>> "Tellus" in row - True - - .. _sqlite3-connection-context-manager: Using the connection as a context manager From 74c3a203c30fd56979e765b8affa1de5be1153b2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 20 Aug 2022 08:02:59 +0200 Subject: [PATCH 3/6] Address review --- Doc/library/sqlite3.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 1ebac55692511f..61834fabfb89a3 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1269,8 +1269,7 @@ Row objects 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 iteration, :func:`repr`, equality testing, :func:`len`, + It supports iteration, equality testing, :func:`len`, and :term:`mapping` access by column name and index. Two row objects compare equal if have equal columns and equal members. @@ -1286,19 +1285,16 @@ Row objects Example:: - >>> con.row_factory = sqlite3.Row # con is an sqlite3.Connection object. - >>> res = con.execute("select 'Tellus' as name, 6378 as radius") + >>> con = sqlite3.connect(":memory:") + >>> con.row_factory = sqlite3.Row + >>> res = con.execute("select 'Earth' as name, 6378 as radius") >>> row = res.fetchone() >>> row.keys() ['name', 'radius'] - >>> row[0] - 'Tellus' - >>> row["name"] - 'Tellus' + >>> row[0], row["name"] # Access by index and name. + ('Earth', 'Earth') >>> row["RADIUS"] 6378 - >>> "Tellus" in row - True .. _sqlite3-blob-objects: From 48dc7d9c3f6c64690d85173f0957f456caab5897 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 20 Aug 2022 09:09:38 +0200 Subject: [PATCH 4/6] Update Doc/library/sqlite3.rst Co-authored-by: Ezio Melotti --- 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 61834fabfb89a3..4e7d6af0a5e173 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1293,7 +1293,7 @@ Row objects ['name', 'radius'] >>> row[0], row["name"] # Access by index and name. ('Earth', 'Earth') - >>> row["RADIUS"] + >>> row["RADIUS"] # Column names are case-insensitive. 6378 From f83999f0b834c9d4e5733e4122fdeb0f3f3e8b5d Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 20 Aug 2022 09:25:51 +0200 Subject: [PATCH 5/6] Update Doc/library/sqlite3.rst Co-authored-by: C.A.M. Gerlach --- Doc/library/sqlite3.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4e7d6af0a5e173..88258debd4076a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1259,7 +1259,6 @@ Cursor objects existing links. .. _sqlite3-columns-by-name: - .. _sqlite3-row-objects: Row objects From 6ea9b18e37700431ebc65578bf63d9ef293ef0db Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 20 Aug 2022 09:25:59 +0200 Subject: [PATCH 6/6] Update Doc/library/sqlite3.rst Co-authored-by: C.A.M. Gerlach --- 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 88258debd4076a..0d1185dd4658f0 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1286,7 +1286,7 @@ Row objects >>> con = sqlite3.connect(":memory:") >>> con.row_factory = sqlite3.Row - >>> res = con.execute("select 'Earth' as name, 6378 as radius") + >>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius") >>> row = res.fetchone() >>> row.keys() ['name', 'radius']