Merge pull request #40 from dimagi/sk/serialization

Add ManyToManyField serialization support

Author: snopoke

README.md

@@ -140,6 +140,44 @@ details:
   are only committed to the database if audit events are successfully created
   and saved as well.
 
+### Auditing Many-to-Many fields
+
+Many-to-Many field changes are automatically audited through Django signals when
+included in the `@audit_fields` decorator. Changes to M2M relationships generate
+audit events immediately without requiring `save()` calls.
+
+```python
+# Example model with audited M2M field
+@audit_fields("name", "title", "certifications")
+class CrewMember(models.Model):
+    name = models.CharField(max_length=256)
+    title = models.CharField(max_length=64)
+    certifications = models.ManyToManyField('Certification', blank=True)
+```
+
+#### Supported M2M operations
+
+All standard M2M operations create audit events:
+
+```python
+crew_member = CrewMember.objects.create(name='Test Pilot', title='Captain')
+cert1 = Certification.objects.create(name='PPL', certification_type='Private')
+
+crew_member.certifications.add(cert1)         # Creates audit event
+crew_member.certifications.remove(cert1)      # Creates audit event
+crew_member.certifications.set([cert1])       # Creates audit event
+crew_member.certifications.clear()            # Creates audit event
+```
+
+#### M2M audit event structure
+
+M2M changes use specific delta structures in audit events:
+
+- **Add**: `{'certifications': {'add': [1, 2]}}`
+- **Remove**: `{'certifications': {'remove': [2]}}`
+- **Clear**: `{'certifications': {'remove': [1, 2]}}`
+- **Create** / **Bootstrap**: `{'certifications': {'new': []}}`
+
 #### Bootstrap events for models with existing records
 
 In the scenario where auditing is enabled for a model with existing data, it can

field_audit/field_audit.py

@@ -2,6 +2,7 @@
 from functools import wraps
 
 from django.db import models, router, transaction
+from django.db.models.signals import m2m_changed
 
 from .utils import get_fqcn
 
@@ -63,6 +64,8 @@ def wrapper(cls):
         cls.save = _decorate_db_write(cls.save)
         cls.delete = _decorate_db_write(cls.delete)
         cls.refresh_from_db = _decorate_refresh_from_db(cls.refresh_from_db)
+
+        _register_m2m_signals(cls, field_names)
         _audited_models[cls] = get_fqcn(cls) if class_path is None else class_path  # noqa: E501
         return cls
     if not field_names:
@@ -154,6 +157,86 @@ def wrapper(self, using=None, fields=None, **kwargs):
     return wrapper
 
 
+def _register_m2m_signals(cls, field_names):
+    """Register m2m_changed signal handlers for ManyToManyFields.
+
+    :param cls: The model class being audited
+    :param field_names: List of field names that are being audited
+    """
+    for field_name in field_names:
+        try:
+            field = cls._meta.get_field(field_name)
+            if isinstance(field, models.ManyToManyField):
+                m2m_changed.connect(
+                    _m2m_changed_handler,
+                    sender=field.remote_field.through,
+                    weak=False
+                )
+        except Exception:
+            # If field doesn't exist or isn't a M2M field, continue
+            continue
+
+
+def _m2m_changed_handler(sender, instance, action, pk_set, **kwargs):
+    """Signal handler for m2m_changed to audit ManyToManyField changes.
+
+    :param sender: The intermediate model class for the ManyToManyField
+    :param instance: The instance whose many-to-many relation is updated
+    :param action: A string indicating the type of update
+    :param pk_set: For add/remove actions, set of primary key values
+    """
+    from .models import AuditEvent
+
+    if action not in ('post_add', 'post_remove', 'post_clear', 'pre_clear'):
+        return
+
+    if type(instance) not in _audited_models:
+        return
+
+    # Find which M2M field this change relates to
+    m2m_field = None
+    field_name = None
+    for field in instance._meta.get_fields():
+        if (
+            isinstance(field, models.ManyToManyField) and
+            hasattr(field, 'remote_field') and
+            field.remote_field.through == sender
+        ):
+            m2m_field = field
+            field_name = field.name
+            break
+
+    if not m2m_field or field_name not in AuditEvent.field_names(instance):
+        return
+
+    if action == 'pre_clear':
+        # `pk_set` not supplied for clear actions. Determine initial values
+        # in the `pre_clear` event
+        AuditEvent.attach_initial_m2m_values(instance, field_name)
+        return
+
+    if action == 'post_clear':
+        initial_values = AuditEvent.get_initial_m2m_values(instance, field_name)
+        if not initial_values:
+            return
+        delta = {field_name: {'remove': initial_values}}
+    else:
+        if not pk_set:
+            # the change was a no-op
+            return
+        delta_key = 'add' if action == 'post_add' else 'remove'
+        delta = {field_name: {delta_key: list(pk_set)}}
+
+    req = request.get()
+    event = AuditEvent.create_audit_event(
+        instance.pk, instance.__class__, delta, False, False, req
+    )
+    if event is not None:
+        event.save()
+
+    AuditEvent.clear_initial_m2m_field_values(instance, field_name)
+
+
 def get_audited_models():
     return _audited_models.copy()
 

field_audit/models.py

@@ -227,6 +227,7 @@ class Meta:
 
     ATTACH_FIELD_NAMES_AT = "__field_audit_field_names"
     ATTACH_INIT_VALUES_AT = "__field_audit_init_values"
+    ATTACH_INIT_M2M_VALUES_AT = "__field_audit_init_m2m_values"
 
     @classmethod
     def attach_field_names(cls, model_class, field_names):
@@ -246,13 +247,19 @@ def field_names(cls, model_class):
         return getattr(model_class, cls.ATTACH_FIELD_NAMES_AT)
 
     @staticmethod
-    def get_field_value(instance, field_name):
+    def get_field_value(instance, field_name, bootstrap=False):
         """Returns the database value of a field on ``instance``.
 
         :param instance: an instance of a Django model
         :param field_name: name of a field on ``instance``
         """
         field = instance._meta.get_field(field_name)
+
+        if isinstance(field, models.ManyToManyField):
+            # ManyToManyField handled by Django signals
+            if bootstrap:
+                return AuditEvent.get_m2m_field_value(instance, field_name)
+            return []
         return field.to_python(field.value_from_object(instance))
 
     @classmethod
@@ -276,6 +283,44 @@ def attach_initial_values(cls, instance):
         init_values = {f: cls.get_field_value(instance, f) for f in field_names}
         setattr(instance, cls.ATTACH_INIT_VALUES_AT, init_values)
 
+    @classmethod
+    def attach_initial_m2m_values(cls, instance, field_name):
+        field = instance._meta.get_field(field_name)
+        if not isinstance(field, models.ManyToManyField):
+            return None
+
+        values = cls.get_m2m_field_value(instance, field_name)
+        init_values = getattr(
+            instance, cls.ATTACH_INIT_M2M_VALUES_AT, None
+        ) or {}
+        init_values.update({field_name: values})
+        setattr(instance, cls.ATTACH_INIT_M2M_VALUES_AT, init_values)
+
+    @classmethod
+    def get_initial_m2m_values(cls, instance, field_name):
+        init_values = getattr(
+            instance, cls.ATTACH_INIT_M2M_VALUES_AT, None
+        ) or {}
+        return init_values.get(field_name)
+
+    @classmethod
+    def clear_initial_m2m_field_values(cls, instance, field_name):
+        init_values = getattr(
+            instance, cls.ATTACH_INIT_M2M_VALUES_AT, None
+        ) or {}
+        init_values.pop(field_name, None)
+        setattr(instance, cls.ATTACH_INIT_M2M_VALUES_AT, init_values)
+
+    @classmethod
+    def get_m2m_field_value(cls, instance, field_name):
+        if instance.pk is None:
+            # Instance is not saved, return empty list
+            return []
+        else:
+            # Instance is saved, we can access the related objects
+            related_manager = getattr(instance, field_name)
+            return list(related_manager.values_list('pk', flat=True))
+
     @classmethod
     def reset_initial_values(cls, instance):
         """Returns the previously attached "initial values" and attaches new
@@ -397,7 +442,6 @@ def make_audit_event_from_instance(cls, instance, is_create, is_delete,
             object_pk = instance.pk
 
         delta = cls.get_delta_from_instance(instance, is_create, is_delete)
-
         if delta:
             return cls.create_audit_event(object_pk, type(instance), delta,
                                           is_create, is_delete, request)
@@ -472,7 +516,9 @@ def iter_events():
             for instance in iter_records():
                 delta = {}
                 for field_name in field_names:
-                    value = cls.get_field_value(instance, field_name)
+                    value = cls.get_field_value(
+                        instance, field_name, bootstrap=True
+                    )
                     delta[field_name] = {"new": value}
                 yield cls(
                     object_class_path=object_class_path,

tests/models.py

@@ -10,6 +10,7 @@
     ForeignKey,
     IntegerField,
     JSONField,
+    ManyToManyField,
 )
 
 from field_audit import audit_fields
@@ -41,12 +42,13 @@ def save(self, *args, **kwargs):
         super().save(*args, **kwargs)
 
 
-@audit_fields("name", "title", "flight_hours")
+@audit_fields("name", "title", "flight_hours", "certifications")
 class CrewMember(Model):
     id = AutoField(primary_key=True)
     name = CharField(max_length=256)
     title = CharField(max_length=64)
     flight_hours = DecimalField(max_digits=10, decimal_places=4, default=0.0)
+    certifications = ManyToManyField('Certification', blank=True)
 
 
 @audit_fields("tail_number", "make_model", "operated_by")
@@ -109,3 +111,10 @@ class PkAuto(Model):
 @audit_fields("id")
 class PkJson(Model):
     id = JSONField(primary_key=True)
+
+
+@audit_fields("name", "certification_type")
+class Certification(Model):
+    id = AutoField(primary_key=True)
+    name = CharField(max_length=128)
+    certification_type = CharField(max_length=64)

tests/test_field_audit.py

@@ -21,6 +21,7 @@
 from .models import (
     Aerodrome,
     Aircraft,
+    Certification,
     CrewMember,
     Flight,
     SimpleModel,
@@ -123,6 +124,7 @@ def test_get_audited_models(self):
                 Aerodrome,
                 Aircraft,
                 CrewMember,
+                Certification,
                 Flight,
                 SimpleModel,
                 ModelWithAuditingManager,