django-api-usage 0.1.0__py3-none-any.whl

django_api_usage/__init__.py

@@ -0,0 +1,3 @@
+"""django-api-usage: usage metering for Django APIs, with deprecation support."""
+
+__version__ = "0.1.0"

django_api_usage/admin.py

@@ -0,0 +1,56 @@
+"""Read-only admin for usage counters, plus editable deprecation metadata."""
+
+from django.contrib import admin
+
+from .models import Consumer, Endpoint, EndpointStat
+
+
+@admin.register(Endpoint)
+class EndpointAdmin(admin.ModelAdmin):
+    list_display = (
+        "app_label",
+        "route_name",
+        "method",
+        "site_id",
+        "deprecated",
+        "sunset_date",
+        "replacement",
+        "owner",
+    )
+    list_filter = ("deprecated", "app_label", "method", "site_id")
+    search_fields = ("route_name", "replacement", "owner", "notes")
+    list_editable = ("deprecated", "sunset_date", "replacement", "owner")
+
+
+@admin.register(EndpointStat)
+class EndpointStatAdmin(admin.ModelAdmin):
+    list_display = ("date", "endpoint", "client_type", "status_class", "count")
+    list_filter = ("date", "client_type", "status_class")
+    list_select_related = ("endpoint",)
+    date_hierarchy = "date"
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Consumer)
+class ConsumerAdmin(admin.ModelAdmin):
+    list_display = (
+        "kind",
+        "ref_short",
+        "user_agent_family",
+        "request_count",
+        "first_seen",
+        "last_seen",
+        "contact",
+    )
+    list_filter = ("kind",)
+    search_fields = ("contact", "notes")
+    list_editable = ("contact",)
+
+    @admin.display(description="Reference")
+    def ref_short(self, obj):
+        return obj.ref_hash[:12]

django_api_usage/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+
+class DjangoApiUsageConfig(AppConfig):
+    name = "django_api_usage"
+    verbose_name = "Django API usage"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Register system checks (middleware installed, consumer salt, ...).
+        from . import checks  # noqa: F401

django_api_usage/buffers.py

@@ -0,0 +1,140 @@
+"""Recording backends.
+
+The default backend accumulates counters in a single cache key and flushes them
+to the database in batches (``api_usage_flush``), so a request never pays a
+database write. With ``FAIL_OPEN`` metering can never break a request.
+
+Note: the cache backend trades perfect accuracy under high concurrency for
+throughput. If you need per-request exactness, set ``BUFFER_BACKEND = "db"``.
+"""
+
+import json
+import logging
+
+from django.core.cache import caches
+from django.db import transaction
+from django.db.models import F
+from django.utils import timezone
+
+from .conf import api_settings
+from .models import Consumer, Endpoint, EndpointStat
+
+logger = logging.getLogger("django_api_usage")
+
+# Order matters: it is how a buffered bucket is encoded into a cache key.
+_FIELDS = ("site_id", "app_label", "route_name", "method", "client_type")
+
+
+def _cache():
+    return caches[api_settings.CACHE_ALIAS]
+
+
+def _buffer_key():
+    return f"{api_settings.CACHE_PREFIX}:buffer"
+
+
+def status_class(status_code):
+    """``204`` -> ``2xx``."""
+    return f"{int(status_code) // 100}xx"
+
+
+def record_hit(dimensions, status_code, consumer=None):
+    """Record a single hit.
+
+    ``dimensions`` is a mapping with the keys in :data:`_FIELDS`.
+    """
+    if api_settings.BUFFER_BACKEND == "db":
+        _write_to_db(dimensions, status_class(status_code), 1)
+    else:
+        _buffer(dimensions, status_class(status_code))
+    if consumer and api_settings.TRACK_CONSUMERS:
+        _touch_consumer(consumer)
+
+
+def _buffer(dimensions, status_code_class):
+    cache = _cache()
+    key = _buffer_key()
+    raw = cache.get(key)
+    counters = json.loads(raw) if raw else {}
+    bucket = "{}|{}".format(
+        "|".join(str(dimensions.get(field, "")) for field in _FIELDS),
+        status_code_class,
+    )
+    counters[bucket] = counters.get(bucket, 0) + 1
+    cache.set(key, json.dumps(counters), None)
+
+
+def flush():
+    """Move buffered counters from the cache into the database.
+
+    Returns the number of counter buckets written.
+    """
+    cache = _cache()
+    key = _buffer_key()
+    raw = cache.get(key)
+    if not raw:
+        return 0
+    cache.delete(key)
+    counters = json.loads(raw) if isinstance(raw, str) else raw
+    written = 0
+    for bucket, count in counters.items():
+        dimension_key, _, status_code_class = bucket.rpartition("|")
+        values = dimension_key.split("|")
+        if len(values) != len(_FIELDS):
+            logger.warning("django-api-usage: skipping malformed bucket %r", bucket)
+            continue
+        dimensions = dict(zip(_FIELDS, values))
+        dimensions["site_id"] = _as_int(dimensions.get("site_id"))
+        _write_to_db(dimensions, status_code_class, count)
+        written += 1
+    return written
+
+
+def _as_int(value):
+    if value in (None, "", "None"):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _write_to_db(dimensions, status_code_class, count):
+    with transaction.atomic():
+        endpoint, _ = Endpoint.objects.get_or_create(
+            site_id=dimensions.get("site_id"),
+            app_label=dimensions.get("app_label") or "unknown",
+            route_name=dimensions.get("route_name") or "unknown",
+            method=dimensions.get("method") or "GET",
+        )
+        stat, created = EndpointStat.objects.get_or_create(
+            endpoint=endpoint,
+            date=timezone.localdate(),
+            client_type=dimensions.get("client_type") or "anon",
+            status_class=status_code_class,
+            defaults={"count": count},
+        )
+        if not created:
+            EndpointStat.objects.filter(pk=stat.pk).update(count=F("count") + count)
+
+
+def _touch_consumer(consumer):
+    kind, ref_hash, user_agent_family = consumer
+    now = timezone.now()
+    obj, created = Consumer.objects.get_or_create(
+        kind=kind,
+        ref_hash=ref_hash,
+        defaults={
+            "user_agent_family": user_agent_family,
+            "first_seen": now,
+            "last_seen": now,
+            "request_count": 1,
+        },
+    )
+    if created:
+        return
+    Consumer.objects.filter(pk=obj.pk).update(
+        last_seen=now,
+        request_count=F("request_count") + 1,
+        user_agent_family=user_agent_family,
+    )

