docs: add documentation for Transaction status

diff --git a/docs/api/objects.rst b/docs/api/objects.rst
index d18192568b7f693dadd3446f5aa9997ce28f1ba2..9dc75a39c3283c51efe7f1aaf719b0dbfa530249 100644 (file)
--- a/docs/api/objects.rst
+++ b/docs/api/objects.rst
@@ -262,11 +262,31 @@ See :ref:`transactions` for details about these objects.
 
     .. autoattribute:: savepoint_name
     .. autoattribute:: connection
+    .. autoattribute:: status
+
+        The current status of the transaction. Returns a `Transaction.Status`
+        enum value indicating whether the transaction is active, committed,
+        rolled back, or failed.
+
+        Possible values:
+
+        - `!NOT_STARTED`: Transaction created but not yet entered
+        - `!ACTIVE`: Transaction is currently active
+        - `!COMMITTED`: Transaction successfully committed
+        - `!ROLLED_BACK_EXPLICITLY`: Transaction explicitly rolled back
+        - `!ROLLED_BACK_WITH_ERROR`: Transaction rolled back due to an error
+        - `!FAILED`: Transaction failed due to connection failure
+
+        See :ref:`transaction-status` for more details and examples.
 
 
 .. autoclass:: AsyncTransaction()
 
     .. autoattribute:: connection
+    .. autoattribute:: status
+
+        The current status of the transaction. Returns a `AsyncTransaction.Status`
+        enum value. See `Transaction.status` for details.
 
 
 .. autoexception:: Rollback

diff --git a/docs/basic/transactions.rst b/docs/basic/transactions.rst
index abcecc9d2f050db9515ca94c54cf4670dc615d84..ab440ed7ef0a4b9348982293f6009aae38164f69 100644 (file)
--- a/docs/basic/transactions.rst
+++ b/docs/basic/transactions.rst
@@ -3,6 +3,7 @@
 .. index:: Transactions management
 .. index:: InFailedSqlTransaction
 .. index:: idle in transaction
+.. index:: Transaction status
 
 .. _transactions:
 
@@ -297,6 +298,67 @@ but not entirely committed yet.
     # and the program would continue from here with no exception.
 
 
+.. _transaction-status:
+
+Transaction status
+^^^^^^^^^^^^^^^^^^
+
+Each `Transaction` object exposes a `~Transaction.status` property that allows
+you to inspect the current state of the transaction. This can be useful for
+debugging, logging, or implementing custom transaction management logic.
+
+The `!status` property returns a `Transaction.Status` enum value that can be
+one of the following:
+
+- `!NOT_STARTED`: The transaction has been created but not yet entered (before
+  the `!__enter__()` method is called).
+- `!ACTIVE`: The transaction is currently active (inside the `!with` block).
+- `!COMMITTED`: The transaction exited successfully and changes were committed.
+- `!ROLLED_BACK_EXPLICITLY`: The transaction was explicitly rolled back, either
+  by raising a `Rollback` exception or by using `!force_rollback=True`.
+- `!ROLLED_BACK_WITH_ERROR`: The transaction was rolled back due to an
+  exception raised within the transaction block.
+- `!FAILED`: The transaction failed due to a connection failure (e.g., the
+  connection was closed or became unavailable during the transaction).
+
+Here's an example of how to use the status property:
+
+.. code:: python
+
+    from psycopg import Rollback
+
+    # Successful transaction
+    with conn.transaction() as tx:
+        assert tx.status == tx.Status.ACTIVE
+        conn.execute("INSERT INTO data VALUES (%s)", ("Hello",))
+    assert tx.status == tx.Status.COMMITTED
+
+    # Transaction rolled back with an error
+    try:
+        with conn.transaction() as tx:
+            conn.execute("INSERT INTO data VALUES (%s)", ("World",))
+            1 / 0  # Causes an exception
+    except ZeroDivisionError:
+        pass
+    assert tx.status == tx.Status.ROLLED_BACK_WITH_ERROR
+
+    # Explicit rollback
+    with conn.transaction() as tx:
+        conn.execute("INSERT INTO data VALUES (%s)", ("Test",))
+        raise Rollback()
+    assert tx.status == tx.Status.ROLLED_BACK_EXPLICITLY
+
+    # Force rollback
+    with conn.transaction(force_rollback=True) as tx:
+        conn.execute("INSERT INTO data VALUES (%s)", ("Temp",))
+    assert tx.status == tx.Status.ROLLED_BACK_EXPLICITLY
+
+The `!status` property remains accessible after the transaction context has
+exited, allowing you to check the final outcome of the transaction even after
+the `!with` block completes. This is particularly useful when you need to log
+transaction outcomes or implement retry logic based on the transaction status.
+
+
 .. _transaction-characteristics:
 
 Transaction characteristics

diff --git a/docs/news.rst b/docs/news.rst
index cfdc1c4476767d175ffd31d77a2b35d7a50e4b3c..c7d175a8f46801aa7f26a67422f2aa34264b364a 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -24,6 +24,8 @@ Psycopg 3.3.0 (unreleased)
 - Add `Cursor.set_result()` and `Cursor.results()` to move across the result
   sets of queries executed though `~Cursor.executemany()` or
   `~Cursor.execute()` with multiple statements (:tickets:`#1080, #1170`).
+- Add `Transaction.status` to report the status during and after a
+  `~Connection.transaction()` block (:ticket:`#969`).
 
 .. rubric:: New libpq wrapper features