django-field-audit 1.2.9__py2.py3-none-any.whl → 1.3.0__py2.py3-none-any.whl

{django_field_audit-1.2.9.dist-info → django_field_audit-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: django-field-audit
-Version: 1.2.9
+Version: 1.3.0
 Summary: Audit Field Changes on Django Models
 Home-page: https://github.com/dimagi/django-field-audit
 Maintainer: Joel Miller
@@ -177,6 +177,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

{django_field_audit-1.2.9.dist-info → django_field_audit-1.3.0.dist-info}/RECORD

@@ -1,19 +1,20 @@
-field_audit/__init__.py,sha256=ukvhgwNNpEmH3wqrM6bBaNi4fH-ORfPzcyDbeWUcvnA,75
+field_audit/__init__.py,sha256=nqzFkr4OZWLY-xTZ5-uZhnh-Rp6iEV2tP0jPeExcq0s,75
 field_audit/apps.py,sha256=04NYTi54zEuYPAhxEvsS61hmoPMIMVfPQKi4DOa9nE0,265
 field_audit/auditors.py,sha256=V5Ese7w4V_WTLklIm5EOsjOJ3t4Iwp69AmgwxNXD33Y,4292
 field_audit/const.py,sha256=U7c5Y4a5YjmvaZjsUpDhdTOvkcoaS5aqFf_L3C5GtYk,1135
-field_audit/field_audit.py,sha256=qPHke6cpeWre6jFodiWsDIkyxKwCStDBtunQjUIwCZ8,5891
+field_audit/field_audit.py,sha256=dy3TMOeKJiNGy4XainDN2wvx-FJzwq_YgDTH8aLVOnY,8698
 field_audit/middleware.py,sha256=JQMdM1vITddHFCqIX_M8_UDIvbCKU8BhY_sWccGVS-Y,468
-field_audit/models.py,sha256=0MaZa3M2he6yrP-lQ09atCwSWFaPT-F_6RpzobQnUA0,29728
+field_audit/models.py,sha256=8EeWtA6lC7xtm-G8Dx44nN-nHcxAxJbMQOd5kjr_EAQ,31663
 field_audit/utils.py,sha256=tILEuWG8JCP98vWsZckdpcjcNi5BlBDbBGDma_WVIlc,3437
 field_audit/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 field_audit/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 field_audit/management/commands/bootstrap_field_audit_events.py,sha256=QN8PNKqTM-_8qHQX10xa6RjxvZMvoLkhNb_PfTYfr-k,4263
 field_audit/migrations/0001_initial.py,sha256=UXnmSkG8ZZmh-4DrqYACH9LSJ0Mh74nW0u_yKdS1ctg,1297
 field_audit/migrations/0002_add_is_bootstrap_column.py,sha256=lkPNMk9Kb6IeaX9E08Snar-0_zr1epVrW9VSq24f9Ns,972
+field_audit/migrations/0003_alter_auditevent_change_context_and_more.py,sha256=0MxLTzKAGCsIc6674-RZc6wGImbHpy5D069fTPbCjak,933
 field_audit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_field_audit-1.2.9.dist-info/LICENSE,sha256=DUmNjtND8byIKaTpjoksSUVazUJ_-3sPWOyyLiOvyDs,1508
-django_field_audit-1.2.9.dist-info/METADATA,sha256=K2B20mIRsOpglILDX4jEcjOn2muUuWZ3sFsMBI0ZiLE,10564
-django_field_audit-1.2.9.dist-info/WHEEL,sha256=9Hm2OB-j1QcCUq9Jguht7ayGIIZBRTdOXD1qg9cCgPM,109
-django_field_audit-1.2.9.dist-info/top_level.txt,sha256=wa_olzk0PU62yd5m6tScO-flaKF_xQyLIV_hZY0vi38,12
-django_field_audit-1.2.9.dist-info/RECORD,,
+django_field_audit-1.3.0.dist-info/LICENSE,sha256=DUmNjtND8byIKaTpjoksSUVazUJ_-3sPWOyyLiOvyDs,1508
+django_field_audit-1.3.0.dist-info/METADATA,sha256=VsvochcqmC3JBnJ-5BuWhtDSY2X2ky1Pta2pGg6Ng8c,11952
+django_field_audit-1.3.0.dist-info/WHEEL,sha256=9Hm2OB-j1QcCUq9Jguht7ayGIIZBRTdOXD1qg9cCgPM,109
+django_field_audit-1.3.0.dist-info/top_level.txt,sha256=wa_olzk0PU62yd5m6tScO-flaKF_xQyLIV_hZY0vi38,12
+django_field_audit-1.3.0.dist-info/RECORD,,

field_audit/__init__.py

@@ -1,3 +1,3 @@
 from .field_audit import audit_fields  # noqa: F401
 
-__version__ = "1.2.9"
+__version__ = "1.3.0"

field_audit/field_audit.py

@@ -2,6 +2,7 @@ import contextvars
 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 audit_fields(*field_names, class_path=None, audit_special_queryset_writes=Fa
         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 _decorate_refresh_from_db(func):
     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/migrations/0003_alter_auditevent_change_context_and_more.py

@@ -0,0 +1,32 @@
+# Generated by Django 5.1.6 on 2025-06-27 15:11
+
+import django.core.serializers.json
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('field_audit', '0002_add_is_bootstrap_column'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='auditevent',
+            name='change_context',
+            field=models.JSONField(
+                encoder=django.core.serializers.json.DjangoJSONEncoder),
+        ),
+        migrations.AlterField(
+            model_name='auditevent',
+            name='delta',
+            field=models.JSONField(
+                encoder=django.core.serializers.json.DjangoJSONEncoder),
+        ),
+        migrations.AlterField(
+            model_name='auditevent',
+            name='object_pk',
+            field=models.JSONField(
+                encoder=django.core.serializers.json.DjangoJSONEncoder),
+        ),
+    ]

field_audit/models.py

@@ -3,6 +3,7 @@ from functools import wraps
 from itertools import islice
 
 from django.conf import settings
+from django.core.serializers.json import DjangoJSONEncoder
 from django.db import models, transaction
 from django.db.models import Expression
 from django.utils import timezone
@@ -203,12 +204,12 @@ def get_date():
 class AuditEvent(models.Model):
     event_date = models.DateTimeField(default=get_date, db_index=True)
     object_class_path = models.CharField(db_index=True, max_length=255)
-    object_pk = models.JSONField()
-    change_context = models.JSONField()
+    object_pk = models.JSONField(encoder=DjangoJSONEncoder)
+    change_context = models.JSONField(encoder=DjangoJSONEncoder)
     is_create = models.BooleanField(default=False)
     is_delete = models.BooleanField(default=False)
     is_bootstrap = models.BooleanField(default=False)
-    delta = models.JSONField()
+    delta = models.JSONField(encoder=DjangoJSONEncoder)
 
     objects = get_manager("AUDITEVENT_MANAGER", DefaultAuditEventManager)
 
@@ -226,6 +227,7 @@ class AuditEvent(models.Model):
 
     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):
@@ -245,13 +247,19 @@ class AuditEvent(models.Model):
         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
@@ -275,6 +283,44 @@ class AuditEvent(models.Model):
         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
@@ -396,7 +442,6 @@ class AuditEvent(models.Model):
             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)
@@ -471,7 +516,9 @@ class AuditEvent(models.Model):
             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,