django_api_usage/checks.py

@@ -0,0 +1,80 @@
+"""Django system checks: catch misconfiguration early."""
+
+from django.conf import settings
+from django.core.checks import Warning, register
+from django.utils.module_loading import import_string
+
+from .conf import api_settings
+
+W001 = Warning(
+    "django-api-usage is enabled but no subclass of "
+    "'django_api_usage.middleware.ApiUsageMiddleware' is in MIDDLEWARE; no usage "
+    "will be recorded.",
+    id="api_usage.W001",
+)
+W002 = Warning(
+    "API_USAGE['TRACK_CONSUMERS'] is enabled but API_USAGE['CONSUMER_SALT'] is empty; "
+    "SECRET_KEY will be used as the salt. Set an explicit, rotatable salt.",
+    id="api_usage.W002",
+)
+W003 = Warning(
+    "API_USAGE['BUFFER_BACKEND'] is 'cache' but the configured cache backend is "
+    "DummyCache, which stores nothing: no usage will be recorded. Configure a real "
+    "cache or set BUFFER_BACKEND='db'.",
+    id="api_usage.W003",
+)
+
+DUMMY_CACHE_BACKEND = "django.core.cache.backends.dummy.DummyCache"
+
+
+def _middleware_installed():
+    """True when some MIDDLEWARE entry is ApiUsageMiddleware or a subclass.
+
+    Subclasses are accepted on purpose: projects are encouraged to subclass the
+    middleware to narrow what gets metered (for example, only ``/api/``).
+    """
+    from .middleware import ApiUsageMiddleware
+
+    for entry in getattr(settings, "MIDDLEWARE", []) or []:
+        if not isinstance(entry, str):
+            continue
+        try:
+            obj = import_string(entry)
+        except Exception:  # pragma: no cover - unresolvable entry
+            continue
+        if isinstance(obj, type) and issubclass(obj, ApiUsageMiddleware):
+            return True
+    return False
+
+
+def _cache_backend_path():
+    """Dotted path of the configured cache backend, or '' if unavailable."""
+    from django.core.cache import caches
+
+    try:
+        backend = caches[api_settings.CACHE_ALIAS]
+    except Exception:  # pragma: no cover - misconfigured CACHES
+        return ""
+    backend_class = type(backend)
+    return f"{backend_class.__module__}.{backend_class.__name__}"
+
+
+@register()
+def api_usage_checks(app_configs, **kwargs):
+    errors = []
+    if not api_settings.ENABLED:
+        return errors
+
+    if not _middleware_installed():
+        errors.append(W001)
+
+    if api_settings.TRACK_CONSUMERS and not api_settings.CONSUMER_SALT:
+        errors.append(W002)
+
+    if (
+        api_settings.BUFFER_BACKEND == "cache"
+        and _cache_backend_path() == DUMMY_CACHE_BACKEND
+    ):
+        errors.append(W003)
+
+    return errors

django_api_usage/conf.py

