django-field-audit 1.2.8__tar.gz → 1.3.0__tar.gz

{django-field-audit-1.2.8/django_field_audit.egg-info → django_field_audit-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: django-field-audit
-Version: 1.2.8
+Version: 1.3.0
 Summary: Audit Field Changes on Django Models
 Home-page: https://github.com/dimagi/django-field-audit
 Maintainer: Joel Miller
@@ -26,6 +26,14 @@ Classifier: Framework :: Django :: 4.2
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: summary
 
 # Audit Field Changes on Django Models
 
@@ -169,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.8/PKG-INFO → django_field_audit-1.3.0/README.md

@@ -1,32 +1,3 @@
-Metadata-Version: 2.1
-Name: django-field-audit
-Version: 1.2.8
-Summary: Audit Field Changes on Django Models
-Home-page: https://github.com/dimagi/django-field-audit
-Maintainer: Joel Miller
-Maintainer-email: jmiller@dimagi.com
-License: BSD License
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Web Environment
-Classifier: Framework :: Django
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 3
-Classifier: Framework :: Django :: 3.2
-Classifier: Framework :: Django :: 4
-Classifier: Framework :: Django :: 4.2
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 # Audit Field Changes on Django Models
 
 [![tests][tests_badge]][tests_link]
@@ -169,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

django-field-audit-1.2.8/README.md → django_field_audit-1.3.0/django_field_audit.egg-info/PKG-INFO

@@ -1,3 +1,40 @@
+Metadata-Version: 2.2
+Name: django-field-audit
+Version: 1.3.0
+Summary: Audit Field Changes on Django Models
+Home-page: https://github.com/dimagi/django-field-audit
+Maintainer: Joel Miller
+Maintainer-email: jmiller@dimagi.com
+License: BSD License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4
+Classifier: Framework :: Django :: 4.2
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: summary
+
 # Audit Field Changes on Django Models
 
 [![tests][tests_badge]][tests_link]
@@ -140,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.8 → django_field_audit-1.3.0}/django_field_audit.egg-info/SOURCES.txt

@@ -19,4 +19,14 @@ field_audit/management/commands/__init__.py
 field_audit/management/commands/bootstrap_field_audit_events.py
 field_audit/migrations/0001_initial.py
 field_audit/migrations/0002_add_is_bootstrap_column.py
-field_audit/migrations/__init__.py
+field_audit/migrations/0003_alter_auditevent_change_context_and_more.py
+field_audit/migrations/__init__.py
+tests/test_apps.py
+tests/test_auditors.py
+tests/test_bootstrap_field_audit_events.py
+tests/test_django_compat.py
+tests/test_field_audit.py
+tests/test_m2m.py
+tests/test_middleware.py
+tests/test_models.py
+tests/test_utils.py

{django-field-audit-1.2.8 → django_field_audit-1.3.0}/field_audit/__init__.py

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

{django-field-audit-1.2.8 → django_field_audit-1.3.0}/field_audit/auditors.py

@@ -107,7 +107,7 @@ class SystemUserAuditor(BaseAuditor):
             try:
                 # get owner of STDIN file on login sessions (e.g. SSH)
                 output = check_output(["who", "-m"], stderr=DEVNULL)
-            except CalledProcessError:
+            except (FileNotFoundError, CalledProcessError):
                 self.has_who_bin = False
             else:
                 if output:

{django-field-audit-1.2.8 → django_field_audit-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()
 

django_field_audit-1.3.0/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),
+        ),
+    ]

{django-field-audit-1.2.8 → django_field_audit-1.3.0}/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,

{django-field-audit-1.2.8 → django_field_audit-1.3.0}/setup.cfg

@@ -6,7 +6,9 @@ license_file = LICENSE
 
 [flake8]
 max-line-length = 80
-exclude = ./build
+exclude = 
+	./build
+	.venv
 
 [egg_info]
 tag_build = 

django_field_audit-1.3.0/tests/test_apps.py

@@ -0,0 +1,18 @@
+from django.apps import apps
+from django.test import TestCase
+
+from field_audit.auditors import audit_dispatcher
+
+
+class TestFieldAuditConfig(TestCase):
+
+    def test_config_ready_sets_auditors(self):
+        # ensure it's not empty already
+        self.assertNotEqual([], audit_dispatcher.auditors)
+        try:
+            audit_dispatcher.auditors = []
+            apps.get_app_config("field_audit").ready()
+            self.assertNotEqual([], audit_dispatcher.auditors)
+        finally:
+            # reset to defaults
+            audit_dispatcher.setup_auditors()