API¶

class django_fsm.TransitionNotAllowed¶

Exception raised when a state transition is not permitted.

Base class for NoTransition and TransitionConditionsUnmet. Catch this to handle any transition failure, or catch a subclass to distinguish why the transition was refused.

class django_fsm.NoTransition(label: str, state: Any)¶

Raised when the current state has no transition registered for the call.

Variables

label – human-readable label of the transition method that was called.
state – the state the instance was in when the call was made.

class django_fsm.TransitionConditionsUnmet(transition: Transition, failed_condition: ThisObject | Callable[[T], bool], unmet_message: str = '')¶

Raised when a transition’s conditions callback returned false.

Variables

transition – the Transition that was attempted.
failed_condition – the first condition callable that returned false.
unmet_message – human-readable reason from a State.CONDITION result, or "" if the condition just returned a falsy value.

class django_fsm.InvalidTargetState(transition: Transition, target: Any, allowed_states: Iterable[Any])¶

Raised when a State.RETURN_VALUE/State.GET_STATE target resolves to a state outside its declared allowed states.

Variables

transition – the Transition that was attempted.
target – the resolved (invalid) state value.
allowed_states – the declared allowed states.

class django_fsm.State(states: Any, default: Any = None)¶

State slot field.

@transition(self, source: Any, target: Any | None = DEFAULT, label: str | None = None, conditions: List[ThisObject | Callable[[T], bool]] | None = None, permission: ThisObject | Callable[[T, Any], bool] | None = DEFAULT, custom: Dict | None = None) → Any¶: Decorator to mark a method as a state transition.

ANY = ANY¶

class CONDITION(is_true: bool, unmet: str = '')¶: Boolean-like object to return value accompanied with a message from fsm conditions.

class RETURN_VALUE(*allowed_states: Any)¶

target=State.RETURN_VALUE(*allowed_states) – the transition target is the method’s own return value, resolved only after it successfully returns (side effects in the method body already happened by then; there’s no way to know the target any sooner).

allowed_states, if given, restricts and documents the possible targets: chart() draws an edge for each, and a return value outside the set raises InvalidTargetState instead of silently landing on an undeclared state. Omit it to allow any return value.

class GET_STATE(func: Callable[[...], Any], states: List[Any] | None = None)¶

target=State.GET_STATE(func, states=[...]) – the transition target is computed by func(instance, *args, **kwargs) from the call’s own arguments, resolved before the transition method runs – so, unlike State.RETURN_VALUE, the method body already observes the new state, and nothing runs if the computed target turns out invalid.

states, if given, restricts and documents the possible targets: chart() draws an edge for each, and a computed target outside the set raises InvalidTargetState. Omit it to allow any target func returns.

class django_fsm.admin.FlowAdminMixin¶: A Mixin for providing Finite State Machine (FSM) management support in Django admin.

class django_fsm.viewset.FlowViewsMixin¶

class django_fsm.rest.FlowRESTMixin¶: ModelViewSet mixing exposes transition methods.

django_fsm.chart(flow_state: StateDescriptor, exclude_guards=True)¶

Draws a directed graph (digraph) of the state transitions defined in the given flow_state.

Args:: flow_state (StateDescriptor): The state descriptor object. exclude_guards (bool): Whether to exclude transitions with no target state.
Returns:: str: A string representation of the digraph in the DOT language.

The function uses the flow_state object to extract the transitions and the states involved. It then generates a DOT language string, which can be used with tools like Graphviz to produce an image of the graph.

A State.RETURN_VALUE/State.GET_STATE target charts one edge per declared allowed state; if none are declared, the transition is charted with no outgoing edge, since its real target is only known at runtime.

class django_fsm.FSMField(*args, **kwargs)¶: A char state column with Viewflow transitions; max_length defaults to 50.

class django_fsm.FSMIntegerField(*args: Any, protected: bool = False, enforce_initial: bool = False, state_choices=None, **kwargs: Any)¶: An integer state column with the same transition API as FSMField.

class django_fsm.FSMKeyField(*args: Any, protected: bool = False, enforce_initial: bool = False, state_choices=None, **kwargs: Any)¶: A foreign key whose model attribute exposes the state key, not an object.

class django_fsm.FSMFieldMixin(*args: Any, protected: bool = False, enforce_initial: bool = False, state_choices=None, **kwargs: Any)¶

State stored in a Django column, with optional assignment protection.

protected=True blocks reassignment after initialization. Transitions write through the state adapter instead. enforce_initial=True checks inserted rows against the field default, including bulk_create(). Raw SQL and fixture loading bypass that check. Both options default to False and are preserved by field cloning and migrations.

class django_fsm.FSMModelMixin¶: Refresh non-deferred, unprotected fields by default, as in django-fsm.

class django_fsm.ConcurrentTransitionMixin(*args, **kwargs)¶

Compare observed FSM states in the UPDATE predicate before saving.

Save in a transaction to roll back other database changes on conflict. Only state columns are compared; this is not a general model version.

class django_fsm.ConcurrentTransition¶: The persisted state changed after this model observed it.

django-fsm-compatible decorator: @transition(field=state, source=..., target=...).

Supports field objects or names, wildcard sources and Django permission names. Transition execution follows Viewflow semantics.

django_fsm.can_proceed(bound_method: TransitionBoundMethod, check_conditions: bool = True) → bool¶: Check the source state and, optionally, the transition’s conditions.

django_fsm.has_transition_perm(bound_method: TransitionBoundMethod, user: Any) → bool¶: Check the source state, conditions and the user’s permission.

class django_fsm.NonInitialStateOnCreate(field: FSMFieldMixin, value: Any)¶

Raised creating a new row through FSMField(enforce_initial=True) with a value other than the field’s declared default.

Variables

field – the FSM model field involved.
value – the rejected value.

django_fsm.signals.pre_transition¶: Django signal emitted before a model-field transition. See Django Model State Fields.

django_fsm.signals.post_transition¶: Django signal emitted after a successful model-field transition. See Django Model State Fields.

Table Of Contents

API¶