MachineMixin fails in Django migrations with historical models

[atinary-bvollmer]

Description

When using MachineMixin with Django models, data migrations that use apps.get_model() fail because Django's historical models don't inherit class attributes like state_machine_name.

Error

ValueError: None is not a valid state machine name.

How to Reproduce

1. Create a Django model with MachineMixin:

from statemachine.mixins import MachineMixin

class MyModel(models.Model, MachineMixin):
    state_machine_name = "myapp.MyStateMachine"
    status = models.CharField(max_length=20)

2. Create a data migration using RunPython:

def backfill_data(apps, schema_editor):
    MyModel = apps.get_model("myapp", "MyModel")
    for obj in MyModel.objects.all():  # Fails here
        obj.some_field = "value"
        obj.save()

class Migration(migrations.Migration):
    operations = [
        migrations.RunPython(backfill_data),
    ]

3. Run python manage.py migrate

Suspected Cause

Django's apps.get_model() returns a dynamically created "historical" model class that doesn't include mixin class attributes. When MachineMixin.__init__ runs, self.state_machine_name is None, triggering the error.

[fgmacedo]

Hi @atinary-bvollmer , thanks for reporting this! This is a known limitation of Django's historical models in data migrations, and how it limits the wayMachineMixin interacts with the model, but we lack proper documentation.

Workaround (available now)

You can set the required attributes directly on the historical model class before instantiating objects:

def backfill_data(apps, schema_editor):
    MyModel = apps.get_model("myapp", "MyModel")
    MyModel.state_machine_name = "myapp.MyStateMachine"
    for obj in MyModel.objects.all():
        obj.some_field = "value"
        obj.save()

This works because the historical model class is a regular Python class — setting a class attribute on it makes it available to MachineMixin.__init__ via the MRO. Just make sure the module defining your StateMachine has been imported so it's registered.

Caveat: You'll need to keep the value in sync manually with your model definition, and repeat this in every data migration that touches the model.

Solutions I am considering for the library

Lazy initialization — Instead of creating the state machine eagerly in __init__, defer it to first access (e.g., via __getattr__). This way, migrations that don't actually use the state machine would never trigger the error. This is the most robust option but represents a bigger behavioral change and may break other scenarios and changes behaviour (instead of an error on intance creation one can get an error when trying to access the state machine field).

Detect Django historical models — Django sets __module__ = '__fake__' on historical model classes. We could check for this and skip state machine initialization. This is very targeted but relies on a Django implementation detail that could change.

We're evaluating which approach best balances correctness and compatibility. Feedback is welcome!

[atinary-bvollmer]

Hey @fgmacedo,

Thanks for the quick answer. I've seen the option with setting the name but it felt a bit "fragile". I've opted for:

import typing as t

from statemachine.mixins import MachineMixin


class MigrationSafeStateMachineMixin(MachineMixin):
    """
    Wrapper around MachineMixin that gracefully handles Django migrations.

    Django's `apps.get_model()` returns historical models that don't inherit
    class attributes like `state_machine_name`. This causes MachineMixin.__init__
    to fail with "None is not a valid state machine name."

    This mixin skips state machine initialization when `state_machine_name` is None,
    allowing historical models to be instantiated during migrations.

    See: https://github.com/fgmacedo/python-statemachine/issues/551
    """

    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:  # noqa: ANN401
        if not self.state_machine_name:
            super(MachineMixin, self).__init__(*args, **kwargs)
            return
        super().__init__(*args, **kwargs)

Would love to hear your thoughts on this.

Regarding potential solutions I would lean towards the second option but I can see your point. I don't know how likely it is that this implementation detail will change!

[fgmacedo]

Nice it worked for you. I think that this approach works for migrations, but is not safe and can hide errors as a general solution. Still thinking.

I'm also thinking on another possible approach, that uses deconstruct as a way to serialized model properties to the historical model representation.