Brought documentation for sqlite3 module up-to-date. Fixed Issue1625205 which

complained about commit, rollback and close not being documented.

diff --git a/Doc/includes/sqlite3/ctx_manager.py b/Doc/includes/sqlite3/ctx_manager.py
new file mode 100644 (file)
index 0000000..27dd0b5
--- /dev/null
+++ 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
index da313fd5976e7c6e0b127a4ddc9f92d387810111..29d5e490b749bfed2f1fe4579cc7c1531e11df7c 100644 (file)
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -232,6 +232,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
@@ -245,7 +263,6 @@ A :class:`Connection` instance has the following attributes and methods:
    calling the cursor method, then calls the cursor's :meth:`executemany` method
    with the parameters given.
 
-
 .. method:: Connection.executescript(sql_script)
 
    This is a nonstandard shortcut that creates an intermediate cursor object by
@@ -332,6 +349,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
@@ -701,10 +731,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
@@ -736,3 +762,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