From: Daniele Varrazzo Date: Sat, 22 Nov 2025 17:49:57 +0000 (+0100) Subject: docs: improvements to Transaction.status documentation X-Git-Tag: 3.3.0~12^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0a4e043bc37be7291c6ca4e47f362e6c2e87fa4b;p=thirdparty%2Fpsycopg.git docs: improvements to Transaction.status documentation --- diff --git a/docs/api/objects.rst b/docs/api/objects.rst index 9dc75a39c..f27f2bd75 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 ab440ed7e..20dc76f3f 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 c7d175a8f..44b0052f5 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 b56c1efe7..11a250757 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: