iil-django-commons

Shared backend services library for Django projects on the iil.pet platform.

Implements ADR-131 — Shared Backend Services for all Django Hub projects.

Installation

# Minimal (logging + health only)
pip install -e packages/iil-django-commons

# With cache support (django-redis)
pip install -e "packages/iil-django-commons[cache]"

# Full
pip install -e "packages/iil-django-commons[all]"

# From GitHub (pinned)
pip install "git+https://github.com/achimdehnert/platform.git@v0.1.0#subdirectory=packages/iil-django-commons"

Setup

# settings.py
INSTALLED_APPS = [
    "iil_commons",
    ...
]

MIDDLEWARE = [
    "iil_commons.logging.middleware.CorrelationIDMiddleware",
    "iil_commons.logging.middleware.RequestLogMiddleware",
    ...
]

IIL_COMMONS = {
    "LOG_FORMAT": "json",        # "json" | "human"
    "LOG_LEVEL": "INFO",
    "CACHE_DEFAULT_TTL": 300,
    "HEALTH_CHECKS": ["db", "redis"],
}

# urls.py
from django.urls import include, path

urlpatterns = [
    path("", include("iil_commons.health.urls")),
    ...
]

Modules (Phase 1)

Logging

# Auto-configured via AppConfig.ready() — no manual call needed.
# Override format per project:
IIL_COMMONS = {"LOG_FORMAT": "json"}  # structured JSON for production

Middlewares add X-Correlation-ID header to every request/response and log method, path, status, duration_ms, user_id per request.

Health Checks

IIL_COMMONS = {"HEALTH_CHECKS": ["db", "redis"]}

Cache

from iil_commons.cache import cached_view, cached_method, invalidate_pattern

@cached_view(ttl=300, key_func=lambda r: f"guests:{r.org.pk}")
def guest_list(request): ...

class GuestService:
    @cached_method(ttl=60, key_prefix="guest_service")
    def get_active(self, org_id): ...

# Invalidate on model save
invalidate_pattern(f"iil:view:guests:{org.pk}:*")

invalidate_pattern requires django-redis backend (iter_keys support).

Running Tests

cd packages/iil-django-commons
pip install -e ".[dev]"
pytest

Roadmap