Merge pull request #42 from dimagi/sk/audit-service

extract main audit logic into a service class

Author: snopoke

README.md

@@ -65,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
 

field_audit/__init__.py

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

field_audit/field_audit.py

@@ -57,7 +57,7 @@ def wrapper(cls):
             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__)
@@ -70,7 +70,8 @@ def wrapper(cls):
         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
 
 
@@ -101,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
 
 
@@ -124,7 +126,7 @@ def wrapper(self, *args, **kw):
         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,
@@ -136,7 +138,8 @@ def wrapper(self, *args, **kw):
     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
 
 
@@ -150,10 +153,11 @@ 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
 
 
@@ -185,7 +189,9 @@ def _m2m_changed_handler(sender, instance, action, pk_set, **kwargs):
     :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
+    from .services import get_audit_service
+
+    service = get_audit_service()
 
     if action not in ('post_add', 'post_remove', 'post_clear', 'pre_clear'):
         return
@@ -206,17 +212,17 @@ def _m2m_changed_handler(sender, instance, action, pk_set, **kwargs):
             field_name = field.name
             break
 
-    if not m2m_field or field_name not in AuditEvent.field_names(instance):
+    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
-        AuditEvent.attach_initial_m2m_values(instance, field_name)
+        service.attach_initial_m2m_values(instance, field_name)
         return
 
     if action == 'post_clear':
-        initial_values = AuditEvent.get_initial_m2m_values(instance, field_name)
+        initial_values = service.get_initial_m2m_values(instance, field_name)
         if not initial_values:
             return
         delta = {field_name: {'remove': initial_values}}
@@ -228,13 +234,13 @@ def _m2m_changed_handler(sender, instance, action, pk_set, **kwargs):
         delta = {field_name: {delta_key: list(pk_set)}}
 
     req = request.get()
-    event = AuditEvent.create_audit_event(
+    event = service.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)
+    service.clear_initial_m2m_field_values(instance, field_name)
 
 
 def get_audited_models():

field_audit/management/commands/bootstrap_field_audit_events.py

@@ -4,7 +4,7 @@
 
 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 @@ def handle(self, operation, models, batch_size, **options):
         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,19 +77,19 @@ def init_all(self, model_class):
         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})")
 
     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}"