django-fsm-log

What it is and what it does

django-fsm-log is a Django app that automatically captures and persists state machine transitions for models using django-fsm-2. It listens for FSM transition signals and creates database records for each state change, including source state, target state, timestamp, and optional metadata like the user who triggered the transition.

The package provides query helpers (StateLog.objects.for_() to filter by model instance), decorators to attach user information or custom descriptions to transitions, and admin integration to visualize transition history. It can optionally cache pending transitions before they're persisted, allowing access to log details immediately after a transition begins rather than waiting for database commit.

Use it for:

• Track approval workflows in document management systems, logging who approved/rejected and when.
• Audit state changes in order processing pipelines for compliance and debugging.
• Display transition history in Django admin to show users how a model's state evolved.
• Implement rollback or undo features by querying the StateLog to find previous states.
• Generate reports on transition timing and frequency to identify bottlenecks in workflows.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automatically logs state transitions for Django FSM models to the database, capturing the source state, target state, timestamp, and optional metadata like the user who triggered the transition.

Yes. The package is actively maintained, supports current Django and Python versions, has no known vulnerabilities, and solves a common need for FSM-based Django applications. Install it if you're using django-fsm-2 and need to audit or display state transition history; the low install friction and permissive license make it a straightforward addition.

Install

django-fsm-log on PyPI

pip install django-fsm-log

uv add django-fsm-log

poetry add django-fsm-log

Installing django-fsm-log

Before you install

Low friction installation with three straightforward dependencies (django, django-fsm-2, django-appconf). The package is actively maintained with recent releases supporting modern Django versions (5.2, 6.0) and Python 3.14, indicating ongoing compatibility work.

License in practice

MIT license is permissive, allowing use in commercial and open-source projects with minimal restrictions—only requiring attribution.

Quickstart

pip install django-fsm-log

# Add to INSTALLED_APPS
INSTALLED_APPS = (..., 'django_fsm_log', ...)

# Run migrations
python manage.py migrate django_fsm_log

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

Requires an existing Django project with django-fsm-2 already configured; the package listens for django_fsm.signals.post_transition, so FSM models must be set up first.

Verify before relying

• Whether the cached backend feature (CachedBackend) is suitable for high-concurrency scenarios or has known limitations.
• Performance impact when logging transitions for models with very high transition frequency.
• Whether the admin integration (StateLogInline) works with all Django admin customizations.

Package facts

Evidence: django_fsm_log-5.0.2-py3-none-any.whl

Keywords: django, django-fsm-2

Tags

More Python Modules packages