@@ -0,0 +1,81 @@
+"""Configuration for django-api-usage.
+
+Every option is read from the ``API_USAGE`` dictionary in Django settings::
+
+    API_USAGE = {
+        "ENABLED": True,
+        "TRACK_CONSUMERS": False,
+    }
+
+Resolver options accept either a dotted path to a callable or the callable
+itself. Nothing in this module depends on the host project.
+"""
+
+from django.utils.module_loading import import_string
+
+DEFAULTS = {
+    # Master switch: when False the middleware becomes a no-op.
+    "ENABLED": True,
+    # Metering must never break a request.
+    "FAIL_OPEN": True,
+    # "cache" buffers counters in the cache and writes them in batches;
+    # "db" writes one aggregate update per request (simpler, slower).
+    "BUFFER_BACKEND": "cache",
+    "CACHE_ALIAS": "default",
+    "CACHE_PREFIX": "api_usage",
+    # Raw per-day aggregates older than this are pruned. 0 keeps them forever.
+    "RETENTION_DAYS": 90,
+    # Opt-in consumer attribution. Only salted hashes are stored; see the docs.
+    "TRACK_CONSUMERS": False,
+    # Salt used to hash consumer identifiers. Keep it secret and rotatable.
+    "CONSUMER_SALT": "",
+    # Resolvers (dotted path or callable).
+    "APP_LABEL_RESOLVER": "django_api_usage.resolvers.default_app_label",
+    "ROUTE_NAME_RESOLVER": "django_api_usage.resolvers.default_route_name",
+    "CLIENT_TYPE_RESOLVER": "django_api_usage.resolvers.default_client_type",
+    "SITE_RESOLVER": "django_api_usage.resolvers.default_site_id",
+    "CONSUMER_RESOLVER": "django_api_usage.resolvers.default_consumer",
+    "ROLE_SCOPES_RESOLVER": "django_api_usage.drf.default_role_scopes",
+    # Regexes matched against request.path; matching requests are not recorded.
+    "IGNORE_PATHS": (
+        r"^/static/",
+        r"^/media/",
+        r"^/favicon\.ico$",
+    ),
+}
+
+
+class ApiUsageSettings:
+    """Lazy accessor over ``settings.API_USAGE`` with sane defaults."""
+
+    def __init__(self, user_settings=None):
+        self._user = user_settings
+        self._resolved = {}
+
+    @property
+    def user_settings(self):
+        if self._user is None:
+            from django.conf import settings as django_settings
+
+            self._user = getattr(django_settings, "API_USAGE", {}) or {}
+        return self._user
+
+    def __getattr__(self, attr):
+        if attr not in DEFAULTS:
+            raise AttributeError(f"Invalid API_USAGE setting: {attr!r}")
+        if attr in self._resolved:
+            return self._resolved[attr]
+        value = self.user_settings.get(attr, DEFAULTS[attr])
+        if attr.endswith("_RESOLVER"):
+            if isinstance(value, str):
+                value = import_string(value)
+            self._resolved[attr] = value
+        return value
+
+    def reload(self):
+        """Forget cached settings and resolved callables (used in tests)."""
+        self._user = None
+        self._resolved = {}
+
+
+api_settings = ApiUsageSettings()

django_api_usage/deprecation.py

@@ -0,0 +1,34 @@
+"""Deprecation lifecycle helpers built on top of the usage counters."""
+
+from datetime import timedelta
+
+from django.db.models import Sum
+from django.utils import timezone
+
+from .models import Endpoint, EndpointStat
+
+
+def usage(period_days=90, site_id=None):
+    """Return ``[(endpoint, calls), ...]`` for every known endpoint."""
+    since = timezone.localdate() - timedelta(days=period_days)
+    endpoints = Endpoint.objects.all()
+    if site_id is not None:
+        endpoints = endpoints.filter(site_id=site_id)
+    totals = (
+        EndpointStat.objects.filter(date__gte=since)
+        .values("endpoint_id")
+        .annotate(total=Sum("count"))
+    )
+    by_id = {row["endpoint_id"]: row["total"] for row in totals}
+    return [(endpoint, by_id.get(endpoint.pk, 0)) for endpoint in endpoints]
+
+
+def in_use(period_days=90, site_id=None):
+    """Endpoints with traffic in the period, most used first."""
+    rows = [(ep, total) for ep, total in usage(period_days, site_id) if total > 0]
+    return sorted(rows, key=lambda row: row[1], reverse=True)
+
+
+def candidates_for_deprecation(period_days=90, site_id=None):
+    """Endpoints with no traffic in the period: the safe ones to deprecate."""
+    return [ep for ep, total in usage(period_days, site_id) if total == 0]

django_api_usage/drf.py

