django-field-audit 1.2.9__tar.gz → 1.4.0__tar.gz

{django_field_audit-1.2.9/django_field_audit.egg-info → django_field_audit-1.4.0}/PKG-INFO

@@ -1,12 +1,11 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: django-field-audit
-Version: 1.2.9
+Version: 1.4.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
+Author-email: Joel Miller <jmiller@dimagi.com>, Simon Kelly <simongdkelly@gmail.com>, Graham Herceg <gherceg@dimagi.com>, Chris Smit <chris.smit@dimagi.com>, Daniel Miller <millerdev@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
 Classifier: Intended Audience :: Developers
@@ -18,22 +17,11 @@ 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
+Requires-Dist: django>=3.2
+Project-URL: Homepage, https://github.com/dimagi/django-field-audit
+Project-URL: Repository, https://github.com/dimagi/django-field-audit
 
 # Audit Field Changes on Django Models
 
@@ -102,6 +90,42 @@ FIELD_AUDIT_AUDITORS = []
 |:----------------------------------|:---------------------------------------------------------------|:------------------------
 | `FIELD_AUDIT_AUDITEVENT_MANAGER`  | A custom manager to use for the `AuditEvent` Model.            | `field_audit.models.DefaultAuditEventManager`
 | `FIELD_AUDIT_AUDITORS`            | A custom list of auditors for acquiring `change_context` info. | `["field_audit.auditors.RequestAuditor", "field_audit.auditors.SystemUserAuditor"]`
+| `FIELD_AUDIT_SERVICE_CLASS`       | A custom service class for audit logic implementation.         | `field_audit.services.AuditService`
+
+### Custom Audit Service
+
+The audit logic has been extracted into a separate `AuditService` class to improve separation of concerns and enable easier customization of audit behavior. Users can provide custom audit implementations by subclassing `AuditService` and configuring the `FIELD_AUDIT_SERVICE_CLASS` setting.
+
+#### Creating a Custom Audit Service
+
+```python
+# myapp/audit.py
+
+from field_audit import AuditService
+
+class CustomAuditService(AuditService):
+    def get_field_value(self, instance, field_name, bootstrap=False):
+        # Custom logic for extracting field values
+        value = super().get_field_value(instance, field_name, bootstrap)
+        
+        # Example: custom serialization or transformation
+        if field_name == 'sensitive_field':
+            value = '[REDACTED]'
+            
+        return value
+```
+
+Then configure it in your Django settings:
+
+```python
+# settings.py
+
+FIELD_AUDIT_SERVICE_CLASS = 'myapp.audit.CustomAuditService'
+```
+
+#### Backward Compatibility
+
+The original `AuditEvent` class methods are maintained for backward compatibility but are now deprecated in favor of the service-based approach. These methods will issue deprecation warnings and delegate to the configured audit service.
 
 ### Model Auditing
 
@@ -177,6 +201,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
@@ -242,12 +304,11 @@ All feature and bug contributions are expected to be covered by tests.
 
 ### Setup for developers
 
-Create/activate a python virtualenv and install the required dependencies.
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management. Install uv and then install the project dependencies:
 
 ```shell
 cd django-field-audit
-mkvirtualenv django-field-audit  # or however you choose to setup your environment
-pip install django pynose flake8 coverage
+uv sync
 ```
 
 ### Running tests
@@ -258,18 +319,18 @@ your local Python's `sqlite3` library ships with the `JSON1` extension enabled
 
 - Tests
   ```shell
-  nosetests
+  uv run pytest
   ```
 
 - Style check
   ```shell
-  flake8 --config=setup.cfg
+  ruff check
   ```
 
 - Coverage
   ```shell
-  coverage run -m nose
-  coverage report -m
+  uv run coverage run -m pytest
+  uv run coverage report -m
   ```
 
 ### Adding migrations
@@ -277,30 +338,25 @@ your local Python's `sqlite3` library ships with the `JSON1` extension enabled
 The example `manage.py` is available for making new migrations.
 
 ```shell
-python example/manage.py makemigrations field_audit
+uv run python example/manage.py makemigrations field_audit
 ```
 
-### Uploading to PyPI
+### Publishing a new version to PyPI
 
-First bump the package version in the `field_audit/__init__.py` file. Then create a changelog entry in the CHANGELOG.md
-file. After these changes are merged, you should tag the main branch with the new version. Then, package and upload the generated files to PyPI.
+Push a new tag to Github using the format vX.Y.Z where X.Y.Z matches the version
+in [`__init__.py`](field_audit/__init__.py). Also ensure that the changelog is up to date.
 
-```shell
-pip install -r pkg-requires.txt
-
-python setup.py sdist bdist_wheel
-twine upload dist/*
-```
+Publishing is automated with [Github Actions](.github/workflows/pypi.yml).
 
 ## TODO
 
 - Implement auditing for the remaining "special" QuerySet write operations:
   - `bulk_update()`
 - Write full library documentation using github.io.
