django-api-usage 0.1.0__tar.gz

django_api_usage-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,116 @@
+![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/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-api-usage"
+version = "0.1.0"
+description = "Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "CodeSyntax", email = "teknika@codesyntax.com" }]
+keywords = ["django", "api", "usage", "metrics", "deprecation", "drf"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = ["Django>=4.2"]
+
+[project.optional-dependencies]
+drf = ["djangorestframework>=3.14"]
+celery = ["celery>=5.2"]
+redis = ["redis>=4.0"]
+dev = ["pytest", "pytest-django", "djangorestframework>=3.14", "black==26.5.1", "ruff==0.16.10"]
+
+[project.urls]
+Homepage = "https://github.com/codesyntax/django-api-usage"
+Source = "https://github.com/codesyntax/django-api-usage"
+Issues = "https://github.com/codesyntax/django-api-usage/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src", "."]
+testpaths = ["tests"]

django_api_usage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_api_usage-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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