Added documentation for the Xid object.

This commit is contained in:
Daniele Varrazzo 2010-10-16 02:31:51 +01:00
parent 3e658c33b5
commit 90e0e2f47d
4 changed files with 74 additions and 31 deletions

View File

@ -119,13 +119,14 @@ The ``connection`` class
.. method:: xid(format_id, gtrid, bqual) .. method:: xid(format_id, gtrid, bqual)
Returns a transaction ID object suitable for passing to the Returns a `~psycopg2.extensions.Xid` instance to be passed to the
`!tpc_*()` methods of this connection. The argument types and `!tpc_*()` methods of this connection. The argument types and
constraints are explained in :ref:`tpc`. constraints are explained in :ref:`tpc`.
The object returned can be accessed and unpacked as a 3 items tuple, The values passed to the method will be available on the returned
returning the arguments passed to the method. The same values are object as the members `!format_id`, `!gtrid`, `!bqual`. The object
available as attributes `!format_id`, `!gtrid`, `!bqual`. also allows accessing to these members and unpacking as a 3-items
tuple.
.. method:: tpc_begin(xid) .. method:: tpc_begin(xid)
@ -223,12 +224,14 @@ The ``connection`` class
.. method:: tpc_recover() .. method:: tpc_recover()
Returns a list of pending transaction IDs suitable for use with Returns a list of `~psycopg2.extensions.Xid` representing pending
`!tpc_commit(xid)` or `!tpc_rollback(xid)`. transactions, suitable for use with `tpc_commit()` or
`tpc_rollback()`.
If a transaction was not initiated by Psycopg, the returned Xids will If a transaction was not initiated by Psycopg, the returned Xids will
have attributes `!format_id` and `!bqual` set to `None` and the have attributes `~psycopg2.extensions.Xid.format_id` and
`!gtrid` set to the PostgreSQL transaction ID: such Xids are still `~psycopg2.extensions.Xid.bqual` set to `None` and the
`~psycopg2.extensions.Xid.gtrid` set to the PostgreSQL transaction ID: such Xids are still
usable for recovery. Psycopg uses the same algorithm of the usable for recovery. Psycopg uses the same algorithm of the
`PostgreSQL JDBC driver`__ to encode a XA triple in a string, so `PostgreSQL JDBC driver`__ to encode a XA triple in a string, so
transactions initiated by a program using such driver should be transactions initiated by a program using such driver should be
@ -236,13 +239,10 @@ The ``connection`` class
.. __: http://jdbc.postgresql.org/ .. __: http://jdbc.postgresql.org/
Xids returned by `!tpc_recover()` have additional attributes populated Xids returned by `!tpc_recover()` also have extra attributes
with the values read from the server: `~psycopg2.extensions.Xid.prepared`, `~psycopg2.extensions.Xid.owner`,
`~psycopg2.extensions.Xid.database` populated with the values read
- `!prepared`: timestamp with timezone reporting the time the from the server.
transaction was prepared
- `!owner`: name of the user who prepared the transaction
- `!database`: name of the database the transaction belongs to
.. seealso:: the |pg_prepared_xacts|_ system view. .. seealso:: the |pg_prepared_xacts|_ system view.

View File

@ -112,6 +112,12 @@ functionalities defined by the |DBAPI|_.
.. versionadded:: 2.2.3 .. versionadded:: 2.2.3
.. autoclass:: Xid(format_id, gtrid, bqual)
:members: format_id, gtrid, bqual, prepared, owner, database
.. automethod:: from_string(s)
.. autofunction:: set_wait_callback(f) .. autofunction:: set_wait_callback(f)
.. versionadded:: 2.2.0 .. versionadded:: 2.2.0

View File

@ -553,7 +553,7 @@ Two-Phase Commit protocol support
.. versionadded:: 2.2.3 .. versionadded:: 2.2.3
Psycopg exposes the two-phase commit features available from PostgreSQL 8,1 Psycopg exposes the two-phase commit features available since PostgreSQL 8.1
implementing the *two-phase commit extensions* proposed by the |DBAPI|. implementing the *two-phase commit extensions* proposed by the |DBAPI|.
The |DBAPI| model of two-phase commit is inspired to the `XA specification`__, The |DBAPI| model of two-phase commit is inspired to the `XA specification`__,
@ -576,9 +576,10 @@ database using `~connection.tpc_recover()` and completed using the above
`!tpc_commit()` and `!tpc_rollback()`. `!tpc_commit()` and `!tpc_rollback()`.
PostgreSQL doesn't follow the XA standard though, and the ID for a PostgreSQL PostgreSQL doesn't follow the XA standard though, and the ID for a PostgreSQL
prepared transaction can be any string up to 200 characters long. Psycopg can prepared transaction can be any string up to 200 characters long.
deal both with Xid objects created by the `!xid()` method and with Psycopg's `~psycopg2.extensions.Xid` objects can represent both XA-style
transactions identified only by a string. transactions IDs (such as the ones created by the `!xid()` method) and
PostgreSQL transaction IDs identified by an unparsed string.
The format in which the Xids are converted into strings passed to the The format in which the Xids are converted into strings passed to the
database is the same employed by the `PostgreSQL JDBC driver`__: this should database is the same employed by the `PostgreSQL JDBC driver`__: this should

