OpenQuizz
Une application de gestion des contenus pédagogiques
ClientSession Class Reference
Inheritance diagram for ClientSession:
Collaboration diagram for ClientSession:

Public Member Functions

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)
 

Detailed Description

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`.

Constructor & Destructor Documentation

◆ __init__()

def __init__ (   self,
  client,
  server_session,
  options,
  authset,
  implicit 
)

Member Function Documentation

◆ __enter__()

def __enter__ (   self)

◆ __exit__()

def __exit__ (   self,
  exc_type,
  exc_val,
  exc_tb 
)

◆ abort_transaction()

def abort_transaction (   self)
Abort a multi-statement transaction.

.. versionadded:: 3.7

◆ advance_cluster_time()

def advance_cluster_time (   self,
  cluster_time 
)
Update the cluster time for this session.

:Parameters:
  - `cluster_time`: The
    :data:`~pymongo.client_session.ClientSession.cluster_time` from
    another `ClientSession` instance.

◆ advance_operation_time()

def advance_operation_time (   self,
  operation_time 
)
Update the operation time for this session.

:Parameters:
  - `operation_time`: The
    :data:`~pymongo.client_session.ClientSession.operation_time` from
    another `ClientSession` instance.

◆ client()

def client (   self)
The :class:`~pymongo.mongo_client.MongoClient` this session was
created from.

◆ cluster_time()

def cluster_time (   self)
The cluster time returned by the last operation executed
in this session.

◆ commit_transaction()

def commit_transaction (   self)
Commit a multi-statement transaction.

.. versionadded:: 3.7

◆ end_session()

def end_session (   self)
Finish this session. If a transaction has started, abort it.

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

◆ has_ended()

def has_ended (   self)
True if this session is finished.

◆ in_transaction()

def in_transaction (   self)
True if this session has an active multi-statement transaction.

.. versionadded:: 3.10

◆ operation_time()

def operation_time (   self)
The operation time returned by the last operation executed
in this session.

◆ options()

def options (   self)
The :class:`SessionOptions` this session was created with.

◆ session_id()

def session_id (   self)
A BSON document, the opaque server session identifier.

◆ start_transaction()

def start_transaction (   self,
  read_concern = None,
  write_concern = None,
  read_preference = None,
  max_commit_time_ms = None 
)
Start a multi-statement transaction.

Takes the same arguments as :class:`TransactionOptions`.

.. versionchanged:: 3.9
   Added the ``max_commit_time_ms`` option.

.. versionadded:: 3.7

◆ with_transaction()

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

The documentation for this class was generated from the following file: