django-phase 0.1.0__py3-none-any.whl

django_phase-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: django-phase
+Version: 0.1.0
+Summary: Race-safe state machines for Django models: a protected PhaseField and transitions as one conditional UPDATE
+Project-URL: Homepage, https://github.com/beyonder-deutschland/django-phase/
+Project-URL: Documentation, https://django-phase.readthedocs.io/en/latest/index.html
+Project-URL: Maintained by, https://beyonder.de/
+Project-URL: Bugtracker, https://github.com/beyonder-deutschland/django-phase/issues
+Project-URL: Changelog, https://django-phase.readthedocs.io/en/latest/features/changelog.html
+Author-email: Beyonder Deutschland <hello@beyonder.de>
+License: MIT License
+        
+        Copyright (c) 2026 Beyonder Deutschland GmbH
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: django>=5.2
+Provides-Extra: dev
+Requires-Dist: ambient-package-update; extra == 'dev'
+Requires-Dist: keyring~=25.7; extra == 'dev'
+Requires-Dist: pre-commit~=4.7; extra == 'dev'
+Requires-Dist: pytest-cov~=7.1; extra == 'dev'
+Requires-Dist: pytest-django~=4.14; extra == 'dev'
+Requires-Dist: pytest-mock~=3.17; extra == 'dev'
+Requires-Dist: sphinx-mdinclude~=0.6; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme~=3.1; extra == 'dev'
+Requires-Dist: sphinx~=8.2; extra == 'dev'
+Requires-Dist: typer~=0.27; extra == 'dev'
+Requires-Dist: uv~=0.13; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![PyPI release](https://img.shields.io/pypi/v/django-phase.svg)](https://pypi.org/project/django-phase/)
+[![Downloads](https://static.pepy.tech/badge/django-phase)](https://pepy.tech/project/django-phase)
+[![Coverage](https://img.shields.io/badge/Coverage-100.0%25-success)](https://github.com/beyonder-deutschland/django-phase/actions?workflow=CI)
+[![Linting](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Coding Style](https://img.shields.io/badge/code%20style-Ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Documentation Status](https://readthedocs.org/projects/django-phase/badge/?version=latest)](https://django-phase.readthedocs.io/en/latest/?badge=latest)
+
+Race-safe state machines for Django models: a protected `PhaseField`, transitions as one conditional `UPDATE`, and
+guards that tell humans and machines why an action was refused.
+
+[PyPI](https://pypi.org/project/django-phase/) • [GitHub](https://github.com/beyonder-deutschland/django-phase) • [Full documentation](https://django-phase.readthedocs.io/en/latest/index.html)
+
+Creator & Maintainer: [Beyonder Deutschland](https://beyonder.de/)
+
+## Features
+
+* Declare the allowed transitions once, as a table on the field
+* Assigning the phase directly raises; only `move()` changes it
+* `move()` writes phase and further fields in **one** conditional `UPDATE`, so of two concurrent transitions from the
+  same phase exactly one succeeds
+* Every `save()` is guarded against a stale phase, so it can't silently undo a concurrent transition
+* Migrations see a plain `CharField` and never import `phase`
+* System checks catch a missing mixin, a second phase field or one inherited from a concrete parent model
+* `PhaseGuardError` gives refused actions a stable `code` for machines and a `detail` for humans
+* Overrides no private Django method
+
+```python
+from django.db import models
+from django.utils import timezone
+
+from phase.fields import PhaseField
+from phase.mixins.phase_guard import PhaseGuardMixin
+from phase.transitions import move
+
+
+class Order(PhaseGuardMixin, models.Model):
+    class Status(models.TextChoices):
+        OPEN = "open"
+        PAID = "paid"
+        SHIPPED = "shipped"
+        CANCELLED = "cancelled"
+
+    status = PhaseField(
+        max_length=10,
+        choices=Status.choices,
+        default=Status.OPEN,
+        transitions={
+            Status.OPEN: (Status.PAID, Status.CANCELLED),
+            Status.PAID: (Status.SHIPPED,),
+        },
+    )
+    paid_at = models.DateTimeField(null=True, blank=True)
+
+
+order = Order.objects.create()
+move(obj=order, to=Order.Status.PAID, paid_at=timezone.now())
+
+order.status = Order.Status.OPEN  # raises ProtectedPhaseFieldError
+move(obj=order, to=Order.Status.OPEN)  # raises IllegalPhaseTransitionError
+```
+
+## Installation
+
+- Install the package via pip:
+
+  `pip install django_phase`
+
+  or via uv:
+
+  `uv add django_phase`
+
+- Add module to `INSTALLED_APPS` within the main django `settings.py`:
+
+```python
+INSTALLED_APPS = (
+    # ...
+    "phase",
+)
+```
+
+## Releasing a new version
+
+Releases are fully automated. Push a version tag and the pipeline will build, sign with
+[Sigstore](https://www.sigstore.dev/), publish to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/), and create a GitHub Release —
+no API tokens needed.
+
+```bash
+git tag v<version>          # e.g. git tag v1.2.3
+git push origin v<version>
+```
+
+Tags **must** start with `v`. Tags without the prefix won't trigger the pipeline.
+
+### First-time setup
+
+Before the pipeline can run for the first time, an admin must:
+
+1. **Create GitHub Environment `pypi`**
+   - Go to *Settings → Environments → New environment*, name it exactly `pypi`
+   - Under *Deployment branches and tags*, add a tag rule with pattern `v*`
+   - Optionally add required reviewers for a manual approval gate
+
+2. **Configure PyPI Trusted Publisher**
+   - Go to *PyPI → Project settings → Publishing → Add a new publisher*
+   - Fill in: Owner `beyonder-deutschland`, Repository `django-phase`,
+     Workflow `release.yml`, Environment `pypi`
+
+### Publish to ReadTheDocs.io
+
+- Fetch the latest changes in GitHub mirror and push them
+- Trigger new build at ReadTheDocs.io (follow instructions in admin panel at RTD) if the GitHub webhook is not yet set
+  up.
+
+### Maintenance
+
+Please note that this package supports the [ambient-package-update](https://pypi.org/project/ambient-package-update/).
+So you don't have to worry about the maintenance of this package. This updater is rendering all important
+configuration and setup files. It works similar to well-known updaters like `pyupgrade` or `django-upgrade`.
+
+To run an update, refer to the [documentation page](https://pypi.org/project/ambient-package-update/)
+of the "ambient-package-update".

django_phase-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+phase/__init__.py,sha256=JnIHCWjHzrgr1bkK6AvjLOxNeE1aYICkL57oSOLJmiI,138
+phase/apps.py,sha256=xLVNKm3jHfvxOgqJKnJYBeCzToaly7DgKUFG_1Y43AQ,258
+phase/checks.py,sha256=njuvHSJEXGDddSwmM2-gFap7E7eWMXUPylzk2wXwgMo,2438
+phase/exceptions.py,sha256=M0Gd9tJD5ar4rqn62wAc4i0KNXRxn5dqy7KXuAuBItc,4074
+phase/fields.py,sha256=k6BJN7ideFY0pB5G_O_q-_e9Iy8daW00XeByAe7vFhM,8224
+phase/transitions.py,sha256=XvzMEsRLCZV1lNBJuiA11vmSPAYvr76Sg8bet62eDOY,572
+phase/mixins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+phase/mixins/phase_guard.py,sha256=hcygbhETdglz06Y7mo-vJmCntLur8O7IaYU7nENE4pY,2965
+django_phase-0.1.0.dist-info/METADATA,sha256=v7VKCSRwfpegDSKK7eeBiiETyx-hBl0CCiNRRZgdBsM,8197
+django_phase-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+django_phase-0.1.0.dist-info/licenses/LICENSE.md,sha256=b7UhMFD7Rhj2PPUk0Pqg815sqtLOvZFUcM8nTsiBf7k,1082
+django_phase-0.1.0.dist-info/RECORD,,

django_phase-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_phase-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beyonder Deutschland GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phase/__init__.py

@@ -0,0 +1,3 @@
+"""Race-safe state machines for Django models: a protected PhaseField and transitions as one conditional UPDATE"""
+
+__version__ = "0.1.0"

phase/apps.py

@@ -0,0 +1,9 @@
+from django.apps import AppConfig
+
+
+class PhaseConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "phase"
+
+    def ready(self) -> None:
+        from phase import checks  # noqa: F401, PLC0415 - registers the system checks

phase/checks.py

@@ -0,0 +1,57 @@
+from itertools import chain
+
+from django.apps import AppConfig, apps
+from django.core import checks
+
+from phase.fields import get_phase_fields
+from phase.mixins.phase_guard import PhaseGuardMixin
+
+
+@checks.register(checks.Tags.models)
+def check_phase_fields(app_configs: list[AppConfig] | None = None, **kwargs: object) -> list[checks.Error]:
+    """
+    Every model with a PhaseField inherits PhaseGuardMixin, has exactly one PhaseField and stores it in its own table.
+
+    Without the mixin the model can't be reloaded, because the field refuses the second assignment. With two phase
+    fields `phase.transitions.move()` couldn't tell which one to move. A phase field in the table of a concrete parent
+    makes Django split the UPDATE of `move()` into a SELECT of the primary keys and an UPDATE without the condition on
+    the phase, so two concurrent transitions could both succeed. Proxy models share their concrete model's fields and
+    are reported there.
+    """
+    if app_configs is None:
+        models = apps.get_models()
+    else:
+        models = chain.from_iterable(app_config.get_models() for app_config in app_configs)
+
+    errors = []
+    for model in models:
+        if model._meta.proxy:
+            continue
+        phase_fields = get_phase_fields(model=model)
+        if phase_fields and not issubclass(model, PhaseGuardMixin):
+            errors.append(
+                checks.Error(
+                    f"{model._meta.label} has a PhaseField but doesn't inherit from PhaseGuardMixin.",
+                    obj=model,
+                    id="phase.E001",
+                )
+            )
+        if len(phase_fields) > 1:
+            errors.append(
+                checks.Error(
+                    f"{model._meta.label} has more than one PhaseField.",
+                    hint="A model has one lifecycle; a second one usually belongs on its own model.",
+                    obj=model,
+                    id="phase.E002",
+                )
+            )
+        if any(field.model is not model for field in phase_fields):
+            errors.append(
+                checks.Error(
+                    f"{model._meta.label} inherits its PhaseField from a concrete parent model.",
+                    hint="Make the parent abstract, or give the lifecycle its own model without concrete children.",
+                    obj=model,
+                    id="phase.E003",
+                )
+            )
+    return errors

phase/exceptions.py

@@ -0,0 +1,96 @@
+class IllegalPhaseTransitionError(Exception):
+    """
+    The transition isn't in the table, or the row changed or vanished since `obj` was loaded.
+
+    `source` is the phase in the database when the row changed in the meantime, and `None` when the row doesn't exist.
+    """
+
+    def __init__(self, *, model_name: str, pk: int | None, source: str | None, target: str):
+        self.model_name = model_name
+        self.pk = pk
+        self.source = source
+        self.target = target
+        if source is None:
+            message = f"{model_name} ID #{pk} doesn't exist in the database and cannot change to '{target}'."
+        else:
+            message = f"{model_name} ID #{pk} cannot change from '{source}' to '{target}'."
+        super().__init__(message)
+
+    def __reduce__(self) -> tuple:
+        # The parallel test runner sends failures between processes; the default reduce calls __init__ positionally.
+        return _rebuild_illegal_phase_transition_error, (self.model_name, self.pk, self.source, self.target)
+
+
+def _rebuild_illegal_phase_transition_error(
+    model_name: str, pk: int | None, source: str | None, target: str
+) -> IllegalPhaseTransitionError:
+    return IllegalPhaseTransitionError(model_name=model_name, pk=pk, source=source, target=target)
+
+
+class StalePhaseError(Exception):
+    def __init__(self, *, model_name: str, pk: int, phases: dict[str, str]):
+        self.model_name = model_name
+        self.pk = pk
+        self.phases = phases
+        loaded = ", ".join(f"{field}='{phase}'" for field, phase in phases.items())
+        super().__init__(f"{model_name} ID #{pk} no longer has {loaded} in the database; reload it before saving.")
+
+    def __reduce__(self) -> tuple:
+        return _rebuild_stale_phase_error, (self.model_name, self.pk, self.phases)
+
+
+def _rebuild_stale_phase_error(model_name: str, pk: int, phases: dict[str, str]) -> StalePhaseError:
+    return StalePhaseError(model_name=model_name, pk=pk, phases=phases)
+
+
+class RebuiltWithoutInitMixin:
+    """
+    Pickle an exception whose constructor takes keyword arguments.
+
+    The default reduce calls `__init__` positionally with the message, which such a constructor refuses. The copy is
+    rebuilt from message and attributes instead, so it works for any constructor signature a subclass defines.
+    """
+
+    def __reduce__(self) -> tuple:
+        return _rebuild_without_init, (type(self), self.args, dict(self.__dict__))
+
+
+def _rebuild_without_init(error_class: type[BaseException], args: tuple, attributes: dict) -> BaseException:
+    error = error_class.__new__(error_class)
+    error.args = args
+    error.__dict__.update(attributes)
+    return error
+
+
+class PhaseGuardError(RebuiltWithoutInitMixin, Exception):
+    """
+    An action refuses to run because a condition on the current phase beyond the transition table isn't met.
+
+    Every guard is its own subclass with a stable `code` for machines and a `detail` for humans, which tells the user
+    why the action was refused and what to do next. `phase` doesn't translate; the subclass passes a translated text.
+    The message given to the constructor is meant for logs and may contain IDs. A subclass is free in its constructor
+    signature and stays picklable.
+    """
+
+    code: str
+    detail: str
+
+
+class ProtectedPhaseFieldError(RebuiltWithoutInitMixin, AttributeError):
+    def __init__(self, *, field_name: str):
+        super().__init__(f"'{field_name}' is a phase field and can only change through a transition.")
+
+
+class EditablePhaseFieldError(TypeError):
+    def __init__(self, *args):
+        super().__init__("A PhaseField can't be editable; its value only changes through a transition.")
+
+
+class InvalidTransitionTableError(RebuiltWithoutInitMixin, TypeError):
+    def __init__(self, *, source: str):
+        super().__init__(f"Targets of phase '{source}' must be a tuple, e.g. ('declined',) for a single target.")
+
+
+class MissingPhaseFieldError(RebuiltWithoutInitMixin, TypeError):
+    def __init__(self, *, model_name: str):
+        super().__init__(f"{model_name} has no PhaseField.")

phase/fields.py

@@ -0,0 +1,174 @@
+from collections.abc import Mapping
+
+from django.db import models, router
+from django.db.models import signals
+from django.db.models.query_utils import DeferredAttribute
+
+from phase.exceptions import (
+    EditablePhaseFieldError,
+    IllegalPhaseTransitionError,
+    InvalidTransitionTableError,
+    MissingPhaseFieldError,
+    ProtectedPhaseFieldError,
+)
+
+# Set on the instance while `PhaseGuardMixin.refresh_from_db()` runs, so the reload may overwrite the phase.
+REFRESHING_FLAG = "_phase_field_refreshing"
+
+
+class ProtectedPhaseDescriptor(DeferredAttribute):
+    """
+    Allow a phase value to be set once per instance, refuse every later assignment.
+
+    Django sets field values with `setattr` when it builds an instance (constructor, loading from the database) and
+    when it fetches a deferred field; in all these cases the instance holds no value yet. A reload through
+    `PhaseGuardMixin.refresh_from_db()` may overwrite it, because it writes what the database holds. So may Django
+    after an INSERT, when it replaces an expression such as a `db_default` with the value the database returned.
+
+    Assigning the value the instance already holds changes nothing and passes. Django does that in
+    `Model.clean_fields()` and when it writes back the columns an INSERT returned.
+    """
+
+    def __set__(self, instance: models.Model, value: str) -> None:
+        if (
+            self.field.attname in instance.__dict__
+            and not instance.__dict__.get(REFRESHING_FLAG)
+            and not is_expression(instance.__dict__[self.field.attname])
+            and instance.__dict__[self.field.attname] != value
+        ):
+            raise ProtectedPhaseFieldError(field_name=self.field.attname)
+        instance.__dict__[self.field.attname] = value
+
+
+def is_expression(value: object) -> bool:
+    """A placeholder the database resolves, e.g. `DatabaseDefault` for a field with `db_default` before the INSERT."""
+    return hasattr(value, "resolve_expression")
+
+
+class PhaseField(models.CharField):
+    """
+    A CharField whose value only changes along `transitions`, via `move()`.
+
+    A phase missing from `transitions` is final. `move()` writes with a conditional UPDATE on the source phase, so two
+    concurrent transitions from the same phase cannot both succeed: the second one updates no row and is rejected like
+    any other illegal transition.
+
+    The field is never editable: admin and model forms leave it out, because saving a form would assign it directly.
+    """
+
+    descriptor_class = ProtectedPhaseDescriptor
+
+    def __init__(self, *args: object, transitions: Mapping[str, tuple[str, ...]], **kwargs: object) -> None:
+        # `(DECLINED)` without a trailing comma is a plain string, and `in` on a string matches substrings.
+        for source, targets in transitions.items():
+            if not isinstance(targets, tuple):
+                raise InvalidTransitionTableError(source=source)
+        if kwargs.get("editable", False):
+            raise EditablePhaseFieldError
+        kwargs["editable"] = False
+        self.transitions = transitions
+        super().__init__(*args, **kwargs)
+
+    def deconstruct(self) -> tuple:
+        # Migrations see a plain CharField: the table and the editability are behaviour, not schema, and must not pin
+        # migrations to phase.
+        name, _, args, kwargs = super().deconstruct()
+        kwargs.pop("editable", None)
+        return name, "django.db.models.CharField", args, kwargs
+
+    def clone(self) -> "PhaseField":
+        # Field.clone() rebuilds from deconstruct(), which drops the table on purpose; the clone still needs it.
+        _, _, args, kwargs = self.deconstruct()
+        return self.__class__(*args, transitions=self.transitions, **kwargs)
+
+    def targets(self, *, obj: models.Model) -> tuple[str, ...]:
+        return self.transitions.get(getattr(obj, self.attname), ())
+
+    def can_transition(self, *, obj: models.Model, to: str) -> bool:
+        return to in self.targets(obj=obj)
+
+    def move(self, *, obj: models.Model, to: str, **fields: object) -> None:
+        """
+        Move `obj` to phase `to` and write `fields` and the model's `auto_now` fields in the same UPDATE.
+
+        Towards signals this behaves like `obj.save(update_fields=[<phase>, *fields, *<auto_now fields>])`: `pre_save`
+        sees the new values on `obj` and may change those fields, `post_save` follows a successful UPDATE.
+
+        On success `obj` is refreshed, so field values given as expressions are read back as stored values. On failure
+        `obj` stays as it was: its phase no longer matches the database, so a later `save()` is refused as stale
+        instead of overwriting what the winner of a race wrote.
+        """
+        model = type(obj)
+        using = router.db_for_write(model, instance=obj)
+        rows = model._base_manager.using(using).filter(pk=obj.pk)
+
+        source = getattr(obj, self.attname)
+        if is_expression(source):
+            # On Django 5.2 a backend without INSERT … RETURNING leaves the `db_default` placeholder on the instance.
+            source = rows.values_list(self.attname, flat=True).first()
+            if source is not None:
+                obj.__dict__[self.attname] = source
+        if to not in self.transitions.get(source, ()):
+            raise IllegalPhaseTransitionError(model_name=obj._meta.label, pk=obj.pk, source=source, target=to)
+
+        written_fields = self._written_fields(obj=obj, fields=fields)
+        update_fields = frozenset(field.name for field in written_fields)
+
+        loaded_state = (dict(obj.__dict__), dict(obj._state.fields_cache))
+        try:
+            obj.__dict__[self.attname] = to
+            for name, value in fields.items():
+                setattr(obj, name, value)
+            signals.pre_save.send(sender=model, instance=obj, raw=False, using=using, update_fields=update_fields)
+            # Like `save()`: values are read after `pre_save`, and `Field.pre_save()` stamps the `auto_now` fields.
+            values = {field.attname: field.pre_save(obj, add=False) for field in written_fields}
+            updated_rows = rows.filter(**{self.attname: source}).update(**values)
+        except BaseException:
+            self._restore(obj=obj, loaded_state=loaded_state)
+            raise
+        if not updated_rows:
+            self._restore(obj=obj, loaded_state=loaded_state)
+            raise IllegalPhaseTransitionError(
+                model_name=obj._meta.label,
+                pk=obj.pk,
+                source=rows.values_list(self.attname, flat=True).first(),
+                target=to,
+            )
+
+        obj.refresh_from_db(using=using, fields=[field.attname for field in written_fields])
+        signals.post_save.send(
+            sender=model, instance=obj, created=False, update_fields=update_fields, raw=False, using=using
+        )
+
+    def _written_fields(self, *, obj: models.Model, fields: Mapping[str, object]) -> list[models.Field]:
+        """The phase, `fields` and the `auto_now` fields not among them, as `save(update_fields=…)` would write them."""
+        written_fields = [self, *(obj._meta.get_field(name) for name in fields)]
+        written_fields += [
+            field
+            for field in obj._meta.concrete_fields
+            if getattr(field, "auto_now", False) and field not in written_fields
+        ]
+        return written_fields
+
+    @staticmethod
+    def _restore(*, obj: models.Model, loaded_state: tuple[dict, dict]) -> None:
+        instance_dict, fields_cache = loaded_state
+        obj.__dict__.clear()
+        obj.__dict__.update(instance_dict)
+        obj._state.fields_cache = fields_cache
+
+
+def get_phase_fields(*, model: type[models.Model]) -> tuple[PhaseField, ...]:
+    return tuple(field for field in model._meta.concrete_fields if isinstance(field, PhaseField))
+
+
+def get_phase_field(*, model: type[models.Model]) -> PhaseField:
+    """
+    Return the one `PhaseField` of `model`.
+
+    A model has at most one phase field (system check `phase.E002`), so callers never name the field.
+    """
+    phase_fields = get_phase_fields(model=model)
+    if not phase_fields:
+        raise MissingPhaseFieldError(model_name=model._meta.label)
+    return phase_fields[0]

phase/mixins/phase_guard.py

@@ -0,0 +1,64 @@
+from django.db import models, router, transaction
+
+from phase.exceptions import StalePhaseError
+from phase.fields import REFRESHING_FLAG, PhaseField, get_phase_fields, is_expression
+
+# The arguments of `Model.save()` in positional order.
+SAVE_ARGUMENTS = ("force_insert", "force_update", "using", "update_fields")
+
+
+class PhaseGuardMixin(models.Model):
+    """
+    Companion of `PhaseField`: lets reloads past the field's write protection and guards every save against a stale
+    phase.
+
+    A save of an instance whose phase no longer matches the database would silently undo a concurrent transition, so
+    it is refused. Because a `PhaseField` only changes through `move()`, the in-memory value always is the value last
+    read from or written to the database, and comparing it with a locked row is enough.
+
+    This also covers a new instance with an explicit primary key: Django tries an UPDATE first, which would otherwise
+    overwrite the phase of an existing row without a transition.
+
+    System check `phase.E001` makes sure every model with a `PhaseField` inherits this mixin.
+    """
+
+    class Meta:
+        abstract = True
+
+    def save(self, *args: object, **kwargs: object) -> None:
+        loaded_phases = {
+            field.attname: self.__dict__[field.attname]
+            for field in self.phase_fields()
+            if field.attname in self.__dict__ and not is_expression(self.__dict__[field.attname])
+        }
+        # Django 5.2 accepts the arguments of `save()` positionally as well.
+        options = dict(zip(SAVE_ARGUMENTS, args, strict=False)) | kwargs
+        update_fields = options.get("update_fields")
+        is_skipped_by_django = update_fields is not None and not update_fields
+        # Nothing to compare, an INSERT anyway, or a save Django skips (empty `update_fields`).
+        if not loaded_phases or self.pk is None or options.get("force_insert") or is_skipped_by_django:
+            super().save(*args, **kwargs)
+            return
+
+        using = options.get("using") or router.db_for_write(type(self), instance=self)
+        with transaction.atomic(using=using):
+            stored_phases = (
+                type(self)._base_manager.using(using).select_for_update().filter(pk=self.pk).values(*loaded_phases)
+            ).first()
+            if stored_phases is None and self._state.adding:
+                super().save(*args, **kwargs)
+                return
+            if stored_phases != loaded_phases:
+                raise StalePhaseError(model_name=self._meta.label, pk=self.pk, phases=loaded_phases)
+            super().save(*args, **kwargs)
+
+    @classmethod
+    def phase_fields(cls) -> tuple[PhaseField, ...]:
+        return get_phase_fields(model=cls)
+
+    def refresh_from_db(self, *args: object, **kwargs: object) -> None:
+        self.__dict__[REFRESHING_FLAG] = True
+        try:
+            super().refresh_from_db(*args, **kwargs)
+        finally:
+            del self.__dict__[REFRESHING_FLAG]

phase/transitions.py

@@ -0,0 +1,16 @@
+from django.db import models
+
+from phase.fields import get_phase_field
+
+
+def move(*, obj: models.Model, to: str, **fields: object) -> None:
+    """Move `obj` to phase `to` and write `fields` in the same conditional UPDATE, see `PhaseField.move()`."""
+    get_phase_field(model=type(obj)).move(obj=obj, to=to, **fields)
+
+
+def can_transition(*, obj: models.Model, to: str) -> bool:
+    return get_phase_field(model=type(obj)).can_transition(obj=obj, to=to)
+
+
+def targets(*, obj: models.Model) -> tuple[str, ...]:
+    return get_phase_field(model=type(obj)).targets(obj=obj)