Django Finite State Machine Log
Automatic logging for the excellent Django FSM package.
Logs can be accessed before a transition occurs and before they are persisted to the database by enabling a cached backend. See Advanced Usage
get_state_displaywith FSMIntegerField (#63)
- Fixed handling of transitions if target is None (#71)
fsm_log_descriptiondecorator (#1, #67)
- Dropped support for Django 1.10 (#64)
- cleanup deprecated code.
- add codecov support.
- switch to pytest.
- add Admin integration to visualize past transitions.
- Bring compatibility with Django 2.0 and drop support of unsupported versions
- Python 2.7 and 3.4+
- Django 1.8+
- Django-FSM 2+
First, install the package with pip. This will automatically install any dependencies you may be missing
pip install django-fsm-log
Register django_fsm_log in your list of Django applications:
INSTALLED_APPS = ( ..., 'django_fsm_log', ..., )
Then migrate the app to create the database table
python manage.py migrate django_fsm_log
The app listens for the
django_fsm.signals.post_transition signal and
creates a new record for each transition.
To query the log:
from django_fsm_log.models import StateLog StateLog.objects.all() # ...all recorded logs...
Disabling logging for specific models
By default transitions get recorded for all models. Logging can be disabled for
specific models by adding their fully qualified name to
DJANGO_FSM_LOG_IGNORED_MODELS = ('poll.models.Vote')
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() StateLog.objects.for_(article) # ...logs for article...
We found that our transitions are commonly called by a user, so we've added a decorator to make logging this easy:
from django.db import models from django_fsm 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
With this the transition gets logged when the
by kwarg is present.
article = Article.objects.create() article.submit(by=some_user) # StateLog.by will be some_user
There is an InlineForm available that can be used to display the history of changes.
To use it expand your own
AdminModel by adding
StateLogInline to its inlines:
from django.contrib import admin from django_fsm_log.admin import StateLogInline @admin.register(FSMModel) class FSMModelAdmin(admin.ModelAdmin): inlines = [StateLogInline]
You can change the behaviour of this app by turning on caching for StateLog records.
DJANGO_FSM_LOG_STORAGE_METHOD = 'django_fsm_log.backends.CachedBackend' to your project's settings file.
It will use your project's default cache backend by default. If you wish to use a specific cache backend, you can add to
your project's settings:
DJANGO_FSM_LOG_CACHE_BACKEND = 'some_other_cache_backend'
The StateLog object is now available after the
signal is fired, but is deleted from the cache and persisted to the database after
This is useful if:
- you need immediate access to StateLog details, and cannot wait until
django_fsm.signals.post_transitionhas 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
from django_fsm_log.models import StateLog article = Article.objects.get(...) pending_state_log = StateLog.pending_objects.get_for_object(article)
pip install tox tox