README.md

Django Finite State Machine Log

Automatic logging for the excellent Django FSM package.

Installation

First, install the package with pip. This will automatically install any dependencies you may be missing

pip install django-fsm-log

With Python 2.7 Django 1.4+ is supported, with Python 3.3 Django 1.5+ is supported.

Then migrate the app to create the database table

python manage.py migrate django_fsm_log

Usage

The app will listen for django_fsm.signals.post_transition to be fired and create a new record for each transition.

To query logs simply

from django_fsm_log.models import StateLog
StateLog.objects.all()
# ...all recorded logs...

for_ Manager Method

For convenience there is a custom for_ manager method to easily filter on the generic foreign key

from my_app.models import Article
from django_fsm_log.models import StateLog

article = Article.objects.all()[0]

StateLog.objects.for_(article)
# ...logs for article...

by Decorator

We found that our transitions are commonly called by a user, so we've added a decorator to make logging that painless

from django.db import models
from django_fsm.db.fields import FSMField, transition
from django_fsm_log.decorators import fsm_log_by

class Article(models.Model):

    state = FSMField(default='draft', protected=True)

    @fsm_log_by
    @transition(field=state, source='draft', target='submitted')
    def submit(self, by=None):
        pass

Then every time the transition is called with the by kwarg set, it will be logged

article = Article.objects.create()
article.submit(by=some_user) # StateLog.by will be some_user

Advanced Usage

You can change the behaviour of this app by turning on caching for StateLog records. Simply add DJANGO_FSM_LOG_CACHE_BACKEND = 'django_fsm_log.backends.CachedBackend' to your project's settings file.

The StateLog object is now available after the django_fsm.signals.pre_transition signal is fired, but is deleted from the cache and persisted to the database after django_fsm.signals.post_transition is fired.

This is useful if:

• you need immediate access to StateLog details, and cannot wait until django_fsm.signals.post_transition has been fired
• at any stage, you need to verify whether or not the StateLog has been written to the database

Access to the pending StateLog record is available via the pending_objects manager

from django_fsm_log.models import StateLog
article = Article.objects.get(...)
pending_state_log = StateLog.pending_objects.get_for_object(article)

Running Tests

./runtests.py