Merge pull request #181 from netzkolchose/signals

signals

Author: jerch

computedfields/handlers.py

@@ -13,6 +13,7 @@
 from django.db import transaction
 from .resolver import active_resolver
 from .settings import settings
+from .signals import resolver_start, resolver_exit
 
 # typing imports
 from typing import Iterable, Type, cast
@@ -97,13 +98,15 @@ def postdelete_handler(sender: Type[Model], instance: Model, **kwargs) -> None:
     # after deletion we can update the associated computed fields
     updates = get_DELETES().pop(instance, None)
     if updates:
+        resolver_start.send(sender=active_resolver)
         with transaction.atomic():
             for model, [pks, fields] in updates.items():
                 active_resolver.bulk_updater(
                     model._base_manager.filter(pk__in=pks),
                     fields,
                     querysize=settings.COMPUTEDFIELDS_QUERYSIZE
                 )
+        resolver_exit.send(sender=active_resolver)
 
 # M2M tests: test_full.tests.test05_m2m test_full.tests.test06_m2mback test_full.tests.test_43.TestBetterM2M test_full.tests.test_m2m_advanced test_full.tests.test_norelated.TestNoReverse test_full.tests.test_proxymodels.TestProxyModelsM2M
 def m2m_handler(sender: Type[Model], instance: Model, **kwargs) -> None:
@@ -139,13 +142,15 @@ def m2m_handler(sender: Type[Model], instance: Model, **kwargs) -> None:
     elif action == 'post_remove':
         old = get_M2M_REMOVE().pop(instance, None)
         if old:
+            resolver_start.send(sender=active_resolver)
             with transaction.atomic():
                 for _model, [pks, update_fields] in old.items():
                     active_resolver.bulk_updater(
                         _model._base_manager.filter(pk__in=pks),
                         update_fields,
                         querysize=settings.COMPUTEDFIELDS_QUERYSIZE
                     )
+            resolver_exit.send(sender=active_resolver)
 
     elif action == 'pre_clear':
         get_M2M_CLEAR()[instance] = active_resolver.preupdate_dependent(
@@ -155,10 +160,12 @@ def m2m_handler(sender: Type[Model], instance: Model, **kwargs) -> None:
     elif action == 'post_clear':
         old = get_M2M_CLEAR().pop(instance, None)
         if old:
+            resolver_start.send(sender=active_resolver)
             with transaction.atomic():
                 for _model, [pks, update_fields] in old.items():
                     active_resolver.bulk_updater(
                         _model._base_manager.filter(pk__in=pks),
                         update_fields,
                         querysize=settings.COMPUTEDFIELDS_QUERYSIZE
                     )
+            resolver_exit.send(sender=active_resolver)

computedfields/resolver.py

@@ -13,6 +13,7 @@
 from .graph import ComputedModelsGraph, ComputedFieldsException, Graph, ModelGraph, IM2mMap
 from .helpers import proxy_to_base_model, slice_iterator, subquery_pk, are_same
 from . import __version__
+from .signals import resolver_start, resolver_exit, resolver_update
 
 from fast_update.fast import fast_update
 
@@ -391,7 +392,8 @@ def update_dependent(
         update_fields: Optional[Iterable[str]] = None,
         old: Optional[Dict[Type[Model], List[Any]]] = None,
         update_local: bool = True,
-        querysize: Optional[int] = None
+        querysize: Optional[int] = None,
+        _is_recursive: bool = False
     ) -> None:
         """
         Updates all dependent computed fields on related models traversing
@@ -472,6 +474,8 @@ def update_dependent(
 
         updates = self._querysets_for_update(_model, instance, _update_fields).values()
         if updates:
+            if not _is_recursive:
+                resolver_start.send(sender=self)
             with transaction.atomic():  # FIXME: place transaction only once in tree descent
                 pks_updated: Dict[Type[Model], Set[Any]] = {}
                 for queryset, fields in updates:
@@ -483,6 +487,8 @@ def update_dependent(
                         pks, fields = data
                         queryset = model2.objects.filter(pk__in=pks-pks_updated.get(model2, set()))
                         self.bulk_updater(queryset, fields, querysize=querysize)
+            if not _is_recursive:
+                resolver_exit.send(sender=self)
 
     def bulk_updater(
         self,
@@ -560,11 +566,20 @@ def bulk_updater(
             if change:
                 self._update(model._base_manager.all(), change, fields)
 
+            if pks:
+                resolver_update.send(sender=self, model=model, fields=fields, pks=pks)
+
         # trigger dependent comp field updates from changed records
         # other than before we exit the update tree early, if we have no changes at all
         # also cuts the update tree for recursive deps (tree-like)
         if not local_only and pks:
-            self.update_dependent(model._base_manager.filter(pk__in=pks), model, fields, update_local=False)
+            self.update_dependent(
+                instance=model._base_manager.filter(pk__in=pks),
+                model=model,
+                update_fields=fields,
+                update_local=False,
+                _is_recursive=True
+            )
         return set(pks) if return_pks else None
 
     def _update(self, queryset: QuerySet, change: Sequence[Any], fields: Sequence[str]) -> Union[int, None]:

computedfields/signals.py

@@ -0,0 +1,40 @@
+from django.dispatch import Signal
+
+
+# Signal sent upon start of the resolver. `sender` points to the resolver instance.
+resolver_start = Signal()
+"""Signal sent upon start of a tree update. `sender` points to the resolver instance."""
+
+
+# Signal sent after a bulk update by the resolver.
+resolver_update = Signal()
+"""
+Signal sent after a bulk update on a model.
+
+Arguments sent with this signal:
+
+- `sender`
+    Resolver instance responsible for the updates.
+- `model`
+    The model class.
+- `fields`
+    Set of computed field names, that were updated.
+- `pks`
+    List of model instance pks, that were updated.
+
+    
+Note that this signal is sent immediately after the bulk update within the whole
+(recursive) dependency tree update done by the resolver. Furthermore your handler
+will be called under the update's transaction umbrella.
+
+To not disrupt the resolver's tree update, you must avoid any raising code pattern
+in your handler code. Database interactions should be avoided, as the state is not
+fully resynced yet.
+
+Also refer to the manual on how to use this signal in a safe way.
+"""
+
+
+# Signal sent upon exit of the resolver. `sender` points to the resolver instance.
+resolver_exit = Signal()
+"""Signal sent upon exit of a tree update. `sender` points to the resolver instance."""

docs/manual.rst

@@ -425,6 +425,53 @@ we could listen to. You have 2 options to work around this issue:
         update_dependent(Entry.objects.filter(pk__in=pks), update_fields=['blog'], old=old)
 
 
+Signals
+-------
+
+Version 0.3.0 introduced 3 custom signals sent by the resolver:
+
+- `resolver_start` indicates the start of a resolver update
+- `resolver_update` sent immediately after a model's bulk update
+- `resolver_exit` indicates the exit of a resolver update
+
+The interesting signal is `resolver_update`, as it allows you to introspect,
+which computed fields on which records were updated. But since that signal is sent right away from deep within
+of the resolver's tree update, it comes with a few caveats:
+
+- still in resolver DFS recursion
+- database not fully resynced yet
+- still under the resolver's transaction umbrella
+
+
+.. WARNING::
+
+    To not compromise the resolver's DFS update, you should not use any complicated or likely-to-raise code
+    in your `resolver_update` handler. Also database interactions, especially calls to `update_dependent`,
+    should be avoided.
+
+Instead collect the interesting data points and wait for the `resolver_exit` signal.
+After that you can safely do your processing, example:
+
+.. CODE:: python
+
+    from computedfields.signals import resolver_update, resolver_exit
+
+    def collect_updates(sender, model, fields, pks):
+        # filter for updates of ModelXY.comp
+        if model == ModelXY and 'comp' in fields:
+            # only collect updated pks here
+            store_somewhere(pks)
+    resolver_update.connect(collect_updates)
+
+    def on_resolver_exit(sender):
+        # retrieve updated pks for ModelXY.comp
+        pks = retrieve_again()
+        # here it is safe to do all nasty things
+        # without compromising the resolver update
+        likely_to_fail(ModelXY.objects.filter(pk__pks))
+    resolver_exit.connect(on_resolver_exit)
+
+
 f-expressions
 -------------
 

docs/reference.rst

@@ -38,3 +38,11 @@ admin.py
 .. automodule:: computedfields.admin
    :members:
    :show-inheritance:
+
+
+signals.py
+----------
+
+.. automodule:: computedfields.signals
+   :members:
+   :show-inheritance: