django-auditkit 0.1.0

Reusable Django audit models, soft-delete support, and admin helpers

django-auditkit

Reusable Django audit models with automatic timestamp tracking, user attribution, and optional soft-delete support. Includes admin mixins for seamless integration with Django Admin.

Features

• 🔍 Full Audit Trail: Track created_at, updated_at, created_by, updated_by automatically
• 🗑️ Soft Delete: Optional soft-delete with deleted_at and deleted_by tracking
• 👤 User Attribution: Automatic tracking of who created/modified/deleted records
• 🛡️ Safe Queries: Soft-deleted records excluded by default, with option to include them
• 🔧 Admin Integration: Ready-to-use admin mixins with audit fields display
• ⚡ QuerySet Optimizations: Built-in methods for common audit operations

Quick Start

Installation

pip install django-auditkit

Basic Usage

# models.py
from django.db import models
from auditkit.models import AuditModel

class MyModel(AuditModel):
    name = models.CharField(max_length=100)
    description = models.TextField()
    
    class Meta:
        ordering = ['-created_at']

# admin.py
from django.contrib import admin
from auditkit.admin import AuditAdminMixin
from .models import MyModel

@admin.register(MyModel)
class MyModelAdmin(AuditAdminMixin, admin.ModelAdmin):
    list_display = ('name', 'created_at', 'created_by', 'updated_at')
    list_filter = ('created_at', 'updated_at')
    search_fields = ('name', 'description')

Models

TimestampModel

Base model with automatic timestamp tracking.

from auditkit.models import TimestampModel

class Product(TimestampModel):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    # Automatically gets:
    # - created_at: DateTimeField (auto_now_add)
    # - updated_at: DateTimeField (auto_now)

AuditModel

Full audit model with user attribution.

from auditkit.models import AuditModel

class Order(AuditModel):
    customer_name = models.CharField(max_length=100)
    total = models.DecimalField(max_digits=10, decimal_places=2)
    # Automatically gets:
    # - created_at, updated_at (from TimestampModel)
    # - created_by: ForeignKey to User
    # - updated_by: ForeignKey to User
    # - deleted_at: DateTimeField (null=True)
    # - deleted_by: ForeignKey to User (null=True)

Features:

• Automatic population of created_by and updated_by on save
• Soft delete support via delete() method
• QuerySet excludes soft-deleted records by default

Soft Delete Operations

# Soft delete (sets deleted_at and deleted_by)
order = Order.objects.get(id=1)
order.delete()  # Soft delete - record still in DB

# Hard delete (permanent removal)
order.delete(hard=True)

# Restore soft-deleted record
order.restore()

# Query including soft-deleted records
all_orders = Order.objects.all_with_deleted()

# Query only soft-deleted records
deleted_orders = Order.objects.deleted()

# Check if record is soft-deleted
if order.is_deleted:
    print("This order was deleted")

Admin Mixins

AuditAdminMixin

Displays audit fields in Django Admin with proper formatting.

from django.contrib import admin
from auditkit.admin import AuditAdminMixin
from .models import Product

@admin.register(Product)
class ProductAdmin(AuditAdminMixin, admin.ModelAdmin):
    list_display = ('name', 'price', 'created_at', 'created_by')
    readonly_fields = ('created_at', 'updated_at', 'created_by', 'updated_by')

Features:

• Automatically adds audit fields to readonly_fields
• Displays timestamps in local timezone
• Shows user links for created_by and updated_by

SoftDeleteAdminMixin

Adds soft-delete functionality to Django Admin.

from django.contrib import admin
from auditkit.admin import SoftDeleteAdminMixin
from .models import Order

@admin.register(Order)
class OrderAdmin(SoftDeleteAdminMixin, admin.ModelAdmin):
    list_display = ('customer_name', 'total', 'is_deleted', 'deleted_at')
    actions = ['soft_delete_selected', 'restore_selected']

Features:

• Soft delete action for bulk operations
• Restore action for recovering deleted records
• Filter by deletion status

QuerySets and Managers

SoftDeleteQuerySet

Enhanced QuerySet with soft-delete awareness.

# Default: excludes soft-deleted records
active_orders = Order.objects.all()

# Include deleted
all_orders = Order.objects.all_with_deleted()

# Only deleted
deleted_orders = Order.objects.deleted()

# Restore multiple records
Order.objects.filter(id__in=[1, 2, 3]).restore()

# Hard delete multiple records
Order.objects.filter(id__in=[1, 2, 3]).delete(hard=True)

Configuration

Add auditkit to your INSTALLED_APPS:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ... other apps
    'auditkit',
    'myapp',
]

Requirements

• Python 3.12+
• Django 6.0+

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Important: All contributions must be made via Pull Request. Direct pushes to main or develop branches are not allowed.

Changelog

0.1.0 (2026-04-20)

• Initial release
• TimestampModel and AuditModel
• Soft-delete support
• Admin mixins
• QuerySet optimizations