Skip to main content

Create Django FSM transitions as a endpoint with Django REST Framework

Project description

=============== Django FSM with Django Rest Framework.


drf_fsm library provides an endpoint for defined each transition in models using Django FSM with Django Rest Framework library.


This library provides endpoint for each transition of FSM and customize like:

  1. Easy to define the number of FSM fields that's the endpoint you want to create automatically. default : No field.
  2. Easy to define how many transitions endpoint you want to create for particular field: default: all transition of fields.
  3. Easy to define serializer for each transition and field name wise: default: serializer_class of ViewSet.
  4. Easy to handle response for each endpoint of transition and field, default: .


  • Install drf_fsm using pip::

    pip install drf_fsm

  • Import Mixin from drf_fsm and Use in ViewSet views of DRF::

    from drf_fsm.mixins import FsmViewSetMixin

Uses with example

Lets Suppose a Post model that uses Django FSM

from django.contrib.auth import get_user_model
from django.db import models
from django_fsm import transition, FSMField

User = get_user_model()

class PostStatusChoices(models.TextChoices):
    Draft = 'draft', 'Draft'
    Pending = 'pending', 'Pending'
    Publish = 'publish', 'Publish'
    Future = 'future', 'Future'
    Trash = 'trash', 'Trash'

class Post(models.Model):
    title = models.CharField(max_length=200, unique=True)
    slug = models.SlugField(max_length=200, unique=True)
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='posts')
    updated_on = models.DateTimeField(auto_now=True)
    content = models.TextField()
    created_on = models.DateTimeField(auto_now_add=True)
    status = FSMField('Status', max_length=20, default=PostStatusChoices.Draft,
                      choices=PostStatusChoices.choices, protected=True)

    @transition(field=status, source='*', target=PostStatusChoices.Draft)
    def draft(self):

    @transition(field=status, source=PostStatusChoices.Draft, target=PostStatusChoices.Pending)
    def pending(self):

    @transition(field=status, source=PostStatusChoices.Pending, target=PostStatusChoices.Publish)
    def publish(self):

    @transition(field=status, source=PostStatusChoices.Pending, target=PostStatusChoices.Future)
    def future(self):

    @transition(field=status, source='*', target=PostStatusChoices.Trash)
    def trash(self):

We define model with 5 choices above and added 5 transition for each status in model.

Now create ViewSet for Post model

from rest_framework.viewsets import ModelViewSet
from drf_fsm.mixins import FsmViewSetMixin
from .models import Post
from .serializers import PostSerializer

class PostViewSet(FsmViewSetMixin, ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    fsm_fields = ['status']

Here we define "status" as a FSM field, we can define multiple in list if we have multiple in single model

Connect this views to DRF router

from rest_framework.routers import DefaultRouter
from .views import PostViewSet

router = DefaultRouter()

router.register('post', PostViewSet, basename="post_view_set")

urlpatterns = router.urls

Finished. Cheers ✌️

Now checking Output in Swagger

.. image:: output.png :width: 100%

😎 :),

Let's move to customizations:


  1. Define number of fields of FSM in view like::

    fsm_fields = ['status', 'priority']

  2. Define particular transitions for include, left will ignore for endpoints. suppose field name is "status" and have 5 transition according above example so we can handle which transition should include and other ignore.

    So write @classmethod in viewset for override this feature::

    @classmethod def status_transitions(cls): # Here status in field name so it's dynamic based on FSM field name. return ['trash', 'publish']

Here "trash" and "publish" transition endpoint will available for API, other will ignore from endpoints

  1. Define serializer class for each transition or field name wise::

    publish_status_serializer_class = PublishStatusPostSerializer # {transition}_{field_name}_serializer_class


    status_serializer_class = StatusPostSerializer # {field_name}_serializer_class

    or, default

    serializer_class = PostSerializer # Default serializer class for each

Serializer class uses dynamic name for each transition if define otherwise default will use.

  1. Define Response of each transition::

     def publish_status_response(self, serializer): # {transition}_{field_name}_response
         return {"message": "Post status updated published"}
     def status_response(self, serializer): # {field_name}_response, but it'll show for all transition of status field
         return {"message": "Post status updated"}
     or, default


Finished Customizations

.. image:: :target:


drf_fsm is an Open Source project licensed under the terms of the MIT license <>_

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drf_fsm-1.0.2.tar.gz (5.3 kB view hashes)

Uploaded Source

Built Distribution

drf_fsm-1.0.2-py3-none-any.whl (5.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page