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

{django_field_audit-1.3.0 → 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.3.0
+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
 
@@ -280,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
@@ -296,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
@@ -315,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.3.0 → django_field_audit-1.4.0}/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
 
@@ -243,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
@@ -259,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
@@ -278,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
-
-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.
+### Publishing a new version to PyPI
 
-```shell
-pip install -r pkg-requires.txt
+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.
 
-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.3.0 → django_field_audit-1.4.0}/field_audit/field_audit.py

@@ -57,7 +57,7 @@ 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__)
@@ -70,7 +70,8 @@ def audit_fields(*field_names, class_path=None, audit_special_queryset_writes=Fa
         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 _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,
@@ -136,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
 
 
@@ -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():

{django_field_audit-1.3.0 → 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}"