Added documentation for Rollback

diff --git a/docs/connection.rst b/docs/connection.rst
index 03cb4441f162faa3dad2fb679e429cd715ab5f6f..abe6b08fecf60e7cf440d611457479cc35e3dcfa 100644 (file)
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -141,6 +141,8 @@ Connection support objects
 .. autoclass:: Notify
     :members: channel, payload, pid
 
+.. rubric:: Objects involved in :ref:`transactions`
+
 .. autoclass:: Transaction(connection: Connection, savepoint_name: Optional[str] = None, force_rollback: bool = False)
 
     .. autoproperty:: savepoint_name
@@ -148,3 +150,5 @@ Connection support objects
         :annotation: Connection
 
 .. autoclass:: AsyncTransaction(connection: AsyncConnection, savepoint_name: Optional[str] = None, force_rollback: bool = False)
+
+.. autoexception:: Rollback

diff --git a/docs/from_pg2.rst b/docs/from_pg2.rst
index 130b2445d9dd64703393c25ba9cd9678d42db325..29eb3865fdc1fe301256e350c63325c4b7a81c2b 100644 (file)
--- a/docs/from_pg2.rst
+++ b/docs/from_pg2.rst
@@ -85,6 +85,8 @@ files.
 What's new in psycopg3
 ======================
 
+TODO: to be completed
+
 - `asyncio` support.
 - Several data types are adapted out-of-the-box: uuid, network, range, bytea,
   array of any supported type are dealt with automatically.

diff --git a/docs/usage.rst b/docs/usage.rst
index fc24d3187353eb803cc6e49901ec98e050383ff7..eb45f90936fcc3f8176d5ec6bdbee20efe9e19e8 100644 (file)
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -129,7 +129,7 @@ TODO: lift from psycopg2 docs
 
 
 .. index::
-    pair: Query; Parameters
+    pair: Binary; Parameters
 
 .. _binary-data:
 
@@ -208,11 +208,13 @@ accounts unbalanced:
     # The transaction is now committed
 
 Transaction blocks can also be nested (internal transaction blocks are
-implemented using :sql:`SAVEPOINT`): an exception raised inside an inner block
-has a chance of being handled and not fail completely outer operations. The
-following is an example where a series of operation interact with the
-database. Operations are allowed to fail, and we want to store the number of
-operations successfully processed too.
+implemented using SAVEPOINT__): an exception raised inside an inner block
+has a chance of being handled and not completely fail outer operations. The
+following is an example where a series of operations interact with the
+database: operations are allowed to fail, plus we also want to store the
+number of operations successfully processed.
+
+.. __: https://www.postgresql.org/docs/current/sql-savepoint.html
 
 .. code:: python
 
@@ -232,10 +234,29 @@ operations successfully processed too.
 If `!unreliable_operation()` causes an error, including an operation causing a
 database error, all its changes will be reverted. The exception bubbles up
 outside the block: in the example it is intercepted by the `!try` so that the
-loop can complete. The outermost loop is unaffected (unless other errors
+loop can complete. The outermost block is unaffected (unless other errors
 happen there).
 
-.. TODO: Document Rollback or remove it
+You can also write code to explicitly roll back any currently active
+transaction block, by raising the `Rollback` exception. The exception "jumps"
+to the end of a transaction block, rolling back its transaction but allowing
+the program execution to continue from there. By default the exception rolls
+back the innermost transaction block, but any current block can be specified
+as the target. In the following example, an hypothetical `!CancelCommand`
+may stop the processing and cancel any operation previously performed,
+but not entirely committed yet.
+
+.. code:: python
+
+    with conn.transaction() as outer_tx:
+        for command in commands():
+            with conn.transaction() as inner_tx:
+                if isinstance(command, CancelCommand):
+                    raise psycopg3.Rollback(outer_tx)
+            process_command(command)
+
+    # If `Rollback` is raised, it would propagate only up to this block,
+    # and the program would continue from here with no exception.
 
 
 .. index::

diff --git a/psycopg3/psycopg3/transaction.py b/psycopg3/psycopg3/transaction.py
index 63a098f0208b55dedf5215f5b2da844be22a0e48..3ef83ef12f4cd14db44bfa0cbd4c3d0d2607b429 100644 (file)
--- a/psycopg3/psycopg3/transaction.py
+++ b/psycopg3/psycopg3/transaction.py
@@ -21,7 +21,7 @@ _log = logging.getLogger(__name__)
 
 class Rollback(Exception):
     """
-    Exit the current Transaction context immediately and rollback any changes
+    Exit the current `Transaction` context immediately and rollback any changes
     made within this context.
 
     If a transaction context is specified in the constructor, rollback