@@ -380,6 +380,16 @@ Connection Objects
380
380
381
381
.. class :: Connection
382
382
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
+
383
393
An SQLite database connection has the following attributes and methods:
384
394
385
395
.. attribute :: isolation_level
@@ -761,6 +771,22 @@ Connection Objects
761
771
Cursor Objects
762
772
--------------
763
773
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
+
764
790
.. class :: Cursor
765
791
766
792
A :class: `Cursor ` instance has the following attributes and methods.
@@ -926,13 +952,11 @@ Row Objects
926
952
927
953
A :class: `Row ` instance serves as a highly optimized
928
954
: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.
930
958
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.
936
960
937
961
.. method :: keys
938
962
@@ -1355,8 +1379,10 @@ Using :mod:`sqlite3` efficiently
1355
1379
--------------------------------
1356
1380
1357
1381
1358
- Using shortcut methods
1359
- ^^^^^^^^^^^^^^^^^^^^^^
1382
+ .. _sqlite3-connection-shortcuts :
1383
+
1384
+ Using connection shortcut methods
1385
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1360
1386
1361
1387
Using the :meth: `~Connection.execute `,
1362
1388
:meth: `~Connection.executemany `, and :meth: `~Connection.executescript `
0 commit comments