Same documentation for sqlite3 module as in 2.6.

ghaering · ghaering · commit 0d7d6cfee4a3 · 2008-03-29T01:32:44.000Z
diff --git a/Doc/includes/sqlite3/ctx_manager.py b/Doc/includes/sqlite3/ctx_manager.py
@@ -0,0 +1,16 @@
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+con.execute("create table person (id integer primary key, firstname varchar unique)")
+
+# Successful, con.commit() is called automatically afterwards
+with con:
+    con.execute("insert into person(firstname) values (?)", ("Joe",))
+
+# con.rollback() is called after the with block finishes with an exception, the
+# exception is still raised and must be catched
+try:
+    with con:
+        con.execute("insert into person(firstname) values (?)", ("Joe",))
+except sqlite3.IntegrityError:
+    print("couldn't add Joe twice")
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -230,6 +230,24 @@ A :class:`Connection` instance has the following attributes and methods:
    :class:`sqlite3.Cursor`.
 
 
+.. method:: Connection.commit()
+
+   This method commits the current transaction. If you don't call this method,
+   anything you did since the last call to commit() is not visible from from
+   other database connections. If you wonder why you don't see the data you've
+   written to the database, please check you didn't forget to call this method.
+
+.. method:: Connection.rollback()
+
+   This method rolls back any changes to the database since the last call to
+   :meth:`commit`.
+
+.. method:: Connection.close()
+
+   This closes the database connection. Note that this does not automatically
+   call :meth:`commit`. If you just close your database connection without
+   calling :meth:`commit` first, your changes will be lost!
+
 .. method:: Connection.execute(sql, [parameters])
 
    This is a nonstandard shortcut that creates an intermediate cursor object by
@@ -330,6 +348,19 @@ A :class:`Connection` instance has the following attributes and methods:
    one. All necessary constants are available in the :mod:`sqlite3` module.
 
 
+.. method:: Connection.set_progress_handler(handler, n)
+
+   .. versionadded:: 2.6
+
+   This routine registers a callback. The callback is invoked for every *n*
+   instructions of the SQLite virtual machine. This is useful if you want to
+   get called from SQLite during long-running operations, for example to update
+   a GUI.
+
+   If you want to clear any previously installed progress handler, call the
+   method with :const:`None` for *handler*.
+
+
 .. attribute:: Connection.row_factory
 
    You can change this attribute to a callable that accepts the cursor and the
@@ -452,29 +483,29 @@ A :class:`Cursor` instance has the following attributes and methods:
    .. literalinclude:: ../includes/sqlite3/executescript.py
 
 
-.. method:: Cursor.fetchone() 
-          
+.. method:: Cursor.fetchone()
+
    Fetches the next row of a query result set, returning a single sequence,
    or ``None`` when no more data is available.
 
 
 .. method:: Cursor.fetchmany([size=cursor.arraysize])
-          
+
    Fetches the next set of rows of a query result, returning a list.  An empty
    list is returned when no more rows are available.
-   
+
    The number of rows to fetch per call is specified by the *size* parameter.
    If it is not given, the cursor's arraysize determines the number of rows
    to be fetched. The method should try to fetch as many rows as indicated by
    the size parameter. If this is not possible due to the specified number of
    rows not being available, fewer rows may be returned.
-   
+
    Note there are performance considerations involved with the *size* parameter.
    For optimal performance, it is usually best to use the arraysize attribute.
    If the *size* parameter is used, then it is best for it to retain the same
    value from one :meth:`fetchmany` call to the next.
-            
-.. method:: Cursor.fetchall() 
+
+.. method:: Cursor.fetchall()
 
    Fetches all (remaining) rows of a query result, returning a list.  Note that
    the cursor's arraysize attribute can affect the performance of this operation.
@@ -692,10 +723,6 @@ Otherwise leave it at its default, which will result in a plain "BEGIN"
 statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
 IMMEDIATE or EXCLUSIVE.
 
-As the :mod:`sqlite3` module needs to keep track of the transaction state, you
-should not use ``OR ROLLBACK`` or ``ON CONFLICT ROLLBACK`` in your SQL. Instead,
-catch the :exc:`IntegrityError` and call the :meth:`rollback` method of the
-connection yourself.
 
 
 Using pysqlite efficiently
@@ -727,3 +754,15 @@ case-insensitively by name:
 
 .. literalinclude:: ../includes/sqlite3/rowclass.py
 
+
+Using the connection as a context manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.6
+
+Connection objects can be used as context managers
+that automatically commit or rollback transactions.  In the event of an
+exception, the transaction is rolled back; otherwise, the transaction is
+committed:
+
+.. literalinclude:: ../includes/sqlite3/ctx_manager.py
