[Python-3000-checkins] r62027 - in python/branches/py3k/Doc: includes/sqlite3/ctx_manager.py library/sqlite3.rst

[gerhard.haering]

Author: gerhard.haering
Date: Sat Mar 29 02:32:44 2008
New Revision: 62027

Added:
   python/branches/py3k/Doc/includes/sqlite3/ctx_manager.py
Modified:
   python/branches/py3k/Doc/library/sqlite3.rst
Log:
Same documentation for sqlite3 module as in 2.6.


Added: python/branches/py3k/Doc/includes/sqlite3/ctx_manager.py
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/includes/sqlite3/ctx_manager.py	Sat Mar 29 02:32:44 2008
@@ -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")

Modified: python/branches/py3k/Doc/library/sqlite3.rst
==============================================================================
--- python/branches/py3k/Doc/library/sqlite3.rst	(original)
+++ python/branches/py3k/Doc/library/sqlite3.rst	Sat Mar 29 02:32:44 2008
@@ -230,6 +230,24 @@
    :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 @@
    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 @@
    .. 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 @@
 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 @@
 
 .. 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