psycopg.git / summary / log / commit / refs
commit 0a4e043bc37be7291c6ca4e47f362e6c2e87fa4b
Author: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat Nov 22 17:49:57 2025 +0000
docs: improvements to Transaction.status documentation
docs/api/objects.rst | 54 +++++++++++++++++++++++++++++-------------
docs/basic/transactions.rst | 25 +++++++------------
docs/news.rst | 2 +-
psycopg/psycopg/transaction.py | 16 ++++++++++++-
4 files changed, 62 insertions(+), 35 deletions(-)
diff --git a/docs/api/objects.rst b/docs/api/objects.rst
index 9dc75a39..f27f2bd7 100644
--- 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 ab440ed7..20dc76f3 100644
--- 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 c7d175a8..44b0052f 100644
--- 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 b56c1efe..11a25075 100644
--- 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:
[parent: 718fc641e086]