Audit Field Changes on Django Models

A Django app for auditing field changes on database models.

Installation

pip install django-field-audit

Documentation

Django Settings

To enable the app, add it to your Django INSTALLED_APPS configuration and run migrations. Settings example:

INSTALLED_APPS = [
    # ...
    "field_audit",
]

The "auditor chain" (see FIELD_AUDIT_AUDITORS in the Custom settings table below) is configured out of the box with the default auditors. If change_context auditing is desired for authenticated Django requests, add the app middleware to your Django MIDDLEWARE configuration. For example:

MIDDLEWARE = [
    # ...
    "field_audit.middleware.FieldAuditMiddleware",
]

The audit chain can be updated to use custom auditors (subclasses of field_audit.auditors.BaseAuditor). If change_context auditing is not desired, the audit chain can be cleared to avoid extra processing:

FIELD_AUDIT_AUDITORS = []

Custom settings details

Model Auditing

To begin auditing Django models, import the field_audit.audit_fields decorator and decorate models specifying which fields should be audited for changes. Example code:

# flight/models.py

from django.db import models
from field_audit import audit_fields


@audit_fields("tail_number", "make_model", "operated_by")
class Aircraft(models.Model):
    id = AutoField(primary_key=True)
    tail_number = models.CharField(max_length=32, unique=True)
    make_model = models.CharField(max_length=64)
    operated_by = models.CharField(max_length=64)

Using with SQLite

This app uses Django's JSONField which means if you intend to use the app with a SQLite database, the SQLite JSON1 extension is required. If your system's Python sqlite3 library doesn't ship with this extension enabled, see this article for details on how to enable it.

Contributing

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.

cd django-field-audit
mkvirtualenv django-field-audit  # or however you choose to setup your environment
pip install django nose flake8 coverage

Running tests

Note: By default, local tests use an in-memory SQLite database. Ensure that your local Python's sqlite3 library ships with the JSON1 extension enabled (see Using with SQLite).

• Tests

  nosetests
  

• Style check

  flake8 --config=setup.cfg
  

• Coverage

  coverage run -m nose
  coverage report -m
  

Adding migrations

The example manage.py is available for making new migrations.

python example/manage.py makemigrations field_audit

Uploading to PyPI

Package and upload the generated files.

pip install -r pkg-requires.txt

python setup.py sdist bdist_wheel
twine upload dist/*

TODO

• Write backfill migration utility / management command.
• Add support for QuerySet write operations (update(), etc).
• Write full library documentation using github.io.
• Switch to pytest to support Python 3.10.
• Write test_library.py functional test module for entire library.

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].