-- Switch to `pytest` to support Python 3.10.
 
 ### Backlog
 
 - Add to optimization for `instance.save(save_fields=[...])` [maybe].
 - Support adding new audit fields on the same model at different times (instead
   of raising `AlreadyAudited`) [maybe].
+

django_field_audit-1.2.9/PKG-INFO → django_field_audit-1.4.0/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.2
-Name: django-field-audit
-Version: 1.2.9
-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]
@@ -102,6 +65,42 @@ FIELD_AUDIT_AUDITORS = []
 |:----------------------------------|:---------------------------------------------------------------|:------------------------
 | `FIELD_AUDIT_AUDITEVENT_MANAGER`  | A custom manager to use for the `AuditEvent` Model.            | `field_audit.models.DefaultAuditEventManager`
 | `FIELD_AUDIT_AUDITORS`            | A custom list of auditors for acquiring `change_context` info. | `["field_audit.auditors.RequestAuditor", "field_audit.auditors.SystemUserAuditor"]`
+| `FIELD_AUDIT_SERVICE_CLASS`       | A custom service class for audit logic implementation.         | `field_audit.services.AuditService`
+
+### Custom Audit Service
+
+The audit logic has been extracted into a separate `AuditService` class to improve separation of concerns and enable easier customization of audit behavior. Users can provide custom audit implementations by subclassing `AuditService` and configuring the `FIELD_AUDIT_SERVICE_CLASS` setting.
+
+#### Creating a Custom Audit Service
+
+```python
+# myapp/audit.py
+
+from field_audit import AuditService
+
+class CustomAuditService(AuditService):
+    def get_field_value(self, instance, field_name, bootstrap=False):
+        # Custom logic for extracting field values
+        value = super().get_field_value(instance, field_name, bootstrap)
+        
+        # Example: custom serialization or transformation
+        if field_name == 'sensitive_field':
+            value = '[REDACTED]'
+            
+        return value
+```
+
+Then configure it in your Django settings:
+
+```python
+# settings.py
+
+FIELD_AUDIT_SERVICE_CLASS = 'myapp.audit.CustomAuditService'
+```
+
+#### Backward Compatibility
+
+The original `AuditEvent` class methods are maintained for backward compatibility but are now deprecated in favor of the service-based approach. These methods will issue deprecation warnings and delegate to the configured audit service.
 
 ### Model Auditing
 
@@ -177,6 +176,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
@@ -242,12 +279,11 @@ All feature and bug contributions are expected to be covered by tests.
 
 ### Setup for developers
 
-Create/activate a python virtualenv and install the required dependencies.
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management. Install uv and then install the project dependencies:
 
 ```shell
 cd django-field-audit
-mkvirtualenv django-field-audit  # or however you choose to setup your environment
-pip install django pynose flake8 coverage
+uv sync
 ```
 
 ### Running tests
@@ -258,18 +294,18 @@ your local Python's `sqlite3` library ships with the `JSON1` extension enabled
 
 - Tests
   ```shell
-  nosetests
+  uv run pytest
   ```
 
 - Style check
   ```shell
-  flake8 --config=setup.cfg
+  ruff check
   ```
 
 - Coverage
   ```shell
-  coverage run -m nose
-  coverage report -m
+  uv run coverage run -m pytest
+  uv run coverage report -m
   ```
 
 ### Adding migrations
@@ -277,27 +313,21 @@ your local Python's `sqlite3` library ships with the `JSON1` extension enabled
 The example `manage.py` is available for making new migrations.
 
 ```shell
-python example/manage.py makemigrations field_audit
+uv run python example/manage.py makemigrations field_audit
 ```
 
-### Uploading to PyPI
+### Publishing a new version to PyPI
 
-First bump the package version in the `field_audit/__init__.py` file. Then create a changelog entry in the CHANGELOG.md
-file. After these changes are merged, you should tag the main branch with the new version. Then, package and upload the generated files to PyPI.
+Push a new tag to Github using the format vX.Y.Z where X.Y.Z matches the version
+in [`__init__.py`](field_audit/__init__.py). Also ensure that the changelog is up to date.
 
-```shell
-pip install -r pkg-requires.txt
-
-python setup.py sdist bdist_wheel
-twine upload dist/*
-```
+Publishing is automated with [Github Actions](.github/workflows/pypi.yml).
 
 ## TODO
 
 - Implement auditing for the remaining "special" QuerySet write operations:
   - `bulk_update()`
 - Write full library documentation using github.io.
-- Switch to `pytest` to support Python 3.10.
 
 ### Backlog
 

django_field_audit-1.4.0/field_audit/__init__.py

@@ -0,0 +1,4 @@
+from .field_audit import audit_fields  # noqa: F401
+from .services import AuditService, get_audit_service  # noqa: F401
+
+__version__ = "1.4.0"

{django_field_audit-1.2.9 → django_field_audit-1.4.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
 
@@ -56,18 +57,21 @@ def audit_fields(*field_names, class_path=None, audit_special_queryset_writes=Fa
             raise AlreadyAudited(cls)
         if not issubclass(cls, models.Model):
             raise ValueError(f"expected Model subclass, got: {cls}")
-        AuditEvent.attach_field_names(cls, field_names)
+        service.attach_field_names(cls, field_names)
         if audit_special_queryset_writes:
             _verify_auditing_manager(cls)
         cls.__init__ = _decorate_init(cls.__init__)
         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:
         raise ValueError("at least one field name is required")
-    from .models import AuditEvent
+    from .services import get_audit_service
+    service = get_audit_service()
     return wrapper
 
 
@@ -98,8 +102,9 @@ def _decorate_init(init):
     @wraps(init)
     def wrapper(self, *args, **kw):
         init(self, *args, **kw)
-        AuditEvent.attach_initial_values(self)
-    from .models import AuditEvent
+        service.attach_initial_values(self)
+    from .services import get_audit_service
+    service = get_audit_service()
     return wrapper
 
 
@@ -121,7 +126,7 @@ def _decorate_db_write(func):
         db = router.db_for_write(type(self))
         with transaction.atomic(using=db):
             ret = func(self, *args, **kw)
-            AuditEvent.audit_field_changes(
+            service.audit_field_changes(
                 self,
                 is_create,
                 is_delete,
@@ -133,7 +138,8 @@ def _decorate_db_write(func):
     is_delete = func.__name__ == "delete"
     if not is_save and not is_delete:
         raise ValueError(f"invalid function for decoration: {func}")
-    from .models import AuditEvent
+    from .services import get_audit_service
+    service = get_audit_service()
     return wrapper
 
 
@@ -147,13 +153,96 @@ def _decorate_refresh_from_db(func):
     @wraps(func)
     def wrapper(self, using=None, fields=None, **kwargs):
         if fields is not None:
-            fields = set(fields) | set(AuditEvent.field_names(self))
+            fields = set(fields) | set(service.get_field_names(self))
         func(self, using, fields, **kwargs)
 
-    from .models import AuditEvent
+    from .services import get_audit_service
+    service = get_audit_service()
     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 .services import get_audit_service
+
+    service = get_audit_service()
+
+    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 service.get_field_names(instance):
+        return
+
+    if action == 'pre_clear':
+        # `pk_set` not supplied for clear actions. Determine initial values
+        # in the `pre_clear` event
+        service.attach_initial_m2m_values(instance, field_name)
+        return
+
+    if action == 'post_clear':
+        initial_values = service.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 = service.create_audit_event(
+        instance.pk, instance.__class__, delta, False, False, req
+    )
+    if event is not None:
+        event.save()
+
+    service.clear_initial_m2m_field_values(instance, field_name)
+
+
 def get_audited_models():
     return _audited_models.copy()
 

{django_field_audit-1.2.9 → django_field_audit-1.4.0}/field_audit/management/commands/bootstrap_field_audit_events.py

@@ -4,7 +4,7 @@ from django.core.management.base import BaseCommand, CommandError
 
 from field_audit.const import BOOTSTRAP_BATCH_SIZE
 from field_audit.field_audit import get_audited_models
-from field_audit.models import AuditEvent
+from field_audit.services import get_audit_service
 
 
 class Command(BaseCommand):
@@ -64,6 +64,9 @@ class Command(BaseCommand):
         if batch_size == 0:
             batch_size = None
         self.batch_size = batch_size
+
+        self.service = get_audit_service()
+
         for name in models:
             model_class = self.models[name]
             self.operations[operation](self, model_class)
@@ -74,7 +77,7 @@ class Command(BaseCommand):
         with self.bootstrap_action_log(log_head) as stream:
             count = self.do_bootstrap(
                 model_class,
-                AuditEvent.bootstrap_existing_model_records,
+                self.service.bootstrap_existing_model_records,
                 iter_records=query.iterator,
             )
             stream.write(f"done ({count})")
@@ -82,11 +85,11 @@ class Command(BaseCommand):
     def top_up_missing(self, model_class):
         log_head = f"top-up: {model_class} ... "
         with self.bootstrap_action_log(log_head) as stream:
-            count = self.do_bootstrap(model_class, AuditEvent.bootstrap_top_up)
+            count = self.do_bootstrap(model_class, self.service.bootstrap_top_up)
             stream.write(f"done ({count})")
 
     def do_bootstrap(self, model_class, bootstrap_method, **bootstrap_kw):
-        field_names = AuditEvent.field_names(model_class)
+        field_names = self.service.get_field_names(model_class)
         if not field_names:
             raise CommandError(
                 f"invalid fields ({field_names!r}) for model: {model_class}"

django_field_audit-1.4.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),
+        ),
+    ]