Remove fsm_log_by and fsm_log_description

Author: pfouque

README.md

@@ -605,17 +605,13 @@ You can also capture `author` and `description` for each transition.
 
 ```python
 import django_fsm
-from django_fsm.log import fsm_log_by
-from django_fsm.log import fsm_log_description
 from django.db import models
 
 
 @django_fsm.track()
 class BlogPost(models.Model):
     state = django_fsm.FSMField(default="new")
 
-    @fsm_log_by
-    @fsm_log_description
     @django_fsm.transition(field=state, source="new", target="published")
     def publish(self):
         pass

django_fsm/__init__.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import inspect
 import typing
 from functools import partialmethod
@@ -648,6 +649,24 @@ def save(self, *args: typing.Any, **kwargs: typing.Any) -> None:
         self._update_initial_state()
 
 
+class FSMLogDescriptor:
+    ATTR_PREFIX = "__django_fsm_log_attr_"
+
+    def __init__(self, instance: models.Model, attrs: dict[str, typing.Any]) -> None:
+        self.instance = instance
+        self.attrs = attrs
+
+    def __enter__(self) -> typing.Self:
+        for name, value in self.attrs.items():
+            setattr(self.instance, self.ATTR_PREFIX + name, value)
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        for name in self.attrs:
+            with contextlib.suppress(AttributeError):
+                delattr(self.instance, self.ATTR_PREFIX + name)
+
+
 def transition(
     field: FSMFieldMixin | str,
     source: _StateValue | typing.Sequence[_StateValue] = ANY_STATE,
@@ -686,6 +705,14 @@ def _change_state(
             instance: _FSMModel, *args: typing.Any, **kwargs: typing.Any
         ) -> typing.Any:
             assert isinstance(fsm_meta.field, FSMFieldMixin)
+            log_attrs: dict[str, typing.Any] = {}
+            if "by" in kwargs:
+                log_attrs["by"] = kwargs.pop("by")
+            if "description" in kwargs:
+                log_attrs["description"] = kwargs.pop("description")
+            if log_attrs:
+                with FSMLogDescriptor(instance, log_attrs):
+                    return fsm_meta.field.change_state(instance, func, *args, **kwargs)
             return fsm_meta.field.change_state(instance, func, *args, **kwargs)
 
         if not wrapper_installed:

django_fsm/admin.py

@@ -3,7 +3,6 @@
 import logging
 import typing
 from dataclasses import dataclass
-from warnings import warn
 
 try:
     from typing import override
@@ -17,7 +16,6 @@
 from django.contrib import messages
 from django.contrib.admin import TabularInline
 from django.contrib.admin.templatetags.admin_urls import add_preserved_filters
-from django.contrib.contenttypes.admin import GenericTabularInline
 from django.core.exceptions import ImproperlyConfigured
 from django.db import models
 from django.forms import Form
@@ -32,19 +30,21 @@
 
 import django_fsm as fsm
 
-from .models import StateLog
-from .models import TransitionLogBase
-
 logger = logging.getLogger(__name__)
 
 if typing.TYPE_CHECKING:  # pragma: no cover
+    from django.http import HttpRequest
+
+    from .models import TransitionLogBase
+
     _ModelAdmin: typing.TypeAlias = admin.ModelAdmin[fsm._FSMModel]
     _FormType: typing.TypeAlias = type[Form | ModelForm[fsm._FSMModel]]
-
-    from django.http import HttpRequest
+    _FSMTransitionInlineBase: typing.TypeAlias = TabularInline[TransitionLogBase, models.Model]
 else:
     _ModelAdmin = admin.ModelAdmin
     _FormType = type[Form | ModelForm]
+    TransitionLogBase = models.Model
+    _FSMTransitionInlineBase = TabularInline
 
 
 @dataclass
@@ -405,7 +405,7 @@ def fsm_transition_view(
         )
 
 
-class FSMTransitionInlineMixin(TabularInline[TransitionLogBase, models.Model]):
+class FSMTransitionInlineMixin(_FSMTransitionInlineBase):
     can_delete = False
 
     def has_add_permission(self, request: HttpRequest, obj: models.Model | None = None) -> bool:
@@ -430,15 +430,3 @@ def get_readonly_fields(
 
     def get_queryset(self, request: HttpRequest) -> models.QuerySet[TransitionLogBase]:
         return super().get_queryset(request).order_by(models.F("timestamp").desc())
-
-
-class StateLogInline(FSMTransitionInlineMixin, GenericTabularInline):
-    model = StateLog
-
-    def __init__(self, parent_model: typing.Any, admin_site: typing.Any) -> None:
-        warn(
-            "StateLogInline has been deprecated by FSMTransitionInlineMixin.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        super().__init__(parent_model, admin_site)

django_fsm/log.py

@@ -1,14 +1,11 @@
 from __future__ import annotations
 
-import contextlib
 import typing
 from dataclasses import dataclass
-from functools import partial
-from functools import wraps
 
-from django.contrib.contenttypes.models import ContentType
 from django.db import models
 
+from . import FSMLogDescriptor
 from .models import StateLog
 from .models import TransitionLogBase
 from .signals import post_transition
@@ -22,19 +19,18 @@
 __all__ = [
     "StateLog",
     "TransitionLogBase",
-    "fsm_log_by",
-    "fsm_log_description",
     "track",
 ]
 
 
 @dataclass(frozen=True)
 class TrackConfig:
-    log_model: type[TransitionLogBase] | None
-    relation_field: str | None
+    log_model: type[TransitionLogBase]
+    relation_field: str
 
 
 _registry: dict[type[models.Model], TrackConfig] = {}
+
 NOTSET = object()
 
 
@@ -47,7 +43,10 @@ def decorator(model_cls: type[models.Model]) -> type[models.Model]:
         if model_cls._meta.abstract:
             raise TypeError("django_fsm.track cannot be used with abstract models")
 
-        _registry[model_cls] = TrackConfig(log_model=log_model, relation_field=relation_field)
+        _registry[model_cls] = TrackConfig(
+            log_model=log_model or StateLog,
+            relation_field=relation_field or "content_object",
+        )
 
         post_transition.connect(
             _log_transition,
@@ -60,63 +59,6 @@ def decorator(model_cls: type[models.Model]) -> type[models.Model]:
     return decorator
 
 
-class FSMLogDescriptor:
-    ATTR_PREFIX = "__django_fsm_log_attr_"
-
-    def __init__(self, instance: models.Model, attribute: str, value: typing.Any = NOTSET):
-        self.instance = instance
-        self.attribute = attribute
-        if value is not NOTSET:
-            self.set(value)
-
-    def get(self) -> typing.Any:
-        return getattr(self.instance, self.ATTR_PREFIX + self.attribute)
-
-    def set(self, value: typing.Any) -> None:
-        setattr(self.instance, self.ATTR_PREFIX + self.attribute, value)
-
-    def __enter__(self) -> typing.Self:
-        return self
-
-    def __exit__(self, *args: object) -> None:
-        with contextlib.suppress(AttributeError):
-            delattr(self.instance, self.ATTR_PREFIX + self.attribute)
-
-
-def fsm_log_by(func: _TransitionFunc) -> _TransitionFunc:
-    @wraps(func)
-    def wrapped(instance: models.Model, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
-        if "by" in kwargs:
-            author = kwargs.pop("by")
-        else:
-            return func(instance, *args, **kwargs)
-
-        with FSMLogDescriptor(instance, "by", author):
-            return func(instance, *args, **kwargs)
-
-    return wrapped
-
-
-def fsm_log_description(
-    func: _TransitionFunc | None = None,
-    *,
-    description: str | None = None,
-) -> _TransitionFunc:
-    if func is None:
-        return partial(fsm_log_description, description=description)
-
-    @wraps(func)
-    def wrapped(instance: models.Model, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
-        with FSMLogDescriptor(instance, "description") as descriptor:
-            if "description" in kwargs:
-                descriptor.set(kwargs.pop("description"))
-            else:
-                descriptor.set(description)
-            return func(instance, *args, **kwargs)
-
-    return wrapped
-
-
 def _log_transition(
     sender: type[models.Model],
     instance: models.Model,
@@ -131,44 +73,17 @@ def _log_transition(
         return
 
     log_model = config.log_model or StateLog
-    log_kwargs: dict[str, typing.Any] = {
-        "transition": name,
-        "state_field": field.name,
-        "source_state": _coerce_state(source),
-        "state": _coerce_state(target),
-        "by": _extract_log_value(instance, "by"),
-        "description": _extract_log_value(instance, "description"),
-    }
-
-    if issubclass(log_model, StateLog):
-        log_kwargs["content_type"] = ContentType.objects.get_for_model(sender)
-        log_kwargs["object_id"] = str(instance.pk)
-    else:
-        relation_field = config.relation_field or _resolve_relation_field(log_model, sender)
-        log_kwargs[relation_field] = instance
-
-    log_model._default_manager.using(instance._state.db).create(**log_kwargs)
-
-
-def _resolve_relation_field(
-    log_model: type[TransitionLogBase], model_cls: type[models.Model]
-) -> str:
-    relation_fields = [
-        field.name
-        for field in log_model._meta.fields
-        if isinstance(field, models.ForeignKey)
-        and _matches_model(field.remote_field.model, model_cls)
-    ]
-    if len(relation_fields) == 1:
-        return relation_fields[0]
-
-    if not relation_fields:
-        raise ValueError(
-            f"{log_model.__name__} does not define a ForeignKey to {model_cls.__name__}"
-        )
-    raise ValueError(
-        f"{log_model.__name__} has multiple ForeignKey fields to {model_cls.__name__}; "
-        "set relation_field when calling track()"
+
+    log_model._default_manager.using(instance._state.db).create(
+        **{
+            "transition": name,
+            "state_field": field.name,
+            "source_state": _coerce_state(source),
+            "state": _coerce_state(target),
+            "by": _extract_log_value(instance, "by"),
+            "description": _extract_log_value(instance, "description"),
+            config.relation_field: instance,
+        }
     )
 
 
@@ -180,16 +95,5 @@ def _coerce_state(value: _StateValue | None) -> _StateValue | None:
     return value
 
 
-def _matches_model(remote_model: typing.Any, model_cls: type[models.Model]) -> bool:
-    if remote_model == model_cls:
-        return True
-    if isinstance(remote_model, str):
-        return remote_model == model_cls.__name__ or remote_model.endswith(f".{model_cls.__name__}")
-    return False
-
-
 def _extract_log_value(instance: models.Model, attribute: str) -> typing.Any:
-    try:
-        return FSMLogDescriptor(instance, attribute).get()
-    except AttributeError:
-        return None
+    return getattr(instance, f"{FSMLogDescriptor.ATTR_PREFIX}{attribute}", None)

django_fsm/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 4.2.16 on 2026-01-29 08:32
+# Generated by Django 6.0.2 on 2026-03-18 12:31
 from __future__ import annotations
 
 import django.db.models.deletion
@@ -53,12 +53,13 @@ class Migration(migrations.Migration):
                 ),
             ],
             options={
+                "db_table": "django_fsm_log_statelog",
                 "indexes": [
                     models.Index(
-                        fields=["source_state", "state"], name="django_fsm__source__bb71ee_idx"
+                        fields=["source_state", "state"], name="django_fsm__source__b87a8b_idx"
                     ),
                     models.Index(
-                        fields=["content_type", "object_id"], name="django_fsm__content_9593e3_idx"
+                        fields=["content_type", "object_id"], name="django_fsm__content_c774a6_idx"
                     ),
                 ],
             },

django_fsm/models.py

@@ -46,6 +46,7 @@ class StateLog(TransitionLogBase):  # noqa: DJ008
     objects = StateLogQuerySet.as_manager()
 
     class Meta:
+        db_table = "django_fsm_log_statelog"
         indexes = [
             models.Index(fields=["source_state", "state"]),
             models.Index(fields=["content_type", "object_id"]),

django_fsm_log/admin.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
 import typing
+from warnings import warn
 
+from django.contrib.contenttypes.admin import GenericTabularInline
 from django.core import checks
 
-from django_fsm.admin import StateLogInline
+from django_fsm.admin import FSMTransitionInlineMixin
+
+from .models import StateLog
 
 __all__ = ["StateLogInline"]
 
@@ -24,3 +28,15 @@ def check_deprecated_mixin_import(
             id="django_fsm.log.W002",
         )
     ]
+
+
+class StateLogInline(FSMTransitionInlineMixin, GenericTabularInline):
+    model = StateLog
+
+    def __init__(self, parent_model: typing.Any, admin_site: typing.Any) -> None:
+        warn(
+            "StateLogInline has been deprecated by FSMTransitionInlineMixin.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(parent_model, admin_site)