|
def | __init__ (self, client, server_session, options, authset, implicit) |
|
def | end_session (self) |
|
def | __enter__ (self) |
|
def | __exit__ (self, exc_type, exc_val, exc_tb) |
|
def | client (self) |
|
def | options (self) |
|
def | session_id (self) |
|
def | cluster_time (self) |
|
def | operation_time (self) |
|
def | with_transaction (self, callback, read_concern=None, write_concern=None, read_preference=None, max_commit_time_ms=None) |
|
def | start_transaction (self, read_concern=None, write_concern=None, read_preference=None, max_commit_time_ms=None) |
|
def | commit_transaction (self) |
|
def | abort_transaction (self) |
|
def | advance_cluster_time (self, cluster_time) |
|
def | advance_operation_time (self, operation_time) |
|
def | has_ended (self) |
|
def | in_transaction (self) |
|
A session for ordering sequential operations.
:class:`ClientSession` instances are **not thread-safe or fork-safe**.
They can only be used by one thread or process at a time. A single
:class:`ClientSession` cannot be used to run multiple operations
concurrently.
Should not be initialized directly by application developers - to create a
:class:`ClientSession`, call
:meth:`~pymongo.mongo_client.MongoClient.start_session`.
def with_transaction |
( |
|
self, |
|
|
|
callback, |
|
|
|
read_concern = None , |
|
|
|
write_concern = None , |
|
|
|
read_preference = None , |
|
|
|
max_commit_time_ms = None |
|
) |
| |
Execute a callback in a transaction.
This method starts a transaction on this session, executes ``callback``
once, and then commits the transaction. For example::
def callback(session):
orders = session.client.db.orders
inventory = session.client.db.inventory
orders.insert_one({"sku": "abc123", "qty": 100}, session=session)
inventory.update_one({"sku": "abc123", "qty": {"$gte": 100}},
{"$inc": {"qty": -100}}, session=session)
with client.start_session() as session:
session.with_transaction(callback)
To pass arbitrary arguments to the ``callback``, wrap your callable
with a ``lambda`` like this::
def callback(session, custom_arg, custom_kwarg=None):
# Transaction operations...
with client.start_session() as session:
session.with_transaction(
lambda s: callback(s, "custom_arg", custom_kwarg=1))
In the event of an exception, ``with_transaction`` may retry the commit
or the entire transaction, therefore ``callback`` may be invoked
multiple times by a single call to ``with_transaction``. Developers
should be mindful of this possiblity when writing a ``callback`` that
modifies application state or has any other side-effects.
Note that even when the ``callback`` is invoked multiple times,
``with_transaction`` ensures that the transaction will be committed
at-most-once on the server.
The ``callback`` should not attempt to start new transactions, but
should simply run operations meant to be contained within a
transaction. The ``callback`` should also not commit the transaction;
this is handled automatically by ``with_transaction``. If the
``callback`` does commit or abort the transaction without error,
however, ``with_transaction`` will return without taking further
action.
:class:`ClientSession` instances are **not thread-safe or fork-safe**.
Consequently, the ``callback`` must not attempt to execute multiple
operations concurrently.
When ``callback`` raises an exception, ``with_transaction``
automatically aborts the current transaction. When ``callback`` or
:meth:`~ClientSession.commit_transaction` raises an exception that
includes the ``"TransientTransactionError"`` error label,
``with_transaction`` starts a new transaction and re-executes
the ``callback``.
When :meth:`~ClientSession.commit_transaction` raises an exception with
the ``"UnknownTransactionCommitResult"`` error label,
``with_transaction`` retries the commit until the result of the
transaction is known.
This method will cease retrying after 120 seconds has elapsed. This
timeout is not configurable and any exception raised by the
``callback`` or by :meth:`ClientSession.commit_transaction` after the
timeout is reached will be re-raised. Applications that desire a
different timeout duration should not use this method.
:Parameters:
- `callback`: The callable ``callback`` to run inside a transaction.
The callable must accept a single argument, this session. Note,
under certain error conditions the callback may be run multiple
times.
- `read_concern` (optional): The
:class:`~pymongo.read_concern.ReadConcern` to use for this
transaction.
- `write_concern` (optional): The
:class:`~pymongo.write_concern.WriteConcern` to use for this
transaction.
- `read_preference` (optional): The read preference to use for this
transaction. If ``None`` (the default) the :attr:`read_preference`
of this :class:`Database` is used. See
:mod:`~pymongo.read_preferences` for options.
:Returns:
The return value of the ``callback``.
.. versionadded:: 3.9