docs: improvements to Transaction.status documentation

diff --git a/docs/api/objects.rst b/docs/api/objects.rst
index 9dc75a39c3283c51efe7f1aaf719b0dbfa530249..f27f2bd752df2b2bdea96e45c01afab8f0582599 100644 (file)
--- a/docs/api/objects.rst
+++ b/docs/api/objects.rst
@@ -247,7 +247,7 @@ Transaction-related objects
 
 See :ref:`transactions` for details about these objects.
 
-.. autoclass:: IsolationLevel
+.. autoclass:: IsolationLevel()
     :members:
 
     The value is usually used with the `Connection.isolation_level` property.
@@ -262,31 +262,53 @@ 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.
+    .. attribute:: status
 
-        Possible values:
+        The current status of the transaction.
 
-        - `!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
+        :type: `~psycopg.Transaction.Status`
 
         See :ref:`transaction-status` for more details and examples.
 
 
 .. autoclass:: AsyncTransaction()
 
+    The class differs from `Transaction` for the following details:
+
     .. autoattribute:: connection
-    .. autoattribute:: status
 
-        The current status of the transaction. Returns a `AsyncTransaction.Status`
-        enum value. See `Transaction.status` for details.
+
+.. class:: psycopg.Transaction.Status()
+.. autoclass:: psycopg.AsyncTransaction.Status()
+
+    .. note: `:members:` doeesn't seem to work currently. Nested class problem?
+
+    .. attribute:: NON_STARTED
+
+        Transaction created but not yet entered.
+
+    .. attribute:: ACTIVE
+
+        Transaction currently active (inside the `!with` block).
+
+    .. attribute:: COMMITTED
+
+        Transaction successfully committed.
+
+    .. attribute:: ROLLED_BACK_EXPLICITLY
+
+        The transaction was explicitly rolled back (by raising
+        `~psycopg.Rollback` or calling `!transaction(force_rollback=True)`).
+
+    .. attribute:: ROLLED_BACK_WITH_ERROR
+
+        The transaction was rolled back due to an exception raised within the
+        transaction block.
+
+    .. attribute:: FAILED
+
+        The transaction failed due to a connection failure (e.g., the
+        connection was closed or became unavailable during the transaction).
 
 
 .. autoexception:: Rollback

diff --git a/docs/basic/transactions.rst b/docs/basic/transactions.rst
index ab440ed7ef0a4b9348982293f6009aae38164f69..20dc76f3fc2cd3707dc3a775e4b361b36330bd08 100644 (file)
--- a/docs/basic/transactions.rst
+++ b/docs/basic/transactions.rst
@@ -303,25 +303,16 @@ but not entirely committed yet.
 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
+.. versionadded:: 3.3
+
+Each `!Transaction` object exposes a `~Transaction.status` property allowing
+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:
+The `!status` property is a `~psycopg.Transaction.Status` enum value:
+please check the enum documentation for the possible values.
+
+Here are a few examples of how to use the `!status` property:
 
 .. code:: python
 

diff --git a/docs/news.rst b/docs/news.rst
index c7d175a8f46801aa7f26a67422f2aa34264b364a..44b0052f53913fb9f9a9798a7dd311cbdafd2695 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -24,7 +24,7 @@ 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
+- Add :ref:`transaction-status` to report the status during and after a
   `~Connection.transaction()` block (:ticket:`#969`).
 
 .. rubric:: New libpq wrapper features

diff --git a/psycopg/psycopg/transaction.py b/psycopg/psycopg/transaction.py
index b56c1efe75a57ea1bfcc3433d3c68bed8951164f..11a250757d7aa5f7f2f2719198fdb83d606173d2 100644 (file)
--- a/psycopg/psycopg/transaction.py
+++ b/psycopg/psycopg/transaction.py
@@ -53,6 +53,13 @@ class OutOfOrderTransactionNesting(e.ProgrammingError):
 
 class BaseTransaction(Generic[ConnectionType]):
     class Status(str, Enum):
+        """
+        The current status of a transaction.
+
+        Exposed as the `~psycopg.Transaction.status` attribute of
+        `~psycopg.Transaction` and `~psycopg.AsyncTransaction` objects.
+        """
+
         NOT_STARTED = "not_started"
         ACTIVE = "active"
         COMMITTED = "committed"
@@ -242,7 +249,10 @@ class Transaction(BaseTransaction["Connection[Any]"]):
 
     @property
     def connection(self) -> Connection[Any]:
-        """The connection the object is managing."""
+        """The connection the object is managing.
+
+        :type: `Connection`
+        """
         return self._conn
 
     def __enter__(self) -> Self:
@@ -273,6 +283,10 @@ class AsyncTransaction(BaseTransaction["AsyncConnection[Any]"]):
 
     @property
     def connection(self) -> AsyncConnection[Any]:
+        """The connection the object is managing.
+
+        :type: `AsyncConnection`
+        """
         return self._conn
 
     async def __aenter__(self) -> Self: