Merge pull request #81 from kraken-tech/meshy/docs/docstrings

Rework docstrings to improve generated API docs

Author: meshy

mkdocs.yml

@@ -55,5 +55,6 @@ plugins:
             show_signature_type_parameters: true
   - api-autonav:
       modules: ['src/django_subatomic']
+  - autorefs
   - search
   - mike

src/django_subatomic/db.py

@@ -33,11 +33,11 @@ def transaction(*, using: str | None = None) -> Generator[None]:
     """
     Create a database transaction.
 
+    Can be used as a decorator or a context manager.
+
     Nested calls are not allowed because SQL does not support nested transactions.
     Consider this like Django's `atomic(durable=True)`, but with added after-commit callback support in tests.
 
-    This wraps Django's 'atomic' function.
-
     Raises:
         RuntimeError: if we call this from inside another existing transaction.
     """
@@ -55,14 +55,28 @@ def transaction_if_not_already(*, using: str | None = None) -> Generator[None]:
     """
     Create a transaction if one isn't already open.
 
+    Can be used as a decorator or a context manager.
+
     Use of this hints at code which lacks control over the state it's called in.
 
-    Suggested alternatives:
+    Note:
+        This has a bit of a clunky name. This is a deliberate attempt to
+        discourage its use. It acts as a code-smell to highlight that places
+        which use it may need further work to achieve full control over how
+        transactions are managed.
+
+    Warning:
+        If this function is called when a transaction is already open, errors raised
+        through it will invalidate the current transaction, regardless of where
+        it was opened.
 
-    - In functions which should not control transactions, use `transaction_required`.
-      This ensures they are handled by the caller.
+    Tip: Suggested alternatives
+        - In functions which should not control transactions,
+          use [`transaction_required`][django_subatomic.db.transaction_required].
+          This ensures they are handled by the caller.
 
-    - In functions which can unambiguously control transactions, use `transaction`.
+        - In functions which can unambiguously control transactions,
+          use [`transaction`][django_subatomic.db.transaction].
     """
     # If the innermost atomic block is from a test case, we should create a SAVEPOINT here.
     # This allows for a rollback when an exception propagates out of this block, and so
@@ -81,21 +95,21 @@ def savepoint(*, using: str | None = None) -> Generator[None]:
     """
     Create a database savepoint.
 
-    Must be called inside an active transaction.
+    Can be used as a context manager, but _not_ as a decorator.
 
-    Tips:
+    Must be called inside an active transaction.
 
-    - You should only create a savepoint if you may roll back to it before
-      continuing with your transaction. If your intention is to ensure that
-      your code is committed atomically, consider using `transaction_required`
-      instead.
-    - We believe savepoint rollback should be handled where the savepoint is created.
-      That locality is not possible with a decorator, so this function
-      deliberately does not work as one.
+    Tip: Recommended usage
+        - You should only create a savepoint if you may roll back to it before
+          continuing with your transaction. If your intention is to ensure that
+          your code is committed atomically, consider using [`transaction_required`][django_subatomic.db.transaction_required]
+          instead.
+        - We believe savepoint rollback should be handled where the savepoint is created.
+          That locality is not possible with a decorator, so this function
+          deliberately does not work as one.
 
     Raises:
         _MissingRequiredTransaction: if we are not in a transaction
-            See Note [_MissingRequiredTransaction in tests]
     """
     with (
         transaction_required(using=using),
@@ -115,8 +129,6 @@ def transaction_required(*, using: str | None = None) -> Generator[None]:
     because we don't want to run the risk of allowing code to pass tests
     but fail in production.
 
-    See Note [_MissingRequiredTransaction in tests]
-
     Raises:
         _MissingRequiredTransaction: if we are not in a transaction.
     """
@@ -132,6 +144,8 @@ def durable[**P, R](func: Callable[P, R]) -> Callable[P, R]:
     """
     Enforce durability with this decorator.
 
+    Can be used as a decorator, but _not_ as a context manager.
+
     "Durability" means that the function's work cannot be rolled back after it completes,
     and is not to be confused with "atomicity" (which is about ensuring that the function
     either completes all its work or none of it).
@@ -307,13 +321,18 @@ def run_after_commit(
     """
     Register a callback to be called after the current transaction is committed.
 
+    (Transactions created by the test suite are deliberately ignored.)
+
     If the current transaction is rolled back, the callback will not be called.
+
     By default, an error will be raised if there is no transaction open.
-    The transaction opened by tests is ignored for this purpose.
+    While you are transitioning your codebase to stricter transaction handling,
+    you may disable this with [`settings.SUBATOMIC_AFTER_COMMIT_NEEDS_TRANSACTION`][subatomic_after_commit_needs_transaction].
 
-    Note that Django's `on_commit` has a `robust` parameter, which allows a callback to fail silently.
-    Kraken has a convention to "not allow code to fail silently"
-    so this behaviour is not available from this function.
+    Note:
+        Django's `on_commit` has a `robust` parameter, which allows a callback
+        to fail silently. Kraken has a convention to "not allow code to fail
+        silently" so this behaviour is not available from this function.
     """
     if using is None:
         using = django_db.DEFAULT_DB_ALIAS

src/django_subatomic/test.py

@@ -17,9 +17,9 @@
 @contextlib.contextmanager
 def part_of_a_transaction(using: str | None = None) -> Generator[None]:
     """
-    Allow calling `transaction_required` code without an explicit transaction.
+    Allow calling "transaction required" code without an explicit transaction.
 
-    This is useful for directly testing code marked with `db.transaction_required()`
+    This is useful for directly testing code marked with [`transaction_required`][django_subatomic.db.transaction_required]
     without going through other code which is responsible for managing a transaction.
 
     This works by entering a new "atomic" block, so that the inner-most "atomic"
@@ -30,9 +30,7 @@ def part_of_a_transaction(using: str | None = None) -> Generator[None]:
     than by calling this.
 
     Note that this does not handle after-commit callback simulation. If you need that,
-    consider using `django_subatomic.db.transaction` instead.
-
-    See Note [_MissingRequiredTransaction in tests]
+    use [`transaction`][django_subatomic.db.transaction] instead.
     """
     with transaction.atomic(using=using):
         yield