Django Subatomic

Subatomic splits Django's atomic into a suite of more specific utilities. It offers precise control over transaction logic in Django projects and transaction simulation in tests.

Installation

pip install django-subatomic

Quick comparison

Subatomic's utilities don't exactly map one-to-one to Django's transactions API, but the table below is broadly representative. See the footnotes for some nuance and the linked API docs for full details.

Desired outcome	Django	Subatomic
Create transaction	atomic()1	transaction()2
Create savepoint	atomic()1	savepoint()3
Run in a transaction	atomic()1	transaction_required()4
Fail if in a transaction	assert not connection.in_atomic_block	@durable5
Run after transaction completes	transaction.on_commit()	run_after_commit()6

Further reading

• Subatomic's features.

• The difference between transactions and savepoints.

• Problems with Django's atomic.

• Testing after-commit callbacks.

---

1. Django's atomic creates a savepoint or a transaction depending on two factors:

   • The arguments passed to it (durable= and savepoint=).
   • If a database transaction is already open.

   For more info, see Django's atomic. ↩↩↩

2. Unlike atomic, which will create a savepoint if a transaction is already open, transaction ensures the database is not already in a transaction. ↩

3. Unlike atomic, which may create a transaction, savepoint ensures the database has an active transaction. ↩

4. This ensures that some code is atomic by requiring that a transaction is already open. Unlike atomic, this never creates a transaction or a savepoint. ↩

5. This ensures that code may choose to manage its own transactions by requiring that a transaction is not already open.

   Note: This shouldn't be confused with atomic(durable=True); this never creates a transaction. ↩

6. Unlike transaction.on_commit(), this prevents misleading code by raising an error if there is no transaction open. ↩