django-api-usage 0.1.5__tar.gz → 0.1.7__tar.gz

{django_api_usage-0.1.5/src/django_api_usage.egg-info → django_api_usage-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.5
+Version: 0.1.7
 Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
 Author-email: CodeSyntax <teknika@codesyntax.com>
 License-Expression: MIT
@@ -127,8 +127,12 @@ Django — **no dependency beyond Django itself** (no `django-object-actions` or
 similar):
 
 * **Endpoint stats** changelist: a search box (by endpoint path, route name, app,
-  method or replacement), filters by date, profile and role, and the **sum of
-  the `count` column** for the rows matching the current filters.
+  method or replacement), filters by date, client type, status class, and
+  **Application** / **Method**, plus the **sum of the `count` column** for the
+  rows matching the current filters. The Method filter lists the riskiest verbs
+  first (`DELETE`, `POST`, ...), so write and destructive calls stand out.
+* **Endpoint** changelist: the same Application / Method filters, plus
+  deprecation state, the site and the CSV export.
 * **Flush now**: moves counters buffered in the cache into the database, so they
   appear immediately when you run with `BUFFER_BACKEND = "cache"`.
 * **Clear statistics**: empties the aggregated counters behind a confirmation
@@ -138,6 +142,28 @@ similar):
   and method), so the file can be fed straight to pandas or a spreadsheet. Use
   the "select all" link to export every row matching the current filters.
 
+## Client applications
+
+Not every caller is a person: ERPs, partners, your own web front end and the
+native mobile apps also hit the API. `ClientApp` is an **editable table**, so a
+new consumer is recognised from the admin, without a deploy:
+
+| Rule | Matched against | Use it for |
+|---|---|---|
+| `accounts` | the authenticated user (and therefore its DRF token) | one dedicated token per integration (ERP, partner...) |
+| `domains` | the `Origin`/`Referer` host, subdomains included | your own web front end |
+| `ip_networks` | the client address, against a CIDR (one per line) | internal networks and servers |
+| `user_agent_patterns` | a case-insensitive substring of `User-Agent` | native mobile apps |
+
+Rules are checked in that order, and `priority` decides between applications
+(lower wins). A caller matching nothing stays unattributed, so the dimension
+cannot grow out of control: `EndpointStat.client_app` only ever holds a
+`ClientApp.slug`.
+
+Counters, the CSV export and the admin filters all carry the application, so
+"which application calls this endpoint?" is one filter away. The **Endpoint
+stats** changelist also offers *Not attributed*: the callers still to classify.
+
 ## Deprecation lifecycle
 
 `Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/README.md

@@ -88,8 +88,12 @@ Django — **no dependency beyond Django itself** (no `django-object-actions` or
 similar):
 
 * **Endpoint stats** changelist: a search box (by endpoint path, route name, app,
-  method or replacement), filters by date, profile and role, and the **sum of
-  the `count` column** for the rows matching the current filters.
+  method or replacement), filters by date, client type, status class, and
+  **Application** / **Method**, plus the **sum of the `count` column** for the
+  rows matching the current filters. The Method filter lists the riskiest verbs
+  first (`DELETE`, `POST`, ...), so write and destructive calls stand out.
+* **Endpoint** changelist: the same Application / Method filters, plus
+  deprecation state, the site and the CSV export.
 * **Flush now**: moves counters buffered in the cache into the database, so they
   appear immediately when you run with `BUFFER_BACKEND = "cache"`.
 * **Clear statistics**: empties the aggregated counters behind a confirmation
@@ -99,6 +103,28 @@ similar):
   and method), so the file can be fed straight to pandas or a spreadsheet. Use
   the "select all" link to export every row matching the current filters.
 
+## Client applications
+
+Not every caller is a person: ERPs, partners, your own web front end and the
+native mobile apps also hit the API. `ClientApp` is an **editable table**, so a
+new consumer is recognised from the admin, without a deploy:
+
+| Rule | Matched against | Use it for |
+|---|---|---|
+| `accounts` | the authenticated user (and therefore its DRF token) | one dedicated token per integration (ERP, partner...) |
+| `domains` | the `Origin`/`Referer` host, subdomains included | your own web front end |
+| `ip_networks` | the client address, against a CIDR (one per line) | internal networks and servers |
+| `user_agent_patterns` | a case-insensitive substring of `User-Agent` | native mobile apps |
+
+Rules are checked in that order, and `priority` decides between applications
+(lower wins). A caller matching nothing stays unattributed, so the dimension
+cannot grow out of control: `EndpointStat.client_app` only ever holds a
+`ClientApp.slug`.
+
+Counters, the CSV export and the admin filters all carry the application, so
+"which application calls this endpoint?" is one filter away. The **Endpoint
+stats** changelist also offers *Not attributed*: the callers still to classify.
+
 ## Deprecation lifecycle
 
 `Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-api-usage"