View File

@ -34,13 +34,48 @@
#include "psycopg/psycopg.h" #include "psycopg/psycopg.h"
#include "psycopg/xid.h" #include "psycopg/xid.h"
static const char xid_doc[] =
"A transaction identifier used for two-phase commit.\n\n"
"Usually returned by the connection methods `~connection.xid()` and\n"
"`~connection.tpc_recover()`.\n"
"`!Xid` instances can be unpacked as a 3-item tuples containing the items\n"
":samp:`({format_id},{gtrid},{bqual})`.\n"
"The `!str()` of the object returns the *transaction ID* used\n"
"in the commands sent to the server.\n\n"
"See :ref:`tpc` for an introduction.";
static const char format_id_doc[] =
"Format ID in a XA transaction.\n\n"
"A non-negative 32 bit integer.\n"
"`None` if the transaction doesn't follow the XA standard.";
static const char gtrid_doc[] =
"Global transaction ID in a XA transaction.\n\n"
"If the transaction doesn't follow the XA standard, it is the plain\n"
"*transaction ID* used in the server commands.";
static const char bqual_doc[] =
"Branch qualifier of the transaction.\n\n"
"In a XA transaction every resource participating to a transaction\n"
"receives a distinct branch qualifier.\n"
"`None` if the transaction doesn't follow the XA standard.";
static const char prepared_doc[] =
"Timestamp (with timezone) in which a recovered transaction was prepared.";
static const char owner_doc[] =
"Name of the user who prepared a recovered transaction.";
static const char database_doc[] =
"Database the recovered transaction belongs to.";
static PyMemberDef xid_members[] = { static PyMemberDef xid_members[] = {
{ "format_id", T_OBJECT, offsetof(XidObject, format_id), RO }, { "format_id", T_OBJECT, offsetof(XidObject, format_id), RO, (char *)format_id_doc },
{ "gtrid", T_OBJECT, offsetof(XidObject, gtrid), RO }, { "gtrid", T_OBJECT, offsetof(XidObject, gtrid), RO, (char *)gtrid_doc },
{ "bqual", T_OBJECT, offsetof(XidObject, bqual), RO }, { "bqual", T_OBJECT, offsetof(XidObject, bqual), RO, (char *)bqual_doc },
{ "prepared", T_OBJECT, offsetof(XidObject, prepared), RO }, { "prepared", T_OBJECT, offsetof(XidObject, prepared), RO, (char *)prepared_doc },
{ "owner", T_OBJECT, offsetof(XidObject, owner), RO }, { "owner", T_OBJECT, offsetof(XidObject, owner), RO, (char *)owner_doc },
{ "database", T_OBJECT, offsetof(XidObject, database), RO }, { "database", T_OBJECT, offsetof(XidObject, database), RO, (char *)database_doc },
{ NULL } { NULL }
}; };
@ -233,7 +268,12 @@ exit:
static const char xid_from_string_doc[] = static const char xid_from_string_doc[] =
"Create a Xid object from a string representation."; "Create a `!Xid` object from a string representation. Static method.\n\n"
"If *s* is a PostgreSQL transaction ID produced by a XA transaction,\n"
"the returned object will have `format_id`, `gtrid`, `bqual` set to\n"
"the values of the preparing XA id.\n"
"Otherwise only the `!gtrid` is populated with the unparsed string.\n"
"The operation is the inverse of the one performed by ``str(xid)``.";
static PyObject * static PyObject *
xid_from_string_method(PyObject *cls, PyObject *args) xid_from_string_method(PyObject *cls, PyObject *args)
@ -245,6 +285,7 @@ xid_from_string_method(PyObject *cls, PyObject *args)
return (PyObject *)xid_from_string(s); return (PyObject *)xid_from_string(s);
} }
static PySequenceMethods xid_sequence = { static PySequenceMethods xid_sequence = {
(lenfunc)xid_len, /* sq_length */ (lenfunc)xid_len, /* sq_length */
0, /* sq_concat */ 0, /* sq_concat */
@ -258,17 +299,12 @@ static PySequenceMethods xid_sequence = {
0, /* sq_inplace_repeat */ 0, /* sq_inplace_repeat */
}; };
static struct PyMethodDef xid_methods[] = { static struct PyMethodDef xid_methods[] = {
{"from_string", (PyCFunction)xid_from_string_method, {"from_string", (PyCFunction)xid_from_string_method,
METH_VARARGS|METH_STATIC, xid_from_string_doc}, METH_VARARGS|METH_STATIC, xid_from_string_doc},
{NULL} {NULL}
}; };
static const char xid_doc[] =
"A transaction identifier used for two phase commit.";
PyTypeObject XidType = { PyTypeObject XidType = {
PyObject_HEAD_INIT(NULL) PyObject_HEAD_INIT(NULL)
0, 0,