docs: Update docs using condition parameter

Author: EnriqueSoria

README.md

@@ -24,11 +24,17 @@ class Article(LifecycleModel):
     status = models.ChoiceField(choices=['draft', 'published'])
     editor = models.ForeignKey(AuthUser)
 
-    @hook(BEFORE_UPDATE, when='contents', has_changed=True)
+    @hook(BEFORE_UPDATE, WhenFieldHasChanged("contents", has_changed=True))
     def on_content_change(self):
         self.updated_at = timezone.now()
 
-    @hook(AFTER_UPDATE, when="status", was="draft", is_now="published")
+    @hook(
+        AFTER_UPDATE, 
+        condition=(
+            WhenFieldValueWas("status", value="draft")
+            & WhenFieldValueIs("status", value="published")
+        )
+    )
     def on_publish(self):
         send_email(self.editor.email, "An article has published!")
 ```

docs/examples.md

@@ -31,9 +31,9 @@ Or you want to email a user when their account is deleted. You could add the dec
 Or if you want to enqueue a background job that depends on state being committed to your database
 
 ```python
-    @hook(AFTER_CREATE, on_commit=True)
-    def do_after_create_jobs(self):
-        enqueue_job(send_item_shipped_notication, self.item_id)
+@hook(AFTER_CREATE, on_commit=True)
+def do_after_create_jobs(self):
+    enqueue_job(send_item_shipped_notication, self.item_id)
 ```
 
 Read on to see how to only fire the hooked method if certain conditions about the model's current and previous state are met.
@@ -43,56 +43,66 @@ Read on to see how to only fire the hooked method if certain conditions about th
 Maybe you only want the hooked method to run under certain circumstances related to the state of your model. If a model's `status` field change from `"active"` to `"banned"`, you may want to send an email to the user:
 
 ```python
-    @hook(AFTER_UPDATE, when='status', was='active', is_now='banned')
-    def email_banned_user(self):
-        mail.send_mail(
-            'You have been banned', 'You may or may not deserve it.',
-            'communitystandards@corporate.com', ['mr.troll@hotmail.com'],
-        )
+@hook(
+    AFTER_UPDATE, 
+    condition=(
+        WhenFieldValueWas("status", value="active") 
+        & WhenFieldValueIs('status', value='banned')
+    )
+)
+def email_banned_user(self):
+    mail.send_mail(
+        'You have been banned', 'You may or may not deserve it.',
+        'communitystandards@corporate.com', ['mr.troll@hotmail.com'],
+    )
 ``` 
 
-The `was` and `is_now` keyword arguments allow you to compare the model's state from when it was first instantiated to the current moment. You can also pass `"*"` to indicate any value - these are the defaults, meaning that by default the hooked method will fire. The `when` keyword specifies which field to check against. 
+The `WhenFieldValueWas` and `WhenFieldValueIs` conditions allow you to compare the model's state from when it was first instantiated to the current moment. You can also pass `"*"` to indicate any value - these are the defaults, meaning that by default the hooked method will fire. 
 
 ## Preventing state transitions
 
 You can also enforce certain disallowed transitions. For example, maybe you don't want your staff to be able to delete an active trial because they should expire instead:
 
 ```python
-    @hook(BEFORE_DELETE, when='has_trial', is_now=True)
-    def ensure_trial_not_active(self):
-        raise CannotDeleteActiveTrial('Cannot delete trial user!')
+@hook(BEFORE_DELETE, condition=WhenFieldValueIs("has_trial", value=True))
+def ensure_trial_not_active(self):
+    raise CannotDeleteActiveTrial('Cannot delete trial user!')
 ```
 
-We've omitted the `was` keyword meaning that the initial state of the `has_trial` field can be any value ("*").
-
 ## Any change to a field
 
-You can pass the keyword argument `has_changed=True` to run the hooked method if a field has changed.
+You can use the `WhenFieldValueChangesTo` condition to run the hooked method if a field has changed.
 
 ```python
-    @hook(BEFORE_UPDATE, when='address', has_changed=True)
-    def timestamp_address_change(self):
-        self.address_updated_at = timezone.now()
+@hook(BEFORE_UPDATE, condition=WhenFieldHasChanged("address", has_changed=True))
+def timestamp_address_change(self):
+    self.address_updated_at = timezone.now()
 ```
 
 ## When a field's value is NOT
 
 You can have a hooked method fire when a field's value IS NOT equal to a certain value.
 
 ```python
-    @hook(BEFORE_SAVE, when='email', is_not=None)
-    def lowercase_email(self):
-        self.email = self.email.lower()
+@hook(BEFORE_SAVE, condition=WhenFieldValueIsNot("email", value=None))
+def lowercase_email(self):
+    self.email = self.email.lower()
 ```
 
 ## When a field's value was NOT
 
 You can have a hooked method fire when a field's initial value was not equal to a specific value.
 
 ```python
-    @hook(BEFORE_SAVE, when='status', was_not="rejected", is_now="published")
-    def send_publish_alerts(self):
-        send_mass_email()
+@hook(
+    BEFORE_SAVE, 
+    condition=(
+        WhenFieldValueWasNot("status", value="rejected") 
+        & WhenFieldValueIs("status", value="published")
+    )
+)
+def send_publish_alerts(self):
+    send_mass_email()
 ```
 
 ## When a field's value changes to
@@ -101,53 +111,49 @@ You can have a hooked method fire when a field's initial value was not equal to
 but now is.
 
 ```python
-    @hook(BEFORE_SAVE, when='status', changes_to="published")
+    @hook(BEFORE_SAVE, condition=WhenFieldValueChangesTo("status", value="published"))
     def send_publish_alerts(self):
         send_mass_email()
 ```
 
-Generally, `changes_to` is a shorthand for the situation when `was_not` and `is_now` have the
-same value. The sample above is equal to:
+Generally, `WhenFieldValueChangesTo` is a shorthand for the situation when `WhenFieldValueWasNot` and `WhenFieldValueIs` 
+conditions have the same value. The sample above is equal to:
 
 ```python
-    @hook(BEFORE_SAVE, when='status', was_not="published", is_now="published")
-    def send_publish_alerts(self):
-        send_mass_email()
+@hook(
+    BEFORE_SAVE, 
+    condition=(
+        WhenFieldValueWasNot("status", value="published")
+        & WhenFieldValueIs("status", value="published")
+    )
+)
+def send_publish_alerts(self):
+    send_mass_email()
 ```
 
 ## Stacking decorators
 
 You can decorate the same method multiple times if you want to hook a method to multiple moments.
 
 ```python
-    @hook(AFTER_UPDATE, when="published", has_changed=True)
-    @hook(AFTER_CREATE, when="type", has_changed=True)
-    def handle_update(self):
-        # do something
-```
-
-## Watching multiple fields
-
-If you want to hook into the same moment, but base its conditions on multiple fields, you can use the `when_any` parameter.
-
-```python
-    @hook(BEFORE_SAVE, when_any=['status', 'type'], has_changed=True)
-    def do_something(self):
-        # do something
+@hook(AFTER_UPDATE, condition=WhenFieldHasChanged("published", has_changed=True))
+@hook(AFTER_CREATE, condition=WhenFieldHasChanged("type", has_changed=True))
+def handle_update(self):
+    # do something
 ```
 
 ## Going deeper with utility methods
 
-If you need to hook into events with more complex conditions, you can take advantage of `has_changed` and `initial_value` [utility methods](advanced.md):
+If you need to hook into events with more complex conditions, you can [write your own conditions](advanced.md), or take advantage of `has_changed` and `initial_value` [utility methods](advanced.md):
 
 ```python
-    @hook(AFTER_UPDATE)
-    def on_update(self):
-        if self.has_changed('username') and not self.has_changed('password'):
-            # do the thing here
-            if self.initial_value('login_attempts') == 2:
-                do_thing()
-            else:
-                do_other_thing()
+@hook(AFTER_UPDATE)
+def on_update(self):
+    if self.has_changed('username') and not self.has_changed('password'):
+        # do the thing here
+        if self.initial_value('login_attempts') == 2:
+            do_thing()
+        else:
+            do_other_thing()
 ```
 

docs/fk_changes.md

@@ -14,7 +14,7 @@ class UserAccount(LifecycleModel):
     email = models.CharField(max_length=600)
     employer = models.ForeignKey(Organization, on_delete=models.SET_NULL)
 
-    @hook(AFTER_UPDATE, when="employer", has_changed=True)
+    @hook(AFTER_UPDATE, condition=WhenFieldHasChanged("employer", has_changed=True))
     def notify_user_of_employer_change(self):
         mail.send_mail("Update", "You now work for someone else!", [self.email])
 ```
@@ -34,7 +34,7 @@ class UserAccount(LifecycleModel):
     email = models.CharField(max_length=600)
     employer = models.ForeignKey(Organization, on_delete=models.SET_NULL)
 
-    @hook(AFTER_UPDATE, when="employer.name", has_changed=True, is_now="Google")
+    @hook(AFTER_UPDATE, condition=WhenFieldValueChangesTo("employer.name", value="Google"))
     def notify_user_of_google_buy_out(self):
         mail.send_mail("Update", "Google bought your employer!", ["to@example.com"],)
 ```

docs/index.md

@@ -20,11 +20,17 @@ class Article(LifecycleModel):
     status = models.ChoiceField(choices=['draft', 'published'])
     editor = models.ForeignKey(AuthUser)
 
-    @hook(BEFORE_UPDATE, when='contents', has_changed=True)
+    @hook(BEFORE_UPDATE, condition=WhenFieldHasChanged('contents', has_changed=True))
     def on_content_change(self):
         self.updated_at = timezone.now()
 
-    @hook(AFTER_UPDATE, when="status", was="draft", is_now="published")
+    @hook(
+        AFTER_UPDATE, 
+        condition=(
+            WhenFieldValueWas("status", value="draft")
+            & WhenFieldValueIs("status", value="published")
+        )
+    )
     def on_publish(self):
         send_email(self.editor.email, "An article has published!")
 ```
@@ -52,8 +58,8 @@ Instead of overriding `save` and `__init__` in a clunky way that hurts readabili
 
 ## Requirements
 
-* Python (3.5+)
-* Django (2.0+)
+* Python (3.7+)
+* Django (2.2+)
 
 ## Installation