httk.store.mongo.database
=========================

.. py:module:: httk.store.mongo.database

.. autoapi-nested-parse::

   MongoDB client lifecycle and transaction-mode probing.



Exceptions
----------

.. autoapisummary::

   httk.store.mongo.database.TransactionsUnavailableError


Classes
-------

.. autoapisummary::

   httk.store.mongo.database.MongoDatabase


Module Contents
---------------

.. py:exception:: TransactionsUnavailableError

   Bases: :py:obj:`RuntimeError`


   An explicit transaction was requested without replica-set support.


.. py:class:: MongoDatabase(client, database, *, transactions = 'auto')

   A named MongoDB database reached through a wrapped PyMongo client.

   The wrapper performs one ``hello`` probe when it is constructed.  A
   replica-set name in that reply enables transaction mode unless the caller
   explicitly pins degraded mode.

   :param client: The PyMongo client that owns the connection pool.
   :param database: The database name.
   :param transactions: ``"auto"``, ``"require"``, or ``"never"``.
   :raises ValueError: If ``transactions`` is invalid or required transactions
       are unavailable.


   .. py:method:: connect(uri, *, database, transactions = 'auto')
      :classmethod:


      Connect to a MongoDB URI with durable majority defaults.

      :param uri: MongoDB connection URI.
      :param database: Database name to expose through the wrapper.
      :param transactions: ``"auto"``, ``"require"``, or ``"never"``.
      :return: A connected database wrapper.
      :raises ValueError: If the requested transaction mode is unavailable.



   .. py:property:: client
      :type: pymongo.MongoClient


      Return the wrapped PyMongo client.

      :return: The client that owns this database connection pool.


   .. py:property:: database
      :type: Any


      Return the selected PyMongo database handle.

      :return: The PyMongo database handle.


   .. py:property:: supports_transactions
      :type: bool


      Whether this wrapper is configured to use MongoDB transactions.

      :return: ``True`` when the mode probe found a replica set and the mode
          was not pinned to ``"never"``.


   .. py:method:: dispose()

      Close the client and its connection pool.

      :return: None.