Django FSM

3.0.1 · deprecated · verified Mon Apr 13

Django FSM (Finite State Machine) provides declarative state management for Django models. It allows defining states and transitions using decorators, ensuring state changes adhere to predefined rules. The standalone `django-fsm` library, currently at version 3.0.1, is deprecated; its functionality has been integrated into `viewflow.fsm` since version 3.0.0. The original library will no longer receive updates.

Warnings

breaking The standalone `django-fsm` library (version 3.0.0+) is no longer maintained. Its functionality has been fully integrated into `viewflow` as the `viewflow.fsm` package. Users are strongly encouraged to migrate to `viewflow.fsm` for new features and ongoing maintenance.
Fix: Migrate existing code to use `viewflow.fsm` classes and decorators. Refer to the `viewflow` documentation for the new API, particularly the migration guide if available. The core concepts of FSM remain, but import paths and class structures have changed significantly.
gotcha Calling a transition method (e.g., `model_instance.transition_method()`) changes the state only in memory. You *must* call `model_instance.save()` afterward to persist the state change to the database.
Fix: Always follow a successful transition method call with `model_instance.save()`.
gotcha If `FSMField(protected=True)` is used, direct assignment to the state field (e.g., `model.state = 'new_state'`) will raise an `AttributeError`. State changes must occur via decorated transition methods. This is often desired for strict state machine enforcement.
Fix: Ensure all state modifications go through methods decorated with `@transition`. If direct assignment is temporarily needed (e.g., for migrations or testing), set `protected=False` or bypass FSM checks carefully.
breaking The default `db_index=True` for `FSMIntegerField` was removed in version 2.2.0. This could subtly affect database performance if you relied on it for indexing.
Fix: If `db_index` is required for `FSMIntegerField` instances, explicitly set `db_index=True` when defining the field in your model (e.g., `state = FSMIntegerField(db_index=True)`).

Install

pip install django-fsm Install `django-fsm` (deprecated)
pip install django-viewflow Install `viewflow` (for `viewflow.fsm` - the maintained successor)

Imports

FSMField
```
from django_fsm import FSMField
```
The direct import from `django_fsm` is the most common and recommended way since early versions.
transition
```
from django_fsm import transition
```
The direct import from `django_fsm` is the most common and recommended way.
FSMIntegerField
```
from django_fsm import FSMIntegerField
```
Used for integer-based state fields.
FSMKeyField
```
from django_fsm import FSMKeyField
```
Used for Foreign Key-based state fields.
can_proceed
```
from django_fsm import can_proceed
```
Utility function to check if a transition is allowed.
FSMAdminMixin
```
from django_fsm.admin import FSMAdminMixin
```
Mixin for integrating FSM functionality into Django Admin.
State
```
from viewflow.fsm import State
```
The new way to define states and transitions in `viewflow.fsm` (successor to `django-fsm` v3.0+).

Quickstart

This quickstart demonstrates defining states with `FSMField` and transitions with the `@transition` decorator for a `BlogPost` model. It highlights basic state transitions and the use of `protected=True` to enforce transitions via methods only. Note that for versions 3.0.0 and above, the functionality has migrated to `viewflow.fsm`.

import os
import django
from enum import Enum
from django.db import models
from django_fsm import FSMField, transition

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project_name.settings') # Replace with actual project settings if needed
django.setup()

class BlogPost(models.Model):
    class BlogState(models.TextChoices):
        DRAFT = "draft", "Draft"
        REVIEW = "review", "Under Review"
        PUBLISHED = "published", "Published"
        ARCHIVED = "archived", "Archived"

    state = FSMField(choices=BlogState.choices, default=BlogState.DRAFT, protected=True)
    title = models.CharField(max_length=255)
    content = models.TextField()

    @transition(field=state, source=BlogState.DRAFT, target=BlogState.REVIEW)
    def submit_for_review(self):
        print(f"Blog post '{self.title}' submitted for review.")

    @transition(field=state, source=BlogState.REVIEW, target=BlogState.PUBLISHED)
    def publish(self):
        print(f"Blog post '{self.title}' published!")

    @transition(field=state, source=[BlogState.DRAFT, BlogState.REVIEW, BlogState.PUBLISHED], target=BlogState.ARCHIVED)
    def archive(self):
        print(f"Blog post '{self.title}' archived.")

    def __str__(self):
        return f"{self.title} ({self.get_state_display()})"

# Example Usage (assuming a Django environment is set up and models are synced)
# For a real application, replace this with actual model creation/retrieval.
# try:
#     blog_post = BlogPost.objects.create(title="My First Post", content="Lorem ipsum...")
#     print(blog_post)

#     if can_proceed(blog_post.submit_for_review):
#         blog_post.submit_for_review()
#         blog_post.save()
#         print(blog_post)

#     if can_proceed(blog_post.publish):
#         blog_post.publish()
#         blog_post.save()
#         print(blog_post)

#     if can_proceed(blog_post.archive):
#         blog_post.archive()
#         blog_post.save()
#         print(blog_post)

#     # This would fail if protected=True and not using a transition method
#     # blog_post.state = BlogPost.BlogState.DRAFT
#     # blog_post.save()

# except Exception as e:
#     print(f"An error occurred: {e}")

view raw JSON →