Django有限状态机日志

提供您fsm模型转换的持久化。由出色的Django FSM包支持。

启用缓存后端后，可以在转换发生之前和持久化到数据库之前访问日志。见高级用法

变更日志

4.0.0（尚未发布）

3.1.0 (2023-03-23)

• fsm_log_description现在接受一个默认描述参数
• 文档fsm_log_description装饰器
• 添加对Django 4.1的支持
• 添加对python 3.11的兼容性

3.0.0 (2022-01-14)

• 切换到github actions（从travis-ci）
• 测试django 3.2和4.0，然后python 3.9和3.10
• 放弃对django 1.11、2.0、2.1、3.0、3.1的支持
• 放弃对python 3.4、3.5、3.6的支持
• 允许在迁移中使用StateLogManager #95

2.0.1 (2020-03-26)

• 添加对django3.0的支持
• 放弃对python2的支持

1.6.2 (2019-01-06)

• 解决1.6.1中添加的迁移历史中断问题

1.6.1 (2018-12-02)

• 使StateLog.description字段可为空

1.6.0 (2018-11-14)

• 在转换时添加源状态
• 修复了get_state_display与FSMIntegerField的兼容性问题 (#63)
• 修复了目标为None时的转换处理问题 (#71)
• 添加了fsm_log_description装饰器 (#1, #67)
• 放弃对Django 1.10的支持 (#64)

1.5.0 (2017-11-29)

• 清理已弃用的代码。
• 添加codecov支持。
• 切换到pytest。
• 添加管理集成以可视化过去的转换。

1.4.0 (2017-11-09)

• 与Django 2.0兼容并放弃对不支持的Django版本的兼容性：1.6、1.7、1.9。

兼容性

• Python 2.7和3.4+
• Django 1.8+
• Django-FSM 2+

安装

首先，使用pip安装该包。这将自动安装可能缺少的任何依赖项

pip install django-fsm-log

在您的Django应用程序列表中注册django_fsm_log

INSTALLED_APPS = (
    ...,
    'django_fsm_log',
    ...,
)

然后迁移应用程序以创建数据库表

python manage.py migrate django_fsm_log

用法

该应用程序监听django_fsm.signals.post_transition信号，并为每个转换创建一个新记录。

查询日志

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

禁用特定模型的日志记录

默认情况下，所有模型的转换都会被记录。可以通过将它们的完全限定名称添加到DJANGO_FSM_LOG_IGNORED_MODELS来禁用特定模型的日志记录。

DJANGO_FSM_LOG_IGNORED_MODELS = ('poll.models.Vote',)

for_管理方法

为了方便起见，有一个自定义的for_管理方法，可以轻松过滤通用的外键

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装饰器

我们发现我们的转换通常由用户调用，所以我们添加了一个装饰器来简化此日志记录

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

如果有by关键字参数，转换就会被记录。

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

description装饰器

装饰器允许为转换设置自定义描述（保存在数据库中）。

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

class Article(models.Model):

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

    @fsm_log_description(description='Article submitted')  # description param is NOT required
    @transition(field=state, source='draft', target='submitted')
    def submit(self, description=None):
        pass

article = Article.objects.create()
article.submit()  # logged with "Article submitted" description
article.submit(description="Article reviewed and submitted")  # logged with "Article reviewed and submitted" description

.. TIP:: 调用".submit"时传递的"描述"参数优先于装饰器中设置的默认描述

装饰器还接受一个布尔参数allow_inline，允许在转换方法中设置描述。

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

class Article(models.Model):

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

    @fsm_log_description(allow_inline=True)
    @transition(field=state, source='draft', target='submitted')
    def submit(self, description=None):
        description.set("Article submitted")

article = Article.objects.create()
article.submit()  # logged with "Article submitted" description

管理集成

有一个内联表单可用于显示更改历史。

要使用它，通过将StateLogInline添加到其内联中，扩展您自己的AdminModel。

from django.contrib import admin
from django_fsm_log.admin import StateLogInline


@admin.register(FSMModel)
class FSMModelAdmin(admin.ModelAdmin):
    inlines = [StateLogInline]

高级用法

您可以通过启用StateLog记录的缓存来更改此应用程序的行为。只需将DJANGO_FSM_LOG_STORAGE_METHOD = 'django_fsm_log.backends.CachedBackend'添加到项目设置文件中。它将默认使用项目默认的缓存后端。如果您希望使用特定的缓存后端，您可以将其添加到项目的设置中

DJANGO_FSM_LOG_CACHE_BACKEND = 'some_other_cache_backend'

在django_fsm.signals.pre_transition信号触发后，现在可以访问StateLog对象，但在django_fsm.signals.post_transition触发后，它将从缓存中删除并持久化到数据库。

这很有用，如果

• 您需要立即访问StateLog详细信息，而无法等待django_fsm.signals.post_transition被触发
• 在任何阶段，您都需要验证StateLog是否已写入数据库

可以通过pending_objects管理器访问待处理的StateLog记录

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

使用pre-commit进行代码风格检查

我们使用ruff、black等工具，所有配置和检查都通过pre-commit完成。在提交之前，请运行以下命令

pip install pre-commit
pre-commit install