Adding docs for the planned set_transaction/autocommit features

doc/src/advanced.rst

@@ -239,9 +239,8 @@ be sent from Python code simply executing a :sql:`NOTIFY` command in an
 `~cursor.execute()` call.
 
 Because of the way sessions interact with notifications (see |NOTIFY|_
-documentation), you should keep the connection in :ref:`autocommit
+documentation), you should keep the connection in `~connection.autocommit`
-<autocommit>` mode if you wish to receive or send notifications in a timely
+mode if you wish to receive or send notifications in a timely manner.
-manner.
 
 .. |LISTEN| replace:: :sql:`LISTEN`
 .. _LISTEN: http://www.postgresql.org/docs/9.0/static/sql-listen.html
@@ -373,12 +372,14 @@ When an asynchronous query is being executed, `connection.isexecuting()` returns
 connection.
 
 There are several limitations in using asynchronous connections: the
-connection is always in :ref:`autocommit <autocommit>` mode and it is not
+connection is always in `~connection.autocommit` mode and it is not
-possible to change it using `~connection.set_isolation_level()`. So a
+possible to change it. So a
 transaction is not implicitly started at the first query and is not possible
 to use methods `~connection.commit()` and `~connection.rollback()`: you can
 manually control transactions using `~cursor.execute()` to send database
-commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`.
+commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`. Similarly
+`set_transaction()` can't be used but it is still possible to invoke the
+:sql:`SET` command with the proper :sql:`default_transaction_...` parameter.
 
 With asynchronous connections it is also not possible to use
 `~connection.set_client_encoding()`, `~cursor.executemany()`, :ref:`large

doc/src/conf.py

@@ -111,10 +111,10 @@ rst_epilog = """
 .. _DBAPI: http://www.python.org/dev/peps/pep-0249/
 
 .. _transaction isolation level:
-    http://www.postgresql.org/docs/9.0/static/transaction-iso.html
+    http://www.postgresql.org/docs/9.1/static/transaction-iso.html
 
 .. _serializable isolation level:
-    http://www.postgresql.org/docs/9.0/static/transaction-iso.html#XACT-SERIALIZABLE
+    http://www.postgresql.org/docs/9.1/static/transaction-iso.html#XACT-SERIALIZABLE
 
 .. _mx.DateTime: http://www.egenix.com/products/python/mxBase/mxDateTime/
 

doc/src/connection.rst

@@ -327,11 +327,85 @@ The ``connection`` class
         pair: Transaction; Autocommit
         pair: Transaction; Isolation level
 
-    .. _autocommit:
+    .. method:: set_transaction(isolation_level=None, readonly=None, deferrable=None, autocommit=None)
+
+        Set one or more parameters for the next transactions or statements in
+        the current session. See |SET TRANSACTION|_ for further details.
+
+        .. |SET TRANSACTION| replace:: :sql:`SET TRANSACTION`
+        .. _SET TRANSACTION: http://www.postgresql.org/docs/9.1/static/sql-set-transaction.html
+
+        :param isolation_level: set the `isolation level`_ for the next
+            transactions/statements.  The value should be one of the
+            :ref:`constants <isolation-level-constants>` defined in the
+            `~psycopg2.extensions` module.
+        :param readonly: if `!True`, set the connection to read only;
+            read/write if `!False`.
+        :param deferrable: if `!True`, set the connection to deferrable;
+            non deferrable if `!False`. Only available from PostgreSQL 9.1.
+        :param autocommit: switch the connection to autocommit mode: not a
+            PostgreSQL session setting but an alias for setting the
+            `autocommit` attribute.
+
+        .. _isolation level:
+            http://www.postgresql.org/docs/9.1/static/transaction-iso.html
+
+        The function must be invoked with no transaction in progress. At every
+        function invocation, only the parameters whose value is not `!None` are
+        changed.
+
+        The default for the values are defined by the server configuration:
+        see values for |default_transaction_isolation|__,
+        |default_transaction_read_only|__, |default_transaction_deferrable|__.
+
+        .. |default_transaction_isolation| replace:: :sql:`default_transaction_isolation`
+        .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION
+        .. |default_transaction_read_only| replace:: :sql:`default_transaction_read_only`
+        .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY
+        .. |default_transaction_deferrable| replace:: :sql:`default_transaction_deferrable`
+        .. __: http://www.postgresql.org/docs/9.1/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE
+
+        .. note::
+
+            There is currently no builtin method to read the current value for
+            the parameters: use :sql:`SHOW default_transaction_...` to read
+            the values from the backend.
+
+        .. versionadded:: 2.4.2
+
+
+    .. attribute:: autocommit
+
+        Read/write attribute: if `!True`, no transaction is handled by the
+        driver and every statement sent to the backend has immediate effect;
+        if `!False` a new transaction is started at the first command
+        execution: the methods `commit()` or `rollback()` must be manually
+        invoked to terminate the transaction.
+
+        The default is `!False` (manual commit) as per DBAPI specification.
+
+        .. warning::
+
+            By default, any query execution, including a simple :sql:`SELECT`
+            will start a transaction: for long-running program, if no further
+            action is taken, the session will remain "idle in transaction", a
+            condition non desiderable for several reasons (locks are held by
+            the session, tables bloat...). For long lived scripts, either
+            ensure to terminate a transaction as soon as possible or use an
+            autocommit connection.
+
+        .. versionadded:: 2.4.2
+
 
     .. attribute:: isolation_level
     .. method:: set_isolation_level(level)
 
+        .. note::
+
+            From version 2.4.2, replaced by `set_transaction()` and
+            `autocommit`, offering finer control on the transaction
+            characteristics.
+
         Read or set the `transaction isolation level`_ for the current session.
         The level defines the different phenomena that can happen in the
         database between concurrent transactions.

doc/src/faq.rst

@@ -22,8 +22,8 @@ Why does `!psycopg2` leave database sessions "idle in transaction"?
     call one of the transaction closing methods before leaving the connection
     unused for a long time (which may also be a few seconds, depending on the
     concurrency level in your database).  Alternatively you can use a
-    connection in :ref:`autocommit <autocommit>` mode to avoid a new
+    connection in `~connection.autocommit` mode to avoid a new transaction to
-    transaction to be started at the first command.
+    be started at the first command.
 
 I receive the error *current transaction is aborted, commands ignored until end of transaction block* and can't do anything else!
     There was a problem *in the previous* command to the database, which