-version = "0.1.5"
+version = "0.1.7"
 description = "Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer."
 readme = "README.md"
 license = "MIT"
@@ -42,7 +42,11 @@ Issues = "https://github.com/codesyntax/django-api-usage/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-django_api_usage = ["templates/admin/django_api_usage/endpointstat/*.html"]
+django_api_usage = [
+    "templates/admin/django_api_usage/endpointstat/*.html",
+    "locale/*/LC_MESSAGES/*.po",
+    "locale/*/LC_MESSAGES/*.mo",
+]
 
 [tool.black]
 line-length = 88

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/src/django_api_usage/__init__.py

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

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/src/django_api_usage/admin.py

@@ -16,7 +16,7 @@ Everything is plain Django: no extra dependency beyond Django itself.
 import csv
 
 from django.contrib import admin, messages
-from django.db.models import Sum
+from django.db.models import Count, OuterRef, Subquery, Sum
 from django.http import HttpResponse, HttpResponseRedirect
 from django.template.response import TemplateResponse
 from django.urls import path, reverse
@@ -25,7 +25,7 @@ from django.utils.text import format_lazy
 from django.utils.translation import gettext_lazy as _
 
 from .buffers import flush
-from .models import Consumer, Endpoint, EndpointStat
+from .models import ClientApp, Consumer, Endpoint, EndpointStat
 
 
 class CsvExportMixin:
@@ -60,6 +60,107 @@ class CsvExportMixin:
         return response
 
 
+#: HTTP methods, riskiest first: the point of the filter is spotting the
+#: write/destructive calls (POST, DELETE, ...) instead of the read ones.
+METHOD_ORDER = ("DELETE", "POST", "PUT", "PATCH", "GET", "HEAD", "OPTIONS")
+
+
+class AppLabelListFilter(admin.SimpleListFilter):
+    """Distinct application labels, under a readable title."""
+
+    title = _("Application")
+    parameter_name = "app_label"
+    #: Lookup against the admin's model; overridden for related filters.
+    field_path = "app_label"
+
+    def lookups(self, request, model_admin):
+        values = (
+            model_admin.model.objects.order_by()
+            .values_list(self.field_path, flat=True)
+            .distinct()
+        )
+        return [(value, value) for value in sorted(v for v in values if v)]
+
+    def queryset(self, request, queryset):
+        if not self.value():
+            return queryset
+        return queryset.filter(**{self.field_path: self.value()})
+
+
+class MethodListFilter(admin.SimpleListFilter):
+    """HTTP methods, riskiest (DELETE, POST, ...) first."""
+
+    title = _("Method")
+    parameter_name = "method"
+    field_path = "method"
+
+    def lookups(self, request, model_admin):
+        values = set(
+            model_admin.model.objects.order_by()
+            .values_list(self.field_path, flat=True)
+            .distinct()
+        )
+        ordered = [method for method in METHOD_ORDER if method in values]
+        rest = sorted(m for m in values if m and m not in METHOD_ORDER)
+        return [(method, method) for method in ordered + rest]
+
+    def queryset(self, request, queryset):
+        if not self.value():
+            return queryset
+        return queryset.filter(**{self.field_path: self.value()})
+
+
+class StatAppLabelListFilter(AppLabelListFilter):
+    """Application filter for the stats changelist (through the endpoint)."""
+
+    field_path = "endpoint__app_label"
+
+
+class StatMethodListFilter(MethodListFilter):
+    """Method filter for the stats changelist (through the endpoint)."""
+
+    field_path = "endpoint__method"
+
+
+#: Sentinel for the calls that could not be attributed to any application.
+UNATTRIBUTED = "__none__"
+
+
+class ClientAppListFilter(admin.SimpleListFilter):
+    """Client applications, plus the calls that were not attributed.
+
+    Applications defined in the table are listed even before they have traffic,
+    which is what you want while checking that a new rule works.
+    """
+
+    title = _("Client application")
+    parameter_name = "client_app"
+
+    def lookups(self, request, model_admin):
+        used = set(
+            model_admin.model.objects.order_by()
+            .values_list("client_app", flat=True)
+            .distinct()
+        )
+        names = dict(ClientApp.objects.values_list("slug", "name"))
+        defined = set(
+            ClientApp.objects.filter(is_active=True).values_list("slug", flat=True)
+        )
+        choices = [
+            (slug, names.get(slug) or slug) for slug in sorted((used | defined) - {""})
+        ]
+        choices.append((UNATTRIBUTED, _("Not attributed")))
+        return choices
+
+    def queryset(self, request, queryset):
+        value = self.value()
+        if value == UNATTRIBUTED:
+            return queryset.filter(client_app="")
+        if value:
+            return queryset.filter(client_app=value)
+        return queryset
+
+
 @admin.register(Endpoint)
 class EndpointAdmin(CsvExportMixin, admin.ModelAdmin):
     actions = ("export_as_csv",)
@@ -86,7 +187,12 @@ class EndpointAdmin(CsvExportMixin, admin.ModelAdmin):
         "replacement",
         "owner",
     )
-    list_filter = ("deprecated", "app_label", "method", "site_id")
+    list_filter = (
+        "deprecated",
+        AppLabelListFilter,
+        MethodListFilter,
+        "site_id",
+    )
     search_fields = ("route_path", "route_name", "replacement", "owner", "notes")
     list_editable = ("deprecated", "sunset_date", "replacement", "owner")
 
@@ -104,11 +210,26 @@ class EndpointStatAdmin(CsvExportMixin, admin.ModelAdmin):
         ("method", "endpoint__method"),
         ("site_id", "endpoint__site_id"),
         ("client_type", "client_type"),
+        ("client_app", "client_app"),
         ("status_class", "status_class"),
         ("count", "count"),
     )
-    list_display = ("date", "endpoint", "client_type", "status_class", "count")
-    list_filter = ("date", "client_type", "status_class")
+    list_display = (
+        "date",
+        "endpoint",
+        "client_type",
+        "client_app",
+        "status_class",
+        "count",
+    )
+    list_filter = (
+        "date",
+        "client_type",
+        ClientAppListFilter,
+        "status_class",
+        StatAppLabelListFilter,
+        StatMethodListFilter,
+    )
     list_select_related = ("endpoint",)
     date_hierarchy = "date"
     # Search across the related endpoint (case-insensitive "contains").
@@ -241,3 +362,72 @@ class ConsumerAdmin(CsvExportMixin, admin.ModelAdmin):
     @admin.display(description="Reference")
     def ref_short(self, obj):
         return obj.ref_hash[:12]
+
+
+@admin.register(ClientApp)
+class ClientAppAdmin(CsvExportMixin, admin.ModelAdmin):
+    """Editable table: recognise a new consumer without deploying anything."""
+
+    actions = ("export_as_csv",)
+    csv_columns = (
+        ("slug", "slug"),
+        ("name", "name"),
+        ("priority", "priority"),
+        ("is_active", "is_active"),
+        ("domains", "domains"),
+        ("ip_networks", "ip_networks"),
+        ("user_agent_patterns", "user_agent_patterns"),
+    )
+    list_display = (
+        "slug",
+        "name",
+        "priority",
+        "is_active",
+        "accounts_total",
+        "counters_total",
+    )
+    list_filter = ("is_active",)
+    search_fields = ("slug", "name", "description")
+    filter_horizontal = ("accounts",)
+    fieldsets = (
+        (None, {"fields": ("slug", "name", "description", "priority", "is_active")}),
+        (
+            _("Matching rules"),
+            {
+                "fields": (
+                    "accounts",
+                    "domains",
+                    "ip_networks",
+                    "user_agent_patterns",
+                ),
+                "description": _(
+                    "Checked in this order: account, request host, client "
+                    "network, user agent. Between applications, the lowest "
+                    "priority wins."
+                ),
+            },
+        ),
+    )
+
+    def get_queryset(self, request):
+        counters = (
+            EndpointStat.objects.filter(client_app=OuterRef("slug"))
+            .order_by()
+            .values("client_app")
+            .annotate(total=Sum("count"))
+            .values("total")
+        )
+        return (
+            super()
+            .get_queryset(request)
+            .annotate(accounts_total=Count("accounts", distinct=True))
+            .annotate(counters_total=Subquery(counters))
+        )
+
+    @admin.display(description=_("Accounts"), ordering="accounts_total")
+    def accounts_total(self, obj):
+        return obj.accounts_total
+
+    @admin.display(description=_("Counters"), ordering="counters_total")
+    def counters_total(self, obj):
+        return obj.counters_total or 0

django_api_usage-0.1.7/src/django_api_usage/apps.py

@@ -0,0 +1,34 @@
+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
+
+        self._connect_client_app_signals()
+
+    def _connect_client_app_signals(self):
+        """Drop the cached ClientApp rules as soon as the table changes."""
+        from django.db.models.signals import m2m_changed, post_delete, post_save
+
+        from .models import ClientApp
+        from .resolvers import reset_client_app_cache
+
+        post_save.connect(
+            reset_client_app_cache, sender=ClientApp, dispatch_uid="api_usage_app_save"
+        )
+        post_delete.connect(
+            reset_client_app_cache,
+            sender=ClientApp,
+            dispatch_uid="api_usage_app_delete",
+        )
+        m2m_changed.connect(
+            reset_client_app_cache,
+            sender=ClientApp.accounts.through,
+            dispatch_uid="api_usage_app_accounts",
+        )

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/src/django_api_usage/buffers.py

@@ -30,6 +30,7 @@ _FIELDS = (
     "route_path",
     "method",
     "client_type",
+    "client_app",
 )
 
 
@@ -126,6 +127,7 @@ def _write_to_db(dimensions, status_code_class, count):
             endpoint=endpoint,
             date=timezone.localdate(),
             client_type=dimensions.get("client_type") or "anon",
+            client_app=dimensions.get("client_app") or "",
             status_class=status_code_class,
             defaults={"count": count},
         )

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/src/django_api_usage/conf.py

@@ -33,6 +33,7 @@ DEFAULTS = {
     "APP_LABEL_RESOLVER": "django_api_usage.resolvers.default_app_label",
     "ROUTE_NAME_RESOLVER": "django_api_usage.resolvers.default_route_name",
     "ROUTE_PATH_RESOLVER": "django_api_usage.resolvers.default_route_path",
+    "CLIENT_APP_RESOLVER": "django_api_usage.resolvers.client_app_from_rules",
     "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",

django_api_usage-0.1.7/src/django_api_usage/locale/eu/LC_MESSAGES/django.po

@@ -0,0 +1,169 @@
+# Basque translation of django-api-usage.
+# Copyright (C) 2026 CodeSyntax
+# This file is distributed under the same license as the django-api-usage package.
+# Urtzi Odriozola <uodriozola@codesyntax.com>, 2026.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: django-api-usage\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-10-08 06:45-0500\n"
+"PO-Revision-Date: 2026-10-08 06:55-0500\n"
+"Last-Translator: Urtzi Odriozola <uodriozola@codesyntax.com>\n"
+"Language-Team: Basque\n"
+"Language: eu\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: src/django_api_usage/admin.py:46
+msgid "Export selected rows to CSV"
+msgstr "Esportatu hautatutako errenkadak CSVra"
+
+#: src/django_api_usage/admin.py:71
+msgid "Application"
+msgstr "Aplikazioa"
+
+#: src/django_api_usage/admin.py:93
+msgid "Method"
+msgstr "Metodoa"
+
+#: src/django_api_usage/admin.py:136 src/django_api_usage/models.py:106
+msgid "Client application"
+msgstr "Bezero-aplikazioa"
+
+#: src/django_api_usage/admin.py:152
+msgid "Not attributed"
+msgstr "Esleitu gabea"
+
+#: src/django_api_usage/admin.py:244
+msgid ""
+"Search by endpoint path, route name, app, method or replacement (for example "
+"'herriak' or 'artikuluak')."
+msgstr ""
+"Bilatu endpointaren bidearen, route-izenaren, aplikazioaren, metodoaren edo "
+"ordezkoaren arabera (adibidez 'herriak' edo 'artikuluak')."
+
+#: src/django_api_usage/admin.py:299
+#, python-brace-format
+msgid "Flushed {count} buffered counter(s)."
+msgstr "{count} kontagailu eraman dira bufferretik datu-basera."
+
+#: src/django_api_usage/admin.py:306
+msgid ""
+"Nothing was buffered: with BUFFER_BACKEND='db' counters are already in the "
+"database."
+msgstr ""
+"Ez zegoen ezer bufferrean: BUFFER_BACKEND='db' denean kontagailuak jada "
+"datu-basean daude."
+
+#: src/django_api_usage/admin.py:318
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/change_list.html:12
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:8
+msgid "Clear statistics"
+msgstr "Estatistikak hustu"
+
+#: src/django_api_usage/admin.py:330
+#, python-brace-format
+msgid "Deleted {count} statistic row(s)."
+msgstr "{count} estatistika-errenkada ezabatu dira."
+
+#: src/django_api_usage/admin.py:395
+msgid "Matching rules"
+msgstr "Bat-etortze arauak"
+
+#: src/django_api_usage/admin.py:404
+msgid ""
+"Checked in this order: account, request host, client network, user agent. "
+"Between applications, the lowest priority wins."
+msgstr ""
+"Ordena honetan egiaztatzen da: kontua, eskaeraren ostalaria, bezeroaren sarea "
+"eta user agent-a. Aplikazioen artean, lehentasun txikiena duenak irabazten du."
+
+#: src/django_api_usage/admin.py:427
+msgid "Accounts"
+msgstr "Kontuak"
+
+#: src/django_api_usage/admin.py:431
+msgid "Counters"
+msgstr "Kontagailuak"
+
+#: src/django_api_usage/models.py:79
+msgid "Short, stable label stored in the counters (e.g. 'mugikorra')."
+msgstr ""
+"Kontagailuetan gordetzen den etiketa labur eta egonkorra (adib. 'mugikorra')."
+
+#: src/django_api_usage/models.py:85
+msgid "Lower wins when several apps could match."
+msgstr "Hainbat aplikaziok bat etorri ahalketenean, txikienak irabazten du."
+
+#: src/django_api_usage/models.py:91
+msgid "Users (and therefore DRF tokens) that belong to this app."
+msgstr "Aplikazio honi dagozkion erabiltzaileak (eta, beraz, haien DRF tokenak)."
+
+#: src/django_api_usage/models.py:95
+msgid "One host per line; matched against the Origin/Referer host."
+msgstr "Ostalari bat lerroko; Origin/Referer ostalariaren aurka egiaztatzen da."
+
+#: src/django_api_usage/models.py:98
+msgid "One CIDR per line, e.g. 10.0.0.0/8."
+msgstr "CIDR bat lerroko, adib. 10.0.0.0/8."
+
+#: src/django_api_usage/models.py:102
+msgid "One substring per line, matched case-insensitively."
+msgstr "Azpikate bat lerroko; maiuskulak/minuskulak bereizi gabe egiaztatzen da."
+
+#: src/django_api_usage/models.py:107
+msgid "Client applications"
+msgstr "Bezero-aplikazioak"
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/change_list.html:8
+msgid "Flush now"
+msgstr "Flush orain"
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/change_list.html:21
+#, python-format
+msgid "TOTAL COUNT: %(total)s"
+msgstr "GUZTIRA: %(total)s"
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:6
+msgid "Home"
+msgstr ""
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:7
+msgid "Endpoint stats"
+msgstr "Endpoint estatistikak"
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:14
+#, python-format
+msgid ""
+"\n"
+"      This will delete the only aggregated statistic row. Endpoints and "
+"their\n"
+"      deprecation metadata are kept.\n"
+"    "
+msgid_plural ""
+"\n"
+"      This will delete all %(counter)s aggregated statistic rows. Endpoints\n"
+"      and their deprecation metadata are kept.\n"
+"    "
+msgstr[0] ""
+"\n"
+"      Estatistika-errenkada agregatu bakarra ezabatuko da. Endpointak eta "
+"haien\n"
+"      deprecation-metadatuak mantendu egingo dira.\n"
+"    "
+msgstr[1] ""
+"\n"
+"      %(counter)s estatistika-errenkada agregatu ezabatuko dira. Endpointak\n"
+"      eta haien deprecation-metadatuak mantendu egingo dira.\n"
+"    "
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:24
+msgid "Yes, clear statistics"
+msgstr "Bai, estatistikak hustu"
+
+#: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:25
+msgid "Cancel"
+msgstr ""

{django_api_usage-0.1.5 → django_api_usage-0.1.7}/src/django_api_usage/middleware.py

@@ -36,6 +36,7 @@ class ApiUsageMiddleware:
                 "route_path": api_settings.ROUTE_PATH_RESOLVER(request),
                 "method": request.method,
                 "client_type": api_settings.CLIENT_TYPE_RESOLVER(request),
+                "client_app": api_settings.CLIENT_APP_RESOLVER(request),
             }
             consumer = None
             if api_settings.TRACK_CONSUMERS: