docs for expanding updates on neighboring models

Author: jerch

docs/examples.rst

@@ -309,6 +309,174 @@ limited for m2m fields. Also see below under optimization examples.
     as much as possible.
 
 
+Multi Table Inheritance
+-----------------------
+
+.. |br| raw:: html
+
+   <br />
+
+
+Multi table inheritance works with computed fields with some restrictions you have to be aware of.
+The following requires basic knowledge about multi table inheritance in Django and its similarities
+to o2o relations on accessor level (also see official Django docs).
+
+Neighboring Models
+^^^^^^^^^^^^^^^^^^
+
+Let's illustrate dealing with updates from neighboring models with an example.
+(Note: The example can also be found in `example.test_full` under `tests/test_multi_table_example.py`)
+
+.. code-block:: python
+
+    from django.db import models
+    from computedfields.models import ComputedFieldsModel, computed
+
+    class User(ComputedFieldsModel):
+        forname = models.CharField(max_length=32)
+        surname = models.CharField(max_length=32)
+
+        @computed(models.CharField(max_length=64), depends=[
+            ['self', ['forname', 'surname']]
+        ])
+        def fullname(self):
+            return '{}, {}'.format(self.surname, self.forname)
+
+    class EmailUser(User):
+        email = models.CharField(max_length=32)
+
+        @computed(models.CharField(max_length=128), depends=[
+            ['self', ['email', 'fullname']],
+            ['user_ptr', ['fullname']]          # trigger updates from User type as well
+        ])
+        def email_contact(self):
+            return '{} <{}>'.format(self.fullname, self.email)
+
+    class Work(ComputedFieldsModel):
+        subject = models.CharField(max_length=32)
+        user = models.ForeignKey(User, on_delete=models.CASCADE)
+
+        @computed(models.CharField(max_length=64), depends=[
+            ['self', ['subject']],
+            ['user', ['fullname']],
+            ['user.emailuser', ['fullname']]    # trigger updates from EmailUser type as well
+        ])
+        def descriptive_assigment(self):
+            return '"{}" is assigned to "{}"'.format(self.subject, self.user.fullname)
+
+In the example there are two surprising `depends` rules:
+
+    1. ``['user_ptr', ['fullname']]`` on ``EmailUser.email_contact``
+    2. ``['user.emailuser', ['fullname']]`` on ``Work.descriptive_assigment``
+
+Both are needed to expand the update rules in a way, that parent or derived models are also respected
+for the field updates. While the first rule extends updates to the parent model `User`
+(ascending in the model inheritance), the second one expands updates to a descendant.
+
+*Why do I have to create those counter-intuitive rules?*
+
+Currently the resolver does not expand on multi table inheritance automatically.
+Furthermore it might not be wanted in all circumstances, that parent or derived models
+trigger updates on other ends. Thus it has to be set explicitly (might change with future versions,
+if highly demanded).
+
+*When do I have to place those additional rules?*
+
+In general the resolver updates computed fields only from model-field associations,
+that were explicitly given in `depends` rules. Therefore it will not catch changes on
+parent or derived models.
+
+In the example above without the first rule any changes to an instance of `User` will not
+trigger a recalculation of ``EmailUser.email_contact``. This is most likely unwanted behavior for this
+particular example, as anyone would expect, that changing parts of the name should update the email contact
+information here.
+
+Without the second rule, ``Work.descriptive_assigment`` will not be updated from changes of an
+`EmailUser` instance, which again is probably unwanted, as anyone would expect `EmailUser` to behave
+like a `User` instance here.
+
+*How to derive those rules?*
+
+To understand, how to construct those additional rules, we have to look first at the rules,
+they are derived from:
+
+- first one is derived from ``['self', ['email', 'fullname']]``
+- second one is derived from ``['user', ['fullname']]``
+
+**Step 1 - check, whether the path ends on multi table model**
+
+Looking at the relation paths (left side of the rules), both have something in common - they both end
+on a model with multi table inheritance (`self` in 1. pointing to `EmailUser` model,
+`user` in 2. pointing to `User` model). So whenever a relation ends on a multi table model,
+there is a high chance, that you might want to apply additional rules for neighboring models.
+
+**Step 2 - derive new relational path from model inheritance**
+
+Next question is, whether you want to expand ascending or descending or both in the model inheritance:
+
+- For ascending expansion append the o2o field name denoting the parent model.
+- For descending expansion append reverse o2o relation name pointing to the derived model.
+
+(Note: If a relation expands on `self` entries, `self` has to removed from the path.)
+
+At this point it is important to know, how Django denotes multi table relations on model field level.
+By default the o2o field is placed on the descendent model as `modelname_ptr`, while the reverse relation
+gets the child modelname on the ancestor model as `modelname` (all lowercase).
+
+In the example above ascending from `EmailUser` to `User` creates a relational path `user_ptr`,
+while descending from `User` to `EmailUser` needs a relational path of `emailuser`.
+
+**Step 3 - apply fieldnames on right side**
+
+For descending rules you can just copy over the field names on the right side. For the descent from
+`User` to `EmailUser` we finally get:
+
+- ``['user.emailuser', ['fullname']]``
+
+to be added to `depends` on ``Work.descriptive_assigment``.
+
+For ascending rules you should be careful not to copy over field names on the right side, that are defined on
+descendent models. After removing `email` from the field names we finally get for the ascent from `EmailUser`
+to `User`:
+
+- ``['user_ptr', ['fullname']]``
+
+to be added to `depends` on ``EmailUser.email_contact``.
+
+Up-Pulling Fields
+^^^^^^^^^^^^^^^^^
+
+The resolver has a special rule for handling dependencies to fields on derived multi table models.
+Therefore it is possible to create a computed field on the parent model, that conditionally
+updates from different descendent model fields, example:
+
+.. code-block:: python
+
+    class Base(ComputedFieldsModel):
+        @computed(models.CharField(max_length=32), depends=[
+            ['a', ['type']],        # pull type field from A descendant
+            ['b', ['type']],        # pull type field from B descendant
+            ['b.c', ['subtype']]    # pull subtype field from C descendant
+        ])
+        def type(self):
+            if hasattr(self, 'a'):
+                return a.type
+            if hasattr(self, 'b'):
+                if hasattr(self, 'b'):
+                    return self.b.c.subtype
+                return b.type
+            return ''
+
+    class A(Base):
+        type = models.CharField(max_length=32, default='a')
+    class B(Base):
+        type = models.CharField(max_length=32, default='b')
+    class C(B):
+        subtype = models.CharField(max_length=32, default='sub-c')
+
+Note that you have to guard the attribute access yourself in the method code.
+
+
 Forced Update of Computed Fields
 --------------------------------
 

docs/manual.rst

@@ -316,15 +316,13 @@ on abstract models or on the final model. They are treated as local computed fie
 Multi Table Inheritance
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Multi table inheritance is currently treated as **not** supported.
-It still works with the following restrictions:
+Multi table inheritance is supported with the following restriction:
 
-- No up- or downcasting yet, therefore updates are only triggered on the model, that was given
-  to `update_dependent`. It is currently your responsibility to either invoke `update_dependent`
-  for derived or parent models as well, or to mark the dependency correctly via its o2o relation.
-- Conditional "up-pulling" (depending on values from certain derived models) does not work.
+.. NOTE::
+
+    **No automatic up- or downcasting** - the resolver strictly limits updates to model types listed in `depends`.
+    Also see example documentation on how to expand updates to neighboring model types manually.
 
-(This will change with future versions.)
 
 Proxy Models
 ^^^^^^^^^^^^

example/test_full/models.py

@@ -777,6 +777,7 @@ def backward_name(self):
         except type(self).o.RelatedObjectDoesNotExist:
             return ''
 
+
 # multi table tests
 class MtRelated(models.Model):
     name = models.CharField(max_length=32)
@@ -829,7 +830,6 @@ class MtSubDerived(MtDerived2):
     sub = models.CharField(max_length=32)
 
 
-
 # Test classes for multi table inheritance support
 class ParentModel(ComputedFieldsModel):
     x = models.IntegerField(default=0)
@@ -887,6 +887,7 @@ class DependsOnParentComputed(ComputedFieldsModel):
     def z2(self):
         return self.parent.z * 2
 
+
 # ptr based multi table access
 class MtPtrBase(models.Model):
   basename = models.CharField(max_length=32)
@@ -898,3 +899,35 @@ class MtPtrDerived(MtPtrBase, ComputedFieldsModel):
   ])
   def comp(self):
       return self.basename
+
+
+# test multi table example in docs
+class User(ComputedFieldsModel):
+    forname = models.CharField(max_length=32)
+    surname = models.CharField(max_length=32)
+
+    @computed(models.CharField(max_length=64), depends=[['self', ['forname', 'surname']]])
+    def fullname(self):
+        return '{}, {}'.format(self.surname, self.forname)
+
+class EmailUser(User):
+    email = models.CharField(max_length=32)
+
+    @computed(models.CharField(max_length=128), depends=[
+        ['self', ['email', 'fullname']],
+        ['user_ptr', ['fullname']]          # trigger updates from User type as well
+    ])
+    def email_contact(self):
+        return '{} <{}>'.format(self.fullname, self.email)
+
+class Work(ComputedFieldsModel):
+    subject = models.CharField(max_length=32)
+    user = models.ForeignKey(User, on_delete=models.CASCADE)
+
+    @computed(models.CharField(max_length=64), depends=[
+        ['self', ['subject']],
+        ['user', ['fullname']],
+        ['user.emailuser', ['fullname']]    # trigger updates from EmailUser type as well
+    ])
+    def descriptive_assigment(self):
+        return '"{}" is assigned to "{}"'.format(self.subject, self.user.fullname)

example/test_full/tests/test_multitable_example.py

@@ -0,0 +1,56 @@
+from django.test import TestCase
+from ..models import User, EmailUser, Work
+
+
+class TestUserMultiTable(TestCase):
+    def setUp(self):
+        self.normal_user = User.objects.create(forname='John', surname='Doe')
+        self.email_user = EmailUser.objects.create(forname='Sally', surname='Housecoat', email='s.h@example.com')
+        self.work1 = Work.objects.create(subject='close window', user=self.normal_user)
+        self.work2 = Work.objects.create(subject='open door', user=self.email_user)
+
+    def test_initial(self):
+        # working on local fields should correctly update all fields including those on parent models
+        self.assertEqual(self.normal_user.fullname, 'Doe, John')
+        self.assertEqual(self.email_user.fullname, 'Housecoat, Sally')
+        self.assertEqual(self.email_user.email_contact, 'Housecoat, Sally <s.h@example.com>')
+        self.assertEqual(self.work1.descriptive_assigment, '"close window" is assigned to "Doe, John"')
+        self.assertEqual(self.work2.descriptive_assigment, '"open door" is assigned to "Housecoat, Sally"')
+
+    def test_change_surname_on_user(self):
+        john = User.objects.get(forname='John')
+        john.surname = 'Bow'
+        john.save(update_fields=['surname'])
+        john.refresh_from_db()
+        self.assertEqual(john.fullname, 'Bow, John')
+
+        sally = User.objects.get(forname='Sally')
+        sally.surname = 'Houseboat'
+        sally.save(update_fields=['surname'])
+        sally.refresh_from_db()
+        self.assertEqual(sally.fullname, 'Houseboat, Sally')
+        
+        # this only updates .email_contact correctly with ['user_ptr', ['fullname']] in depends
+        # (ascending rule to extend EmailUser to User)
+        self.email_user.refresh_from_db()
+        self.assertEqual(self.email_user.email_contact, 'Houseboat, Sally <s.h@example.com>')
+
+        # this updates correctly since User got updated
+        self.work1.refresh_from_db()
+        self.assertEqual(self.work1.descriptive_assigment, '"close window" is assigned to "Bow, John"')
+        self.work2.refresh_from_db()
+        self.assertEqual(self.work2.descriptive_assigment, '"open door" is assigned to "Houseboat, Sally"')
+
+    def test_change_surname_on_emailuser(self):
+        sally = EmailUser.objects.get(forname='Sally')
+        sally.surname = 'Houseboat'
+        sally.save(update_fields=['surname'])
+
+        # this work correctly since .fullname is treated as local field
+        sally.refresh_from_db()
+        self.assertEqual(sally.fullname, 'Houseboat, Sally')
+
+        # .descriptive_assigment only updates correctly with ['user.emailuser', ['fullname']] in depends
+        # (descending rule to extend User to EmailUser)
+        self.work2.refresh_from_db()
+        self.assertEqual(self.work2.descriptive_assigment, '"open door" is assigned to "Houseboat, Sally"')