simplify + reflow docs

Author: timgraham

django_mongodb_backend/base.py

@@ -152,7 +152,9 @@ def __init__(self, settings_dict, alias=DEFAULT_DB_ALIAS):
         super().__init__(settings_dict, alias=alias)
         self.session = None
         # Tracks if the connection is in a transaction managed by
-        # django_mongodb_backend.transaction.atomic.
+        # django_mongodb_backend.transaction.atomic. `in_atomic_block` isn't
+        # used in case Django's atomic() (used internally in Django) is called
+        # within this package's atomic().
         self.in_atomic_block_mongo = False
         # Current number of nested 'atomic' calls.
         self.nested_atomics = 0
@@ -250,39 +252,46 @@ def get_database_version(self):
         """Return a tuple of the database's version."""
         return tuple(self.connection.server_info()["versionArray"])
 
-    def _start_transaction(self):
+    ## Transaction API for django_mongodb_backend.transaction.atomic()
+    @async_unsafe
+    def start_transaction_mongo(self):
         if self.session is None:
             self.session = self.connection.start_session()
             with debug_transaction(self, "session.start_transaction()"):
                 self.session.start_transaction()
 
+    @async_unsafe
     def commit_mongo(self):
         if self.session:
             with debug_transaction(self, "session.commit_transaction()"):
                 self.session.commit_transaction()
             self._end_session()
-        self.run_commit_hooks_on_set_autocommit_on = True
+        self.run_and_clear_commit_hooks()
 
     @async_unsafe
     def rollback_mongo(self):
-        """Roll back a MongoDB transaction and reset the dirty flag."""
         if self.session:
             with debug_transaction(self, "session.abort_transaction()"):
                 self.session.abort_transaction()
             self._end_session()
         self.run_on_commit = []
 
     def _end_session(self):
-        # Private API, specific to this backend.
         self.session.end_session()
         self.session = None
 
     def on_commit(self, func, robust=False):
+        """
+        Copied from BaseDatabaseWrapper.on_commit() except that it checks
+        in_atomic_block_mongo instead of in_atomic_block.
+        """
         if not callable(func):
             raise TypeError("on_commit()'s callback must be a callable.")
         if self.in_atomic_block_mongo:
             # Transaction in progress; save for execution on commit.
-            self.run_on_commit.append((set(self.savepoint_ids), func, robust))
+            # The first item in the tuple (an empty list) is normally the
+            # savepoint IDs, which isn't applicable on MongoDB.
+            self.run_on_commit.append(([], func, robust))
         else:
             # No transaction in progress; execute immediately.
             if robust:

django_mongodb_backend/transaction.py

@@ -1,36 +1,18 @@
 from contextlib import ContextDecorator
 
 from django.db import DEFAULT_DB_ALIAS, DatabaseError
-from django.db.transaction import get_connection
+from django.db.transaction import get_connection, on_commit
 
-
-def on_commit(func, using=None, robust=False):
-    """
-    Register `func` to be called when the current transaction is committed.
-    If the current transaction is rolled back, `func` will not be called.
-    """
-    get_connection(using).on_commit(func, robust)
+__all__ = [
+    "atomic",
+    "on_commit",  # convenience alias
+]
 
 
 class Atomic(ContextDecorator):
     """
     Guarantee the atomic execution of a given block.
 
-    An instance can be used either as a decorator or as a context manager.
-
-    When it's used as a decorator, __call__ wraps the execution of the
-    decorated function in the instance itself, used as a context manager.
-
-    When it's used as a context manager, __enter__ creates a transaction and
-    __exit__ commits the transaction on normal exit, and rolls back the transaction on
-    exceptions.
-
-    This allows reentrancy even if the same AtomicWrapper is reused. For
-    example, it's possible to define `oa = atomic('other')` and use `@oa` or
-    `with oa:` multiple times.
-
-    Since database connections are thread-local, this is thread-safe.
-
     Simplified from django.db.transaction.
     """
 
@@ -40,51 +22,39 @@ def __init__(self, using):
     def __enter__(self):
         connection = get_connection(self.using)
         if connection.in_atomic_block_mongo:
-            # If we're already in an atomic(), track the number of nested calls.
+            # Track the number of nested atomic() calls.
             connection.nested_atomics += 1
         else:
             # Start a transaction for the outermost atomic().
-            connection._start_transaction()
+            connection.start_transaction_mongo()
             connection.in_atomic_block_mongo = True
 
     def __exit__(self, exc_type, exc_value, traceback):
         connection = get_connection(self.using)
         if connection.nested_atomics:
+            # Exiting inner atomic.
             connection.nested_atomics -= 1
         else:
+            # Reset flag when exiting outer atomic.
             connection.in_atomic_block_mongo = False
-        try:
-            if exc_type is None:
-                # atomic() exited without an error.
-                if connection.in_atomic_block_mongo:
-                    # Do nothing for an inner atomic().
-                    pass
-                else:
-                    # Commit transaction.
-                    try:
-                        connection.commit_mongo()
-                    except DatabaseError:
-                        connection.rollback_mongo()
-            else:
-                # atomic() exited with an error.
-                if connection.in_atomic_block_mongo:
-                    # Do nothing for an inner atomic().
-                    pass
-                else:
-                    # Rollback transaction.
+        if exc_type is None:
+            # atomic() exited without an error.
+            if not connection.in_atomic_block_mongo:
+                # Commit transaction if outer atomic().
+                try:
+                    connection.commit_mongo()
+                except DatabaseError:
                     connection.rollback_mongo()
-        finally:
-            if (
-                not connection.in_atomic_block_mongo
-                and connection.run_commit_hooks_on_set_autocommit_on
-            ):
-                # Run on_commit() callbacks after outermost atomic()
-                connection.run_and_clear_commit_hooks()
+        else:
+            # atomic() exited with an error.
+            if connection.in_atomic_block_mongo:
+                # Rollback transaction if outer atomic().
+                connection.rollback_mongo()
 
 
 def atomic(using=None):
-    # Bare decorator: @atomic -- although the first argument is called `using`, it's
-    # actually the function being decorated.
+    # Bare decorator: @atomic -- although the first argument is called `using`,
+    # it's actually the function being decorated.
     if callable(using):
         return Atomic(DEFAULT_DB_ALIAS)(using)
     # Decorator: @atomic(...) or context manager: with atomic(...): ...

docs/source/topics/transactions.rst

@@ -6,41 +6,45 @@ Transactions
 
 .. module:: django_mongodb_backend.transaction
 
-MongoDB supports :doc:`transactions <manual:core/transactions>` if it's configured as a
-:doc:`replica set <manual:replication>` or a :doc:`sharded cluster <manual:sharding>`.
+MongoDB supports :doc:`transactions <manual:core/transactions>` if it's
+configured as a :doc:`replica set <manual:replication>` or a :doc:`sharded
+cluster <manual:sharding>`.
 
-Because MongoDB transactions have some limitations and are not meant to be used as
-freely as SQL transactions, :doc:`Django's transactions APIs
+Because MongoDB transactions have some limitations and are not meant to be used
+as freely as SQL transactions, :doc:`Django's transactions APIs
 <django:topics/db/transactions>`, including most notably
 :func:`django.db.transaction.atomic`, function as no-ops.
 
 Instead, Django MongoDB Backend provides its own
 :func:`django_mongodb_backend.transaction.atomic` function.
 
-Outside of a transaction, query execution uses Django and MongoDB's default behavior of
-autocommit mode. Each query is immediately committed to the database.
+Outside of a transaction, query execution uses Django and MongoDB's default
+behavior of autocommit mode. Each query is immediately committed to the
+database.
 
 Controlling transactions
 ========================
 
 .. function:: atomic(using=None)
 
-    Atomicity is the defining property of database transactions. ``atomic`` allows
-    creating a block of code within which the atomicity on the database is guaranteed.
-    If the block of code is successfully completed, the changes are committed to the
-    database. If there is an exception, the changes are rolled back.
+    Atomicity is the defining property of database transactions. ``atomic``
+    allows creating a block of code within which the atomicity on the database
+    is guaranteed. If the block of code is successfully completed, the changes
+    are committed to the database. If there is an exception, the changes are
+    rolled back.
 
-    On databases that support savepoints, ``atomic`` blocks can be nested, such that
-    the outermost ``atomic`` starts a transaction and inner ``atomic``\s create
-    savepoints. Since MongoDB doesn't support savepoints, inner ``atomic`` blocks
-    don't have any effect. The transaction commits once the outermost ``atomic`` exits.
+    On databases that support savepoints, ``atomic`` blocks can be nested, such
+    that the outermost ``atomic`` starts a transaction and inner ``atomic``\s
+    create savepoints. Since MongoDB doesn't support savepoints, inner
+    ``atomic`` blocks don't have any effect. The transaction commits once the
+    outermost ``atomic`` exits.
 
     ``atomic`` is usable both as a :py:term:`decorator`::
 
         from django_mongodb_backend import transaction
 
 
-        @atomic
+        @transaction.atomic
         def viewfunc(request):
             # This code executes inside a transaction.
             do_stuff()
@@ -54,31 +58,32 @@ Controlling transactions
             # This code executes in autocommit mode (Django's default).
             do_stuff()
 
-            with atomic():
+            with transaction.atomic():
                 # This code executes inside a transaction.
                 do_more_stuff()
 
     .. admonition:: Avoid catching exceptions inside ``atomic``!
 
-        When exiting an ``atomic`` block, Django looks at whether it's exited normally
-        or with an exception to determine whether to commit or roll back. If you catch
-        and handle exceptions inside an ``atomic`` block, you may hide from Django the
-        fact that a problem has happened. This can result in unexpected behavior.
+        When exiting an ``atomic`` block, Django looks at whether it's exited
+        normally or with an exception to determine whether to commit or roll
+        back. If you catch and handle exceptions inside an ``atomic`` block,
+        you may hide from Django the fact that a problem has happened. This can
+        result in unexpected behavior.
 
-        This is mostly a concern for :exc:`~django.db.DatabaseError` and its subclasses
-        such as :exc:`~django.db.IntegrityError`. After such an error, the transaction
-        is broken and Django will perform a rollback at the end of the ``atomic``
-        block.
+        This is mostly a concern for :exc:`~django.db.DatabaseError` and its
+        subclasses such as :exc:`~django.db.IntegrityError`. After such an
+        error, the transaction is broken and Django will perform a rollback at
+        the end of the ``atomic`` block.
 
     .. admonition:: You may need to manually revert app state when rolling back a transaction.
 
-        The values of a model's fields won't be reverted when a transaction rollback
-        happens. This could lead to an inconsistent model state unless you manually
-        restore the original field values.
+        The values of a model's fields won't be reverted when a transaction
+        rollback happens. This could lead to an inconsistent model state unless
+        you manually restore the original field values.
 
-        For example, given ``MyModel`` with an ``active`` field, this snippet ensures
-        that the ``if obj.active`` check at the end uses the correct value if updating
-        ``active`` to ``True`` fails in the transaction::
+        For example, given ``MyModel`` with an ``active`` field, this snippet
+        ensures that the ``if obj.active`` check at the end uses the correct
+        value if updating ``active`` to ``True`` fails in the transaction::
 
             from django_mongodb_backend import transaction
             from django.db import DatabaseError
@@ -94,11 +99,12 @@ Controlling transactions
             if obj.active:
                 ...
 
-        This also applies to any other mechanism that may hold app state, such as
-        caching or global variables. For example, if the code proactively updates data
-        in the cache after saving an object, it's recommended to use
-        :ref:`transaction.on_commit() <performing-actions-after-commit>` instead, to
-        defer cache alterations until the transaction is actually committed.
+        This also applies to any other mechanism that may hold app state, such
+        as caching or global variables. For example, if the code proactively
+        updates data in the cache after saving an object, it's recommended to
+        use :ref:`transaction.on_commit() <performing-actions-after-commit>`
+        instead, to defer cache alterations until the transaction is actually
+        committed.
 
     ``atomic`` takes a ``using`` argument which should be the name of a
     database. If this argument isn't provided, Django uses the ``"default"``
@@ -111,17 +117,27 @@ Controlling transactions
 
 .. admonition:: Performance considerations
 
-    Open transactions have a performance cost for your database server. To minimize
-    this overhead, keep your transactions as short as possible. This is especially
-    important if you're using :func:`atomic` in long-running processes, outside of
-    Django's request / response cycle.
+    Open transactions have a performance cost for your database server. To
+    minimize this overhead, keep your transactions as short as possible. This
+    is especially important if you're using :func:`atomic` in long-running
+    processes, outside of Django's request / response cycle.
 
 Performing actions after commit
 ===============================
 
-The :func:`atomic` function supports Django's :func:`~django.db.transaction.on_commit`
-API to :ref:`perform actions after a transaction successfully commits
-<performing-actions-after-commit>`.
+The :func:`atomic` function supports Django's
+:func:`~django.db.transaction.on_commit` API to :ref:`perform actions after a
+transaction successfully commits <performing-actions-after-commit>`.
+
+For convenience, :func:`~django.db.transaction.on_commit` is aliased at
+``django_mongodb_backend.transaction.on_commit`` so you can use both::
+
+    from django_mongodb_backend import transaction
+
+
+    transaction.atomic()
+    transaction.on_commit(...)
+
 
 .. _transactions-limitations:
 
@@ -132,17 +148,7 @@ MongoDB's transaction limitations that are applicable to Django are:
 
 - :meth:`QuerySet.union() <django.db.models.query.QuerySet.union>` is not
   supported inside a transaction.
-- If a transaction raises an exception, the transaction is no longer usable.
-  For example, if the update stage of :meth:`QuerySet.update_or_create()
-  <django.db.models.query.QuerySet.update_or_create>` fails with
-  :class:`~django.db.IntegrityError` due to a unique constraint violation, the
-  create stage won't be able to proceed.
-  :class:`pymongo.errors.OperationFailure` is raised, wrapped by
-  :class:`django.db.DatabaseError`.
 - Savepoints (i.e. nested :func:`~django.db.transaction.atomic` blocks) aren't
   supported. The outermost :func:`~django.db.transaction.atomic` will start
   a transaction while any subsequent :func:`~django.db.transaction.atomic`
   blocks will have no effect.
-- Migration operations aren't :ref:`wrapped in a transaction
-  <topics/migrations:transactions>` because of MongoDB restrictions such as
-  adding indexes to existing collections while in a transaction.