Metadata-Version: 2.4
Name: django-auditkit
Version: 0.1.0
Summary: Reusable Django audit models, soft-delete support, and admin helpers
Author-email: Pablo Digonzelli <pdigonzelli@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pdigonzelli/django-auditkit
Project-URL: Documentation, https://github.com/pdigonzelli/django-auditkit#readme
Project-URL: Repository, https://github.com/pdigonzelli/django-auditkit
Project-URL: Issues, https://github.com/pdigonzelli/django-auditkit/issues
Keywords: django,audit,auditkit,soft-delete,admin
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=6.0.3
Dynamic: license-file

# django-auditkit

[![CI](https://github.com/pdigonzelli/django-auditkit/actions/workflows/ci.yml/badge.svg)](https://github.com/pdigonzelli/django-auditkit/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/django-auditkit.svg)](https://badge.fury.io/py/django-auditkit)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Django 6.0+](https://img.shields.io/badge/django-6.0+-green.svg)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

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

```bash
pip install django-auditkit
```

### Basic Usage

```python
# 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']
```

```python
# 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.

```python
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.

```python
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

```python
# 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.

```python
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.

```python
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.

```python
# 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`:

```python
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](LICENSE) file for details.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](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
