`MotorClientSession` – Sequence of operations¶

Warning

As of May 14th, 2025, Motor is deprecated in favor of the GA release of the PyMongo Async API. No new features will be added to Motor, and only bug fixes will be provided until it reaches end of life on May 14th, 2026. After that, only critical bug fixes will be made until final support ends on May 14th, 2027. We strongly recommend migrating to the PyMongo Async API while Motor is still supported. For help transitioning, see the Migrate to PyMongo Async guide.

class motor.motor_tornado.MotorClientSession(delegate, motor_client)¶

coroutine abort_transaction() → None¶: Abort a multi-statement transaction.

coroutine commit_transaction() → None¶: Commit a multi-statement transaction.

coroutine end_session() → None¶

Finish this session. If a transaction has started, abort it.

It is an error to use the session after the session has ended.

start_transaction(read_concern=None, write_concern=None, read_preference=None, max_commit_time_ms=None)¶

Start a multi-statement transaction.

Takes the same arguments as TransactionOptions.

Best used in a context manager block:

# Use "await" for start_session, but not for start_transaction.
async with await client.start_session() as s:
    async with s.start_transaction():
        await collection.delete_one({"x": 1}, session=s)
        await collection.insert_one({"x": 2}, session=s)

async with_transaction(coro, read_concern=None, write_concern=None, read_preference=None, max_commit_time_ms=None)¶

Executes an awaitable in a transaction.

This method starts a transaction on this session, awaits coro once, and then commits the transaction. For example:

async def coro(session):
    orders = session.client.db.orders
    inventory = session.client.db.inventory
    inserted_id = await orders.insert_one(
        {"sku": "abc123", "qty": 100}, session=session)
    await inventory.update_one(
        {"sku": "abc123", "qty": {"$gte": 100}},
        {"$inc": {"qty": -100}}, session=session)
    return inserted_id

async with await client.start_session() as session:
    inserted_id = await session.with_transaction(coro)

To pass arbitrary arguments to the coro, wrap it with a lambda like this:

async def coro(session, custom_arg, custom_kwarg=None):
    # Transaction operations...

async with await client.start_session() as session:
    await session.with_transaction(
        lambda s: coro(s, "custom_arg", custom_kwarg=1))

In the event of an exception, with_transaction may retry the commit or the entire transaction, therefore coro may be awaited multiple times by a single call to with_transaction. Developers should be mindful of this possibility when writing a coro that modifies application state or has any other side-effects. Note that even when the coro is invoked multiple times, with_transaction ensures that the transaction will be committed at-most-once on the server.

The coro should not attempt to start new transactions, but should simply run operations meant to be contained within a transaction. The coro should also not commit the transaction; this is handled automatically by with_transaction. If the coro does commit or abort the transaction without error, however, with_transaction will return without taking further action.

When coro raises an exception, with_transaction automatically aborts the current transaction. When coro or commit_transaction() raises an exception that includes the "TransientTransactionError" error label, with_transaction starts a new transaction and re-executes the coro.

When 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 coro or by 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:

coro: The coroutine to run inside a transaction. The coroutine must accept a single argument, this session. Note, under certain error conditions the coroutine may be run multiple times.
read_concern (optional): The ReadConcern to use for this transaction.
write_concern (optional): The WriteConcern to use for this transaction.
read_preference (optional): The read preference to use for this transaction. If None (the default) the read_preference of this Database is used. See read_preferences for options.

Returns:

The return value of the coro.

Added in version 2.1.

property advance_cluster_time¶

Update the cluster time for this session.

Parameters:: cluster_time – The cluster_time from another ClientSession instance.

property advance_operation_time¶

Update the operation time for this session.

Parameters:: operation_time – The operation_time from another ClientSession instance.

property client¶: The MotorClient this session was created from.

property cluster_time¶: The cluster time returned by the last operation executed in this session.

property has_ended¶: True if this session is finished.

property in_transaction¶: True if this session has an active multi-statement transaction.

Added in version 3.10.

property operation_time¶: The operation time returned by the last operation executed in this session.

property options¶: The SessionOptions this session was created with.

property session_id¶: A BSON document, the opaque server session identifier.

MotorClientSession – Sequence of operations¶

`MotorClientSession` – Sequence of operations¶