Metadata-Version: 2.4
Name: django-actlog
Version: 1.0.0
Summary: Minimal explicit event logging for Django MVPs.
Author-email: Hossein Dahaei <dahaeehossein@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/HosseinDahaei/django-actlog
Project-URL: Repository, https://github.com/HosseinDahaei/django-actlog
Project-URL: Documentation, https://github.com/HosseinDahaei/django-actlog#readme
Keywords: django,audit,activity-log,event-logging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: django-json-widget>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# django-actlog

Minimal, opt-in application event logging for Django MVPs.

Unlike [django-auditlog](https://github.com/jazzband/django-auditlog) (automatic model change history) or [django-easy-audit](https://github.com/soynatan/django-easy-audit) (automatic CRUD/auth hooks), **django-actlog** records events only when you explicitly call `log_event()` with a host-defined action string.

## Install

```bash
pip install django-actlog
```

Add to `INSTALLED_APPS` and migrate:

```python
INSTALLED_APPS = [
    # ...
    "actlog",
]
```

```bash
python manage.py migrate actlog
```

## Quick start

Define action constants in your project (not in the library):

```python
# myapp/audit_constants.py
LOGIN_SUCCESS = "LOGIN_SUCCESS"
OTP_SENT = "OTP_SENT"
```

Log events from your services:

```python
from actlog import log_event, Level
from myapp.audit_constants import LOGIN_SUCCESS, LOGIN_FAILED

def on_login_success(user, request, session):
    event = log_event(
        LOGIN_SUCCESS,
        user=user,
        metadata={
            "method": "otp",
            "session_id": session.id,
            "ip": request.META.get("REMOTE_ADDR"),
            "user_agent": request.META.get("HTTP_USER_AGENT", ""),
        },
    )

def on_login_failed(request, username):
    log_event(
        LOGIN_FAILED,
        level=Level.WARNING,
        metadata={"username": username, "ip": request.META.get("REMOTE_ADDR")},
    )
```

`log_event()` persists synchronously and returns the created `ActLog` instance. Pass any request or domain context via `metadata`.

Severity is set with `level` (optional; default `INFO`). Values mirror Python logging: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (`Level`).

## Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `ACTLOG_MODEL` | `"actlog.ActLog"` | Dotted path to the log model (advanced) |
| `ACTLOG_USER_RELATED_NAME` | `"act_logs"` | `related_name` on the user FK |
| `ACTLOG_ACTION_MAX_LENGTH` | `64` | Max length for action strings |
| `ACTLOG_USER_SEARCH_FIELDS` | `("user__email",)` | Admin search lookups for the user FK |

## Django admin

Register is automatic. The admin is read-only (no add/delete). The metadata field uses a read-only JSON editor (`django-json-widget` is installed and registered automatically).

Custom user models: override `ACTLOG_USER_SEARCH_FIELDS` if `user__email` does not apply.

## Public API

```python
from actlog import log_event, ActLog, Level
from actlog.models import ActLog
from actlog.choices import Level
from actlog.services import log_event
```

## License

MIT