@@ -0,0 +1,71 @@
+"""Optional DRF integration: scope-based permissions with a shadow mode.
+
+Importing this module requires ``djangorestframework`` to be installed.
+
+The point of the shadow mode is to let a new permission be **deployed and
+measured before it is enforced**: with ``API_ENFORCEMENT = "report"`` nothing is
+blocked, and the middleware adds an ``X-Api-Would-Deny`` header so you can see
+what the permission would have rejected.
+"""
+
+from django.conf import settings
+from rest_framework.permissions import BasePermission
+
+from .conf import api_settings
+
+REPORT = "report"
+WARN = "warn"
+ENFORCE = "enforce"
+
+
+def enforcement_mode(view=None):
+    """Resolve the enforcement mode, honouring per-view/per-endpoint overrides."""
+    overrides = getattr(settings, "API_ENFORCEMENT_OVERRIDES", {}) or {}
+    if view is not None:
+        key = getattr(view, "enforcement_key", None) or getattr(view, "basename", None)
+        if key and key in overrides:
+            return overrides[key]
+    return getattr(settings, "API_ENFORCEMENT", REPORT)
+
+
+def default_role_scopes(user):
+    """Scopes granted to a user.
+
+    Uses ``user.get_api_scopes()`` when the project exposes it, otherwise maps
+    Django groups named ``api:<scope>`` (e.g. ``api:content:write``).
+    """
+    getter = getattr(user, "get_api_scopes", None)
+    if callable(getter):
+        return set(getter())
+    return {
+        group.name[4:] for group in user.groups.all() if group.name.startswith("api:")
+    }
+
+
+def granted_scopes(request):
+    """Scopes granted to the caller: client key scopes, or role-derived scopes."""
+    scopes = set()
+    api_key = getattr(request, "api_key", None)
+    if api_key is not None:
+        scopes.update(api_key.scopes.values_list("code", flat=True))
+        return scopes
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        scopes.update(api_settings.ROLE_SCOPES_RESOLVER(user))
+    return scopes
+
+
+class HasAPIScope(BasePermission):
+    """Require the scopes declared in ``view.required_scopes``.
+
+    Views that declare no scopes are denied (fail closed) once enforcing.
+    """
+
+    def has_permission(self, request, view):
+        required = set(getattr(view, "required_scopes", ()) or ())
+        if required and required <= granted_scopes(request):
+            return True
+        if enforcement_mode(view) in (REPORT, WARN):
+            request._api_usage_would_deny = sorted(required)
+            return True
+        return False

django_api_usage/maintenance.py

@@ -0,0 +1,21 @@
+"""Maintenance helpers (retention/pruning)."""
+
+from datetime import timedelta
+
+from django.utils import timezone
+
+from .conf import api_settings
+from .models import EndpointStat
+
+
+def prune(retention_days=None):
+    """Delete raw counters older than the retention window.
+
+    Returns the number of deleted rows. ``RETENTION_DAYS = 0`` disables pruning.
+    """
+    days = api_settings.RETENTION_DAYS if retention_days is None else retention_days
+    if not days:
+        return 0
+    cutoff = timezone.localdate() - timedelta(days=days)
+    deleted, _ = EndpointStat.objects.filter(date__lt=cutoff).delete()
+    return deleted

django_api_usage/management/commands/api_usage_flush.py

@@ -0,0 +1,27 @@
+"""Flush buffered counters and apply the retention window.
+
+Run from cron or a Celery beat schedule:
+
+    python manage.py api_usage_flush
+"""
+
+from django.core.management.base import BaseCommand
+
+from django_api_usage.buffers import flush
+from django_api_usage.maintenance import prune
+
+
+class Command(BaseCommand):
+    help = "Move buffered counters to the database and prune old rows."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--no-prune", action="store_true", help="Skip the retention/pruning step."
+        )
+
+    def handle(self, *args, **options):
+        written = flush()
+        self.stdout.write(f"Flushed {written} counter bucket(s).")
+        if not options["no_prune"]:
+            deleted = prune()
+            self.stdout.write(f"Pruned {deleted} old stat row(s).")

django_api_usage/management/commands/api_usage_report.py

@@ -0,0 +1,60 @@
+"""Report API usage per endpoint and per application.
+
+This is the command that feeds a deprecation decision:
+
+    python manage.py api_usage_report --days 90
+    python manage.py api_usage_report --days 90 --sunset-candidates
+    python manage.py api_usage_report --app gida
+"""
+
+from django.core.management.base import BaseCommand
+
+from django_api_usage.deprecation import candidates_for_deprecation, in_use
+
+
+class Command(BaseCommand):
+    help = "Report API usage per endpoint and app, to support deprecation decisions."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--days",
+            type=int,
+            default=90,
+            help="Look-back window in days (default: 90).",
+        )
+        parser.add_argument(
+            "--app", dest="app_label", default=None, help="Filter by app."
+        )
+        parser.add_argument("--site", type=int, default=None, help="Filter by site id.")
+        parser.add_argument(
+            "--sunset-candidates",
+            action="store_true",
+            help="List endpoints with no traffic in the window instead of usage.",
+        )
+
+    def handle(self, *args, **options):
+        days = options["days"]
+        site_id = options["site"]
+        app_label = options["app_label"]
+
+        if options["sunset_candidates"]:
+            endpoints = candidates_for_deprecation(days, site_id)
+            if app_label:
+                endpoints = [ep for ep in endpoints if ep.app_label == app_label]
+            self.stdout.write(f"Endpoints without traffic in the last {days} day(s):")
+            for endpoint in endpoints:
+                self.stdout.write(
+                    f"  {endpoint.method} {endpoint.route_name} ({endpoint.app_label})"
+                )
+            self.stdout.write(f"Total: {len(endpoints)}")
+            return
+
+        rows = in_use(days, site_id)
+        if app_label:
+            rows = [(ep, total) for ep, total in rows if ep.app_label == app_label]
+        self.stdout.write("{:<12} {:<40} {:>10}".format("APP", "ENDPOINT", "CALLS"))
+        for endpoint, total in rows:
+            self.stdout.write(
+                f"{endpoint.app_label:<12} {endpoint.route_name:<40} {total:>10}"
+            )
+        self.stdout.write(f"Endpoints with traffic: {len(rows)}")

django_api_usage/middleware.py

@@ -0,0 +1,60 @@
+"""Fail-open middleware that meters every Django view, DRF or not."""
+
+import logging
+import re
+
+from .buffers import record_hit
+from .conf import api_settings
+
+logger = logging.getLogger("django_api_usage")
+
+
+class ApiUsageMiddleware:
+    """Record one aggregated hit per request and expose the shadow-mode header.
+
+    Placed anywhere in ``MIDDLEWARE``; it only needs the final response.
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if api_settings.ENABLED:
+            self._record(request, response)
+            self._add_shadow_header(request, response)
+        return response
+
+    def _record(self, request, response):
+        try:
+            if self._is_ignored(request):
+                return
+            dimensions = {
+                "site_id": api_settings.SITE_RESOLVER(request),
+                "app_label": api_settings.APP_LABEL_RESOLVER(request),
+                "route_name": api_settings.ROUTE_NAME_RESOLVER(request),
+                "method": request.method,
+                "client_type": api_settings.CLIENT_TYPE_RESOLVER(request),
+            }
+            consumer = None
+            if api_settings.TRACK_CONSUMERS:
+                consumer = api_settings.CONSUMER_RESOLVER(request)
+            record_hit(dimensions, response.status_code, consumer)
+        except Exception:
+            logger.exception("django-api-usage: could not record request")
+            if not api_settings.FAIL_OPEN:
+                raise
+
+    @staticmethod
+    def _add_shadow_header(request, response):
+        would_deny = getattr(request, "_api_usage_would_deny", None)
+        if would_deny:
+            response["X-Api-Would-Deny"] = ",".join(sorted(would_deny))
+
+    @staticmethod
+    def _is_ignored(request):
+        path = request.path or ""
+        for pattern in api_settings.IGNORE_PATHS:
+            if re.search(pattern, path):
+                return True
+        return False

django_api_usage/migrations/0001_initial.py

@@ -0,0 +1,118 @@
+# Generated by Django 4.2.30 on 2026-10-07 15:10
+
+from django.db import migrations, models
+import django.db.models.deletion
+import django.utils.timezone
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="Endpoint",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "site_id",
+                    models.PositiveIntegerField(blank=True, db_index=True, null=True),
+                ),
+                ("app_label", models.CharField(db_index=True, max_length=64)),
+                ("route_name", models.CharField(max_length=160)),
+                ("method", models.CharField(max_length=8)),
+                ("deprecated", models.BooleanField(default=False)),
+                ("sunset_date", models.DateField(blank=True, null=True)),
+                ("replacement", models.CharField(blank=True, max_length=160)),
+                ("owner", models.CharField(blank=True, max_length=160)),
+                ("notes", models.TextField(blank=True)),
+            ],
+            options={
+                "ordering": ("app_label", "route_name", "method"),
+                "unique_together": {("site_id", "app_label", "route_name", "method")},
+            },
+        ),
+        migrations.CreateModel(
+            name="Consumer",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "kind",
+                    models.CharField(
+                        choices=[
+                            ("api_key", "API key"),
+                            ("user", "User"),
+                            ("ip_hash", "IP hash"),
+                        ],
+                        max_length=16,
+                    ),
+                ),
+                ("ref_hash", models.CharField(db_index=True, max_length=64)),
+                ("user_agent_family", models.CharField(blank=True, max_length=64)),
+                ("first_seen", models.DateTimeField(default=django.utils.timezone.now)),
+                ("last_seen", models.DateTimeField(default=django.utils.timezone.now)),
+                ("request_count", models.PositiveIntegerField(default=0)),
+                ("contact", models.CharField(blank=True, max_length=200)),
+                ("notes", models.TextField(blank=True)),
+            ],
+            options={
+                "ordering": ("-last_seen",),
+                "unique_together": {("kind", "ref_hash")},
+            },
+        ),
+        migrations.CreateModel(
+            name="EndpointStat",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("date", models.DateField(db_index=True)),
+                ("client_type", models.CharField(default="anon", max_length=16)),
+                ("status_class", models.CharField(default="2xx", max_length=4)),
+                ("count", models.PositiveIntegerField(default=0)),
+                (
+                    "endpoint",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="stats",
+                        to="django_api_usage.endpoint",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ("-date",),
+                "indexes": [
+                    models.Index(
+                        fields=["date", "endpoint"], name="django_api__date_fd01a8_idx"
+                    )
+                ],
+                "unique_together": {
+                    ("endpoint", "date", "client_type", "status_class")
+                },
+            },
+        ),
+    ]

django_api_usage/models.py

@@ -0,0 +1,95 @@
+"""Data model.
+
+Two layers live here on purpose:
+
+* **Usage metering** (:class:`Endpoint`, :class:`EndpointStat`) is the neutral
+  core: how much is each endpoint of each app used.
+* **Deprecation lifecycle** (the extra fields on :class:`Endpoint`) is the
+  optional layer built on top of the same data.
+"""
+
+from django.db import models
+from django.utils import timezone
+
+
+class Endpoint(models.Model):
+    """One distinct (site, app, route, method) combination that was called."""
+
+    # Plain integer instead of a FK to sites.Site: keeps the package usable in
+    # projects without django.contrib.sites.
+    site_id = models.PositiveIntegerField(null=True, blank=True, db_index=True)
+    app_label = models.CharField(max_length=64, db_index=True)
+    route_name = models.CharField(max_length=160)
+    method = models.CharField(max_length=8)
+
+    # Deprecation lifecycle (optional layer).
+    deprecated = models.BooleanField(default=False)
+    sunset_date = models.DateField(null=True, blank=True)
+    replacement = models.CharField(max_length=160, blank=True)
+    owner = models.CharField(max_length=160, blank=True)
+    notes = models.TextField(blank=True)
+
+    class Meta:
+        unique_together = ("site_id", "app_label", "route_name", "method")
+        ordering = ("app_label", "route_name", "method")
+
+    def __str__(self):
+        return f"{self.method} {self.route_name} ({self.app_label})"
+
+    @property
+    def is_sunset(self):
+        """True when the sunset date has been reached."""
+        return bool(self.sunset_date and self.sunset_date <= timezone.localdate())
+
+    @property
+    def days_until_sunset(self):
+        if not self.sunset_date:
+            return None
+        return (self.sunset_date - timezone.localdate()).days
+
+
+class EndpointStat(models.Model):
+    """Aggregated counter per endpoint, day, client type and status class."""
+
+    endpoint = models.ForeignKey(
+        Endpoint, on_delete=models.CASCADE, related_name="stats"
+    )
+    date = models.DateField(db_index=True)
+    client_type = models.CharField(max_length=16, default="anon")
+    status_class = models.CharField(max_length=4, default="2xx")
+    count = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        unique_together = ("endpoint", "date", "client_type", "status_class")
+        ordering = ("-date",)
+        indexes = [models.Index(fields=["date", "endpoint"])]
+
+    def __str__(self):
+        return f"{self.date} {self.endpoint} {self.client_type} {self.count}"
+
+
+class Consumer(models.Model):
+    """An observed caller, identified only by a salted hash. Opt-in."""
+
+    KIND_CHOICES = (
+        ("api_key", "API key"),
+        ("user", "User"),
+        ("ip_hash", "IP hash"),
+    )
+
+    kind = models.CharField(max_length=16, choices=KIND_CHOICES)
+    ref_hash = models.CharField(max_length=64, db_index=True)
+    user_agent_family = models.CharField(max_length=64, blank=True)
+    first_seen = models.DateTimeField(default=timezone.now)
+    last_seen = models.DateTimeField(default=timezone.now)
+    request_count = models.PositiveIntegerField(default=0)
+    # Manually maintained: who to contact before deprecating something.
+    contact = models.CharField(max_length=200, blank=True)
+    notes = models.TextField(blank=True)
+
+    class Meta:
+        unique_together = ("kind", "ref_hash")
+        ordering = ("-last_seen",)
+
+    def __str__(self):
+        return f"{self.kind} {self.ref_hash[:12]}"

django_api_usage/resolvers.py

@@ -0,0 +1,104 @@
+"""Default resolvers describing a request.
+
+Everything here is overridable from ``API_USAGE`` so the package stays free of
+project-specific knowledge. Resolvers must be cheap: they run on every request.
+"""
+
+import hashlib
+
+from django.conf import settings as django_settings
+
+
+def _view_module(match):
+    """Best-effort module name of the callable that handled the request."""
+    func = getattr(match, "func", None)
+    view_class = getattr(func, "cls", None)  # class-based views and DRF viewsets
+    if view_class is not None:
+        return getattr(view_class, "__module__", "") or ""
+    return getattr(func, "__module__", "") or ""
+
+
+def default_app_label(request):
+    """Return a short application label for the resolved view.
+
+    ``tokikom.gida.views`` -> ``gida``, ``myproject.api.rest_views`` -> ``api``.
+    Override with ``API_USAGE["APP_LABEL_RESOLVER"]`` when your layout differs.
+    """
+    match = getattr(request, "resolver_match", None)
+    if match is None:
+        return "unknown"
+    if getattr(match, "app_name", None):
+        return match.app_name
+    parts = [part for part in _view_module(match).split(".") if part]
+    if not parts:
+        return "unknown"
+    suffixes = {"views", "viewsets", "rest_views", "api"}
+    if len(parts) >= 2 and parts[-1] in suffixes:
+        return parts[-2]
+    return parts[-1]
+
+
+def default_route_name(request):
+    """Return the named URL pattern, never the raw path (cardinality!)."""
+    match = getattr(request, "resolver_match", None)
+    if match is None:
+        return "unknown"
+    return (
+        getattr(match, "url_name", None) or getattr(match, "route", None) or "unknown"
+    )
+
+
+def default_client_type(request):
+    """Classify the caller as ``client``, ``user`` or ``anon``."""
+    if getattr(request, "api_client", None) is not None:
+        return "client"
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        return "user"
+    return "anon"
+
+
+def default_site_id(request):
+    """Return ``settings.SITE_ID`` as an int, or ``None`` when not configured."""
+    site_id = getattr(django_settings, "SITE_ID", None)
+    if site_id is None:
+        return None
+    try:
+        return int(site_id)
+    except (TypeError, ValueError):
+        return None
+
+
+def _hash(value, salt):
+    return hashlib.sha256(f"{salt}:{value}".encode()).hexdigest()
+
+
+def _user_agent_family(request):
+    user_agent = request.META.get("HTTP_USER_AGENT", "") or ""
+    return user_agent.split(" ")[0][:64]
+
+
+def default_consumer(request):
+    """Return ``(kind, ref_hash, user_agent_family)`` or ``None``.
+
+    Raw identifiers are never stored: only a salted SHA-256 digest. Set
+    ``API_USAGE["CONSUMER_SALT"]`` to a secret, rotatable value.
+    """
+    from .conf import api_settings
+
+    salt = api_settings.CONSUMER_SALT or django_settings.SECRET_KEY
+    user_agent_family = _user_agent_family(request)
+
+    api_key = getattr(request, "api_key", None)
+    if api_key is not None:
+        return ("api_key", _hash(str(api_key.pk), salt), user_agent_family)
+
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        return ("user", _hash(str(user.pk), salt), user_agent_family)
+
+    forwarded = request.META.get("HTTP_X_FORWARDED_FOR", "")
+    ip = forwarded.split(",")[0].strip() or request.META.get("REMOTE_ADDR", "")
+    if not ip:
+        return None
+    return ("ip_hash", _hash(ip, salt), user_agent_family)

django_api_usage/tasks.py

@@ -0,0 +1,22 @@
+"""Optional Celery tasks. Requires the ``celery`` extra."""
+
+from .buffers import flush
+from .maintenance import prune
+
+try:
+    from celery import shared_task
+except ImportError:  # pragma: no cover - celery is an optional dependency
+    shared_task = None
+
+
+if shared_task is not None:
+
+    @shared_task
+    def flush_api_usage():
+        """Move buffered counters to the database."""
+        return flush()
+
+    @shared_task
+    def prune_api_usage():
+        """Apply the retention window to raw counters."""
+        return prune()

django_api_usage-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: django-api-usage
+Version: 0.1.0
+Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
+Author-email: CodeSyntax <teknika@codesyntax.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/codesyntax/django-api-usage
+Project-URL: Source, https://github.com/codesyntax/django-api-usage
+Project-URL: Issues, https://github.com/codesyntax/django-api-usage/issues
+Keywords: django,api,usage,metrics,deprecation,drf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == "drf"
+Provides-Extra: celery
+Requires-Dist: celery>=5.2; extra == "celery"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-django; extra == "dev"
+Requires-Dist: djangorestframework>=3.14; extra == "dev"
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: ruff==0.16.10; extra == "dev"
+Dynamic: license-file
+
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-api-usage)
+![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2-0C4B33)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/codesyntax/django-api-usage/ci.yml)
+![PyPI - Version](https://img.shields.io/pypi/v/django-api-usage)
+
+# django-api-usage
+
+Lightweight, privacy-first **usage metering for Django APIs**, with an optional
+**deprecation lifecycle** layer on top.
+
+It answers two questions that decide whether an endpoint can be changed or removed:
+
+1. **How much is this endpoint (or this whole Django app) used?**
+2. **Who is calling it, so they can be contacted before it changes?**
+
+The package is deliberately generic: the core is plain Django middleware (works
+with or without Django REST Framework), it never breaks a request because
+metering failed, and it stores no raw personal data by default.
+
+## Why not just `drf-api-tracking`?
+
+`drf-api-tracking` stores one database row per request (including bodies), which
+is heavy and privacy-sensitive. `django-api-usage` accumulates **counters** and
+keeps consumer attribution **hashed and opt-in**. That makes it suitable both for
+continuous usage analytics and for the concrete decision of deprecating an
+endpoint.
+
+## Install
+
+```bash
+pip install django-api-usage
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_api_usage",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_api_usage.middleware.ApiUsageMiddleware",
+]
+```
+
+Metering starts immediately. Counters are buffered in the cache and written to
+the database in batches:
+
+```bash
+python manage.py api_usage_flush      # from cron, or a Celery beat task
+python manage.py api_usage_report --days 30
+python manage.py api_usage_report --days 90 --sunset-candidates
+```
+
+With Celery (and the `celery` extra) two tasks are provided:
+`django_api_usage.tasks.flush_api_usage` and
+`django_api_usage.tasks.prune_api_usage`.
+
+## Configuration
+
+```python
+API_USAGE = {
+    "ENABLED": True,
+    "FAIL_OPEN": True,
+    "BUFFER_BACKEND": "cache",       # "cache" (batched) or "db" (write per request)
+    "RETENTION_DAYS": 90,
+    "TRACK_CONSUMERS": False,        # opt-in; stores hashed callers only
+    "CONSUMER_SALT": "a-rotatable-secret",
+}
+```
+
+All resolvers are overridable, so no project-specific knowledge leaks into the
+package:
+
+```python
+API_USAGE = {
+    "APP_LABEL_RESOLVER": "myproject.api.resolvers.app_label",
+    "SITE_RESOLVER": "myproject.api.resolvers.site_id",
+    "ROLE_SCOPES_RESOLVER": "myproject.api.resolvers.role_scopes",
+}
+```
+
+## Deprecation lifecycle
+
+`Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the
+same data that measures usage also drives a deprecation plan. See the consuming
+project's migration guide for the full workflow (measure → notify → enforce).
+
+## DRF shadow mode
+
+`django_api_usage.drf.HasAPIScope` enforces scopes declared on a view:
+
+```python
+class AllUserViewSet(viewsets.ReadOnlyModelViewSet):
+    permission_classes = [HasAPIScope]
+    required_scopes = ["user:read_all"]
+```
+
+With `API_ENFORCEMENT = "report"` (the default) nothing is blocked yet: a
+`X-Api-Would-Deny` header is returned instead, so you can deploy a permission and
+measure what it *would* have denied before enforcing it.
+
+## Status
+
+**Alpha.** The core is implemented: metering middleware, models and migrations,
+management commands, the deprecation layer and a DRF shadow-mode permission.
+Tested on Python 3.10-3.12 and Django 4.2/5.2. MIT licensed.
+
+## Development
+
+```bash
+python -m django test tests --settings=tests.settings
+ruff check .
+black --check .
+```

django_api_usage-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+django_api_usage/__init__.py,sha256=Rnl9TTnoJUF0gwudzH71y7EEq2lqCnSLy0AoqP53S7M,105
+django_api_usage/admin.py,sha256=Gs8bTO_4GJCtoRM6Jp94oGkC1Xivt_buz4wmEMxfqY0,1515
+django_api_usage/apps.py,sha256=IP6SBrHpuyHuVvLwIjvgRhV8LAQxp82WkyLO2SRGYZI,342
+django_api_usage/buffers.py,sha256=QInMzFZZHgstuVmSYklH38uLrsiIvD5IrOqM2qjNXQA,4292
+django_api_usage/checks.py,sha256=HT4xVAXMx89faygH7WflfmCfLOMaxEFuPsh8tmriCbA,2509
+django_api_usage/conf.py,sha256=yGBigS_pGqg-N2Ud-trHQWqXfVuAUcZlc5ZXJk3yja0,2872
+django_api_usage/deprecation.py,sha256=e_QSzCL_jHMBcu4XIH4rrjUPqB8APsNhka_pKhZgC_g,1272
+django_api_usage/drf.py,sha256=VucHwwQqA9ZA66XKWcIhfea8qy0q37aDyu2Z_HVI8RA,2499
+django_api_usage/maintenance.py,sha256=z3--j65dWyNDJN5THkSDe3g5u5LcCptjHjfoEvsv8Mc,629
+django_api_usage/middleware.py,sha256=pCunQ5dj8VIAc2PJSm2Ab5WhCuVKH4e7cRyjFUj26bI,2027
+django_api_usage/models.py,sha256=skV4tumzZ2m1AC70TZzlR3t54TOB1-uVohDDg2kUESk,3429
+django_api_usage/resolvers.py,sha256=euoj73k_fP0ypFc3a1OImdUX8c9Cds1TsVZ5X8rbqLI,3509
+django_api_usage/tasks.py,sha256=gGUfvNvv_qvsKGcpER1Q7cGZ8vFodTxItT00w5-JVOY,536
+django_api_usage/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_api_usage/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_api_usage/management/commands/api_usage_flush.py,sha256=51TVn5wiVdM3Vr1Li5pRcEiofpTFRAqrglpgTKxngaA,821
+django_api_usage/management/commands/api_usage_report.py,sha256=fbiXCK2NlEhlE_8bdy7a_zfnTPqlddb885i7WZ2l4GI,2290
+django_api_usage/migrations/0001_initial.py,sha256=0mt6BMYDmHedbQpdd_nChFWb7BxhdH6J1iaKmM6oniw,4432
+django_api_usage/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_api_usage-0.1.0.dist-info/licenses/LICENSE,sha256=wtaPGB5yvwDIUqTgIMOnQDpMc4xjG7qnhvAtTPlEggM,1067
+django_api_usage-0.1.0.dist-info/METADATA,sha256=gf2phpPt2fgiwjAQOnptStsOGpby32Ki3F_DcrnERj0,5291
+django_api_usage-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_api_usage-0.1.0.dist-info/top_level.txt,sha256=M0Lfi57fatFaVtRXWLvyuHRbYp3UsnHy-f1Xqa-0z8A,17
+django_api_usage-0.1.0.dist-info/RECORD,,

django_api_usage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_api_usage-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeSyntax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_api_usage-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_api_usage