Merge pull request #143 from lorenzomorandini/add-description-arg-to-decorator

Add description argument to fsm_log_description decorator

Author: lorenzomorandini

README.md

@@ -14,6 +14,11 @@ by enabling a cached backend. See [Advanced Usage](#advanced-usage)
 
 ## Changelog
 
+### Unreleased
+
+- `fsm_log_description` now accepts a default description parameter
+- Document `fsm_log_description` decorator
+
 ### 3.0.0 (2022-01-14)
 
 - Switch to github actions (from travis-ci)
@@ -149,6 +154,52 @@ article = Article.objects.create()
 article.submit(by=some_user) # StateLog.by will be some_user
 ```
 
+### `description` Decorator
+
+Decorator that allows to set a custom description (saved on database) to a transitions.
+
+```python
+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::
+    The "description" argument passed when calling ".submit" has precedence over the default description set in the decorator
+
+The decorator also accepts a `allow_inline` boolean argument that allows to set the description inside the transition method.
+
+```python
+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
+```
+
 ### Admin integration
 
 There is an InlineForm available that can be used to display the history of changes.

django_fsm_log/decorators.py

@@ -4,6 +4,12 @@
 
 
 def fsm_log_by(func):
+    """Set the "by" field of a transition.
+
+    :param func: transition method
+    :type func: function
+    """
+
     @wraps(func)
     def wrapped(instance, *args, **kwargs):
         try:
@@ -16,20 +22,28 @@ def wrapped(instance, *args, **kwargs):
     return wrapped
 
 
-def fsm_log_description(func=None, allow_inline=False):
+def fsm_log_description(func=None, allow_inline=False, description=None):
+    """Set the "description" field of a transition.
+
+    :param func: transition method, defaults to None
+    :type func: function, optional
+    :param allow_inline: allow to set the description inside the transition method, defaults to False
+    :type allow_inline: bool, optional
+    :param description: default description, defaults to None
+    :type description: str, optional
+    """
     if func is None:
-        return partial(fsm_log_description, allow_inline=allow_inline)
+        return partial(fsm_log_description, allow_inline=allow_inline, description=description)
 
     @wraps(func)
     def wrapped(instance, *args, **kwargs):
         with FSMLogDescriptor(instance, "description") as descriptor:
-            try:
-                description = kwargs["description"]
-            except KeyError:
-                if allow_inline:
-                    kwargs["description"] = descriptor
-                return func(instance, *args, **kwargs)
-            descriptor.set(description)
+            if kwargs.get("description"):
+                descriptor.set(kwargs["description"])
+            elif allow_inline:
+                kwargs["description"] = descriptor
+            else:
+                descriptor.set(description)
             return func(instance, *args, **kwargs)
 
     return wrapped

tests/models.py

@@ -9,6 +9,7 @@ class Article(models.Model):
         ("draft", "Draft"),
         ("submitted", "Article submitted"),
         ("published", "Article published"),
+        ("temporary", "Article published (temporary)"),
         ("deleted", "Article deleted"),
     )
 
@@ -35,6 +36,19 @@ def publish(self, by=None):
     def delete(self, using=None):
         pass
 
+    @fsm_log_by
+    @fsm_log_description(description="Article restored")
+    @transition(field=state, source="deleted", target="draft")
+    def restore(self, description=None, by=None):
+        pass
+
+    @fsm_log_by
+    @fsm_log_description(allow_inline=True, description="Article published as temporary")
+    @transition(field=state, source="draft", target="temporary")
+    def publish_as_temporary(self, description=None, by=None):
+        if not isinstance(description, str):
+            description.set("Article published (temporary)")
+
     @fsm_log_by
     @fsm_log_description(allow_inline=True)
     @transition(field=state, source="draft", target="submitted")

tests/test_model.py

@@ -7,11 +7,11 @@
 
 
 def test_get_available_state_transitions(article):
-    assert len(list(article.get_available_state_transitions())) == 4
+    assert len(list(article.get_available_state_transitions())) == 5
 
 
 def test_get_all_state_transitions(article):
-    assert len(list(article.get_all_state_transitions())) == 6
+    assert len(list(article.get_all_state_transitions())) == 8
 
 
 def test_log_created_on_transition(article):
@@ -83,6 +83,34 @@ def test_description_can_be_mutated_by_the_transition(article):
         article.__django_fsm_log_attr_description
 
 
+def test_default_description(article):
+    article.delete()
+    article.save()
+    article.restore()
+    article.save()
+
+    log = StateLog.objects.all()[1]
+    assert log.description == "Article restored"
+
+
+def test_default_description_call_priority(article):
+    article.delete()
+    article.save()
+    article.restore(description="Restored because of mistake")
+    article.save()
+
+    log = StateLog.objects.all()[1]
+    assert log.description == "Restored because of mistake"
+
+
+def test_default_description_inline_priority(article):
+    article.publish_as_temporary()
+    article.save()
+
+    log = StateLog.objects.all()[0]
+    assert log.description == "Article published (temporary)"
+
+
 def test_logged_state_is_new_state(article):
     article.submit()