Django FSM-2

The source and target parameters support advanced logic:

• Wildcards:
  • source='*': Any state (constant fsm.ANY_STATE).
  • source='+': Any state except the target (constant fsm.ANY_OTHER_STATE).
• Dynamic Targets:
  • fsm.RETURN_VALUE(value_if_returned, target_state): Uses the method's return value to determine the target.
  • fsm.GET_STATE(callable, states=[...]): Uses a callable to determine the target state from a list of allowed states.

import django_fsm as fsm

# Using RETURN_VALUE
@fsm.transition(
    field=state,
    source='*',
    target=fsm.RETURN_VALUE('for_moderators', 'published'),
)
def publish(self, is_public=False, **kwargs):
    return 'for_moderators' if is_public else 'published'

# Using GET_STATE
@fsm.transition(
    field=state,
    source='for_moderators',
    target=fsm.GET_STATE(
        lambda self, allowed: 'published' if allowed else 'rejected',
        states=['published', 'rejected'],
    ),
)
def moderate(self, allowed, **kwargs):
    pass

You can customize the appearance and behavior of transition buttons in the admin in two ways:

1. Via the @fsm.transition decorator

Use the custom dictionary to set label and help_text directly on the transition.

2. Via FSMAdminMixin methods

Override get_fsm_label and get_help_text in your ModelAdmin class to dynamically return strings based on the transition name.

Hiding transitions

To hide a button from the admin interface:

• Use custom={"admin": False} in the transition decorator.
• OR override is_fsm_transition_visible(self, transition) in your ModelAdmin and return False for specific transitions.

Note on visibility defaults: If you set FSM_ADMIN_FORCE_PERMIT = True in your Django settings, or set fsm_default_disallow_transition = False on your ModelAdmin, all transitions are hidden by default. You must then explicitly enable them using custom={"admin": True}.

# Option 1: Decorator customization
@fsm.transition(
    field='state',
    source=['startstate'],
    target='finalstate',
    custom={
        "label": "My awesome transition",
        "help_text": "Rename blog post",
        "admin": False,  # Hides the button
    },
)
def do_something(self, **kwargs):
    ...

# Option 2: Admin Mixin customization
@admin.register(AdminBlogPost)
class MyAdmin(FSMAdminMixin, admin.ModelAdmin):
    fsm_fields = ['state']

    def get_fsm_label(self, transition):
        if transition.name == "do_something":
            return "My awesome transition"
        return super().get_fsm_label(transition)

    def is_fsm_transition_visible(self, transition):
        if transition.name == "do_something":
            return False
        return super().is_fsm_transition_visible(transition)

Use the conditions argument in @fsm.transition to pass a list of callables. Each callable receives the model instance and must return a truthy or falsey value. Callables should not have side effects.

If a condition is not met, a django_fsm.TransitionConditionsUnmet exception is raised. You can access the failing callable via the failed_condition attribute on the exception.

import django_fsm as fsm
from django_fsm import TransitionConditionsUnmet

def can_publish(instance):
    return datetime.datetime.now().hour <= 17

class XXX(fsm.FSMModelMixin, models.Model):
    @fsm.transition(
        field=state,
        source='new',
        target='published',
        conditions=[can_publish]
    )
    def publish(self, **kwargs):
        pass

# Error handling
try:
    instance.publish()
except TransitionConditionsUnmet as e:
    print(e.failed_condition)  # e.g. <function can_publish at 0x...>

You can restrict transitions based on user permissions using the permission argument in @fsm.transition. It accepts:

• A permission string (e.g., 'myapp.can_remove_post').
• A callable that receives (instance, user) and returns a boolean.

To check if a user has permission to perform a transition before calling it, use fsm.has_transition_perm(transition_method, user).

import django_fsm as fsm

# Using a callable
@fsm.transition(
    field=state,
    source='*',
    target='published',
    permission=lambda instance, user: not user.has_perm('myapp.can_make_mistakes'),
)
def publish(self, **kwargs):
    pass

# Using a string
@fsm.transition(
    field=state,
    source='*',
    target='removed',
    permission='myapp.can_remove_post',
)
def remove(self, **kwargs):
    pass

# Checking permission in a view
def publish_view(request, post_id):
    post = get_object_or_404(BlogPost, pk=post_id)
    if not fsm.has_transition_perm(post.publish, request.user):
        raise PermissionDenied

    post.publish()
    post.save()

Django FSM-2 provides specialized field types for different storage needs:

• FSMKeyField: Stores state as a foreign key to another model. This maintains referential integrity. source and target use the Primary Key values of the target model.
• FSMIntegerField: Stores state as an integer, ideal for using Django IntegerChoices (enums).

import django_fsm as fsm

# FSMKeyField example
class DbState(fsm.FSMModelMixin, models.Model):
    id = models.CharField(primary_key=True)
    label = models.CharField()

class BlogPost(fsm.FSMModelMixin, models.Model):
    state = fsm.FSMKeyField(DbState, default='new')

# FSMIntegerField example
class BlogPostStateChoices(models.IntegerChoices):
    NEW = 10, "New"
    PUBLISHED = 20, "Published"

class BlogPostWithIntegerField(fsm.FSMModelMixin, models.Model):
    state = fsm.FSMIntegerField(default=BlogPostStateChoices.NEW)