From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 19 Nov 2020 03:11:17 +0000 (+0000)
Subject: More docs about Rollback usage
X-Git-Tag: 3.0.dev0~347
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=522bd773421000dba402c9489f14ad48ccc29601;p=thirdparty%2Fpsycopg.git

More docs about Rollback usage
---

diff --git a/docs/connection.rst b/docs/connection.rst
index abe6b08fe..84cb838b3 100644
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -152,3 +152,15 @@ Connection support objects
 .. autoclass:: AsyncTransaction(connection: AsyncConnection, savepoint_name: Optional[str] = None, force_rollback: bool = False)
 
 .. autoexception:: Rollback
+
+    It can be used as
+
+    - ``raise Rollback``: roll back the operation that happened in the current
+      transaction block and continue the program after the block.
+
+    - ``raise Rollback()``: same effect as above
+
+    - :samp:`raise Rollback({tx})`: roll back any operation that happened in
+      the `Transaction` *tx* (returned by a statement such as :samp:`with
+      conn.transaction() as {tx}:` and all the blocks nested within. The
+      program will continue after the *tx* block.
diff --git a/docs/usage.rst b/docs/usage.rst
index eb45f9093..c3694f559 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -248,11 +248,13 @@ but not entirely committed yet.
 
 .. code:: python
 
+    from psycopg3 import Rollback
+
     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)
+                    raise Rollback(outer_tx)
             process_command(command)
 
     # If `Rollback` is raised, it would propagate only up to this block,