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

{django_api_usage-0.1.6/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.6
+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
@@ -142,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.6 → django_api_usage-0.1.7}/README.md

@@ -103,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.6 → 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.6"
+version = "0.1.7"
 description = "Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer."
 readme = "README.md"
 license = "MIT"

{django_api_usage-0.1.6 → 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.6"
+__version__ = "0.1.7"

{django_api_usage-0.1.6 → 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:
@@ -122,6 +122,45 @@ class StatMethodListFilter(MethodListFilter):
     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",)
@@ -171,13 +210,22 @@ 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_display = (
+        "date",
+        "endpoint",
+        "client_type",
+        "client_app",
+        "status_class",
+        "count",
+    )
     list_filter = (
         "date",
         "client_type",
+        ClientAppListFilter,
         "status_class",
         StatAppLabelListFilter,
         StatMethodListFilter,
@@ -314,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.6 → 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.6 → 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.6 → django_api_usage-0.1.7}/src/django_api_usage/locale/eu/LC_MESSAGES/django.po

@@ -7,8 +7,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: django-api-usage\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-10-08 06:10-0500\n"
-"PO-Revision-Date: 2026-10-08 06:20-0500\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"
@@ -29,7 +29,15 @@ msgstr "Aplikazioa"
 msgid "Method"
 msgstr "Metodoa"
 
-#: src/django_api_usage/admin.py:196
+#: 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')."
@@ -37,30 +45,79 @@ msgstr ""
 "Bilatu endpointaren bidearen, route-izenaren, aplikazioaren, metodoaren edo "
 "ordezkoaren arabera (adibidez 'herriak' edo 'artikuluak')."
 
-#: src/django_api_usage/admin.py:251
+#: 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:258
+#: 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."
+"Ez zegoen ezer bufferrean: BUFFER_BACKEND='db' denean kontagailuak jada "
+"datu-basean daude."
 
-#: src/django_api_usage/admin.py:270
+#: 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:282
+#: 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"
@@ -68,7 +125,7 @@ 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 ""
+msgstr "GUZTIRA: %(total)s"
 
 #: src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html:6
 msgid "Home"

{django_api_usage-0.1.6 → 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:

django_api_usage-0.1.7/src/django_api_usage/migrations/0003_alter_endpointstat_unique_together_and_more.py

@@ -0,0 +1,96 @@
+# Generated by Django 4.2.30 on 2026-10-08 11:42
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("django_api_usage", "0002_endpoint_route_path"),
+    ]
+
+    operations = [
+        migrations.AlterUniqueTogether(
+            name="endpointstat",
+            unique_together=set(),
+        ),
+        migrations.AddField(
+            model_name="endpointstat",
+            name="client_app",
+            field=models.CharField(blank=True, max_length=64),
+        ),
+        migrations.AlterUniqueTogether(
+            name="endpointstat",
+            unique_together={
+                ("endpoint", "date", "client_type", "client_app", "status_class")
+            },
+        ),
+        migrations.CreateModel(
+            name="ClientApp",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "slug",
+                    models.SlugField(
+                        help_text="Short, stable label stored in the counters (e.g. 'mugikorra').",
+                        max_length=64,
+                        unique=True,
+                    ),
+                ),
+                ("name", models.CharField(blank=True, max_length=160)),
+                ("description", models.TextField(blank=True)),
+                ("is_active", models.BooleanField(default=True)),
+                (
+                    "priority",
+                    models.PositiveSmallIntegerField(
+                        default=100,
+                        help_text="Lower wins when several apps could match.",
+                    ),
+                ),
+                (
+                    "domains",
+                    models.TextField(
+                        blank=True,
+                        help_text="One host per line; matched against the Origin/Referer host.",
+                    ),
+                ),
+                (
+                    "ip_networks",
+                    models.TextField(
+                        blank=True, help_text="One CIDR per line, e.g. 10.0.0.0/8."
+                    ),
+                ),
+                (
+                    "user_agent_patterns",
+                    models.TextField(
+                        blank=True,
+                        help_text="One substring per line, matched case-insensitively.",
+                    ),
+                ),
+                (
+                    "accounts",
+                    models.ManyToManyField(
+                        blank=True,
+                        help_text="Users (and therefore DRF tokens) that belong to this app.",
+                        related_name="+",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Client application",
+                "verbose_name_plural": "Client applications",
+                "ordering": ("priority", "slug"),
+            },
+        ),
+    ]

{django_api_usage-0.1.6 → django_api_usage-0.1.7}/src/django_api_usage/models.py

@@ -1,15 +1,25 @@
 """Data model.
 
-Two layers live here on purpose:
+Three layers live here on purpose:
 
 * **Usage metering** (:class:`Endpoint`, :class:`EndpointStat`) is the neutral
-  core: how much is each endpoint of each app used.
+  core: how much is each endpoint of each app used, and by which client
+  application (:class:`ClientApp`).
+* **Client attribution** (:class:`ClientApp`) is editable data, so new consumers
+  can be recognised from the admin without a deploy.
 * **Deprecation lifecycle** (the extra fields on :class:`Endpoint`) is the
   optional layer built on top of the same data.
 """
 
+from django.conf import settings
 from django.db import models
 from django.utils import timezone
+from django.utils.translation import gettext_lazy as _
+
+
+def _lines(value):
+    """Split a textarea into non-empty, stripped lines."""
+    return [line.strip() for line in (value or "").splitlines() if line.strip()]
 
 
 class Endpoint(models.Model):
@@ -52,19 +62,85 @@ class Endpoint(models.Model):
         return (self.sunset_date - timezone.localdate()).days
 
 
+class ClientApp(models.Model):
+    """An application that consumes the API (mobile app, ERP, partner, ...).
+
+    Editable on purpose: the mapping is data, not code. A blank ``slug``-less
+    request is attributed to no app at all, so the rules can grow without a
+    deploy.
+
+    Resolution order is: authenticated account, request host, client network,
+    then user agent. ``priority`` breaks ties (lower wins).
+    """
+
+    slug = models.SlugField(
+        max_length=64,
+        unique=True,
+        help_text=_("Short, stable label stored in the counters (e.g. 'mugikorra')."),
+    )
+    name = models.CharField(max_length=160, blank=True)
+    description = models.TextField(blank=True)
+    is_active = models.BooleanField(default=True)
+    priority = models.PositiveSmallIntegerField(
+        default=100, help_text=_("Lower wins when several apps could match.")
+    )
+    accounts = models.ManyToManyField(
+        settings.AUTH_USER_MODEL,
+        blank=True,
+        related_name="+",
+        help_text=_("Users (and therefore DRF tokens) that belong to this app."),
+    )
+    domains = models.TextField(
+        blank=True,
+        help_text=_("One host per line; matched against the Origin/Referer host."),
+    )
+    ip_networks = models.TextField(
+        blank=True, help_text=_("One CIDR per line, e.g. 10.0.0.0/8.")
+    )
+    user_agent_patterns = models.TextField(
+        blank=True,
+        help_text=_("One substring per line, matched case-insensitively."),
+    )
+
+    class Meta:
+        verbose_name = _("Client application")
+        verbose_name_plural = _("Client applications")
+        ordering = ("priority", "slug")
+
+    def __str__(self):
+        return self.name or self.slug
+
+    def domain_list(self):
+        return _lines(self.domains)
+
+    def network_list(self):
+        return _lines(self.ip_networks)
+
+    def user_agent_list(self):
+        return [pattern.lower() for pattern in _lines(self.user_agent_patterns)]
+
+
 class EndpointStat(models.Model):
-    """Aggregated counter per endpoint, day, client type and status class."""
+    """Aggregated counter per endpoint, day, client 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")
+    #: ``ClientApp.slug``; blank when the caller could not be attributed.
+    client_app = models.CharField(max_length=64, blank=True)
     status_class = models.CharField(max_length=4, default="2xx")
     count = models.PositiveIntegerField(default=0)
 
     class Meta:
-        unique_together = ("endpoint", "date", "client_type", "status_class")
+        unique_together = (
+            "endpoint",
+            "date",
+            "client_type",
+            "client_app",
+            "status_class",
+        )
         ordering = ("-date",)
         indexes = [models.Index(fields=["date", "endpoint"])]
 

{django_api_usage-0.1.6 → django_api_usage-0.1.7}/src/django_api_usage/resolvers.py

@@ -5,9 +5,15 @@ project-specific knowledge. Resolvers must be cheap: they run on every request.
 """
 
 import hashlib
+import ipaddress
+import logging
+import time
+from urllib.parse import urlsplit
 
 from django.conf import settings as django_settings
 
+logger = logging.getLogger("django_api_usage")
+
 
 def _view_module(match):
     """Best-effort module name of the callable that handled the request."""
@@ -114,3 +120,113 @@ def default_consumer(request):
     if not ip:
         return None
     return ("ip_hash", _hash(ip, salt), user_agent_family)
+
+
+# -- client application attribution -----------------------------------------
+
+#: Safety net for processes that did not see the signal (see ``apps.py``).
+CLIENT_APP_RULES_TTL = 60
+_rules_cache = {"loaded_at": 0.0, "rules": None}
+
+
+def reset_client_app_cache(**kwargs):
+    """Forget the cached :class:`~django_api_usage.models.ClientApp` rules."""
+    _rules_cache["rules"] = None
+    _rules_cache["loaded_at"] = 0.0
+
+
+def _load_client_app_rules():
+    from .models import ClientApp
+
+    rules = {"by_user": {}, "hosts": [], "networks": [], "patterns": []}
+    apps = ClientApp.objects.filter(is_active=True).prefetch_related("accounts")
+    for app in apps:  # ordered by priority, then slug
+        for user_id in app.accounts.values_list("pk", flat=True):
+            rules["by_user"].setdefault(user_id, app.slug)
+        rules["hosts"].extend((host.lower(), app.slug) for host in app.domain_list())
+        for cidr in app.network_list():
+            try:
+                network = ipaddress.ip_network(cidr, strict=False)
+            except ValueError:
+                logger.warning(
+                    "django-api-usage: ignoring invalid network %r on %s", cidr, app
+                )
+                continue
+            rules["networks"].append((network, app.slug))
+        rules["patterns"].extend(
+            (pattern, app.slug) for pattern in app.user_agent_list()
+        )
+    return rules
+
+
+def _client_app_rules():
+    now = time.monotonic()
+    if (
+        _rules_cache["rules"] is None
+        or now - _rules_cache["loaded_at"] > CLIENT_APP_RULES_TTL
+    ):
+        _rules_cache["rules"] = _load_client_app_rules()
+        _rules_cache["loaded_at"] = now
+    return _rules_cache["rules"]
+
+
+def _request_host(request):
+    """Host of the ``Origin`` (or ``Referer``) header, lowercased."""
+    for header in ("HTTP_ORIGIN", "HTTP_REFERER"):
+        value = request.META.get(header)
+        if value:
+            host = urlsplit(value).hostname
+            if host:
+                return host.lower()
+    return ""
+
+
+def client_ip(request):
+    """Client address, honouring the first ``X-Forwarded-For`` entry."""
+    forwarded = request.META.get("HTTP_X_FORWARDED_FOR", "")
+    return forwarded.split(",")[0].strip() or request.META.get("REMOTE_ADDR", "")
+
+
+def client_app_from_rules(request):
+    """Attribute the caller to a :class:`ClientApp`, or return ``""``.
+
+    The rules live in the database and are editable from the admin, so a new
+    consumer can be recognised without a deploy. Monitored order: the caller's
+    account (a dedicated token), then the request host, then the client network,
+    then the user agent. ``ClientApp.priority`` decides the order between apps.
+    """
+    rules = _client_app_rules()
+
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        slug = rules["by_user"].get(user.pk)
+        if slug:
+            return slug
+
+    host = _request_host(request)
+    if host:
+        for pattern, slug in rules["hosts"]:
+            if host == pattern or host.endswith("." + pattern):
+                return slug
+
+    address = _as_address(client_ip(request))
+    if address is not None:
+        for network, slug in rules["networks"]:
+            if address.version == network.version and address in network:
+                return slug
+
+    user_agent = request.META.get("HTTP_USER_AGENT", "").lower()
+    if user_agent:
+        for pattern, slug in rules["patterns"]:
+            if pattern in user_agent:
+                return slug
+    return ""
+
+
+def _as_address(value):
+    if not value:
+        return None
+    try:
+        return ipaddress.ip_address(value)
+    except ValueError:
+        return None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.6
+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
@@ -142,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.6 → django_api_usage-0.1.7}/src/django_api_usage.egg-info/SOURCES.txt

@@ -27,11 +27,13 @@ src/django_api_usage/management/commands/api_usage_flush.py
 src/django_api_usage/management/commands/api_usage_report.py
 src/django_api_usage/migrations/0001_initial.py
 src/django_api_usage/migrations/0002_endpoint_route_path.py
+src/django_api_usage/migrations/0003_alter_endpointstat_unique_together_and_more.py
 src/django_api_usage/migrations/__init__.py
 src/django_api_usage/templates/admin/django_api_usage/endpointstat/change_list.html
 src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html
 tests/test_admin.py
 tests/test_checks.py
+tests/test_client_app.py
 tests/test_commands.py
 tests/test_csv_export.py
 tests/test_drf.py

django_api_usage-0.1.7/tests/test_client_app.py

@@ -0,0 +1,159 @@
+"""Tests for the editable ClientApp table and its matching rules."""
+
+from django.contrib.auth.models import User
+from django.test import RequestFactory
+from django.urls import reverse
+
+from django_api_usage.buffers import flush
+from django_api_usage.models import ClientApp, Endpoint, EndpointStat
+from django_api_usage.resolvers import client_app_from_rules, reset_client_app_cache
+
+from .base import UsageTestCase
+
+STAT_CHANGELIST = "admin:django_api_usage_endpointstat_changelist"
+
+
+class ClientAppResolverTest(UsageTestCase):
+    def setUp(self):
+        super().setUp()
+        reset_client_app_cache()
+        self.factory = RequestFactory()
+
+    def request(self, user=None, **meta):
+        request = self.factory.get("/api/3.0/artikuluak/", **meta)
+        if user is not None:
+            request.user = user
+        return request
+
+    def test_a_dedicated_account_wins(self):
+        """A dedicated token (its user) identifies the integration."""
+        user = User.objects.create_user("zoho", "zoho@example.com", "pw")
+        app = ClientApp.objects.create(slug="zoho", priority=10)
+        app.accounts.add(user)
+
+        self.assertEqual(client_app_from_rules(self.request(user=user)), "zoho")
+
+    def test_the_request_host_matches_subdomains(self):
+        ClientApp.objects.create(slug="elhuyar", domains="elhuyar.eus")
+
+        request = self.request(HTTP_ORIGIN="https://www.elhuyar.eus/tresnak")
+
+        self.assertEqual(client_app_from_rules(request), "elhuyar")
+
+    def test_the_client_network_matches(self):
+        ClientApp.objects.create(
+            slug="goiena_erp", ip_networks="10.0.0.0/8\n192.168.1.0/24"
+        )
+
+        self.assertEqual(
+            client_app_from_rules(self.request(REMOTE_ADDR="10.1.2.3")), "goiena_erp"
+        )
+
+    def test_the_user_agent_matches_for_anonymous_readers(self):
+        """The bulk of the traffic: readers on the native mobile apps."""
+        ClientApp.objects.create(slug="mugikorra", user_agent_patterns="TokikomApp")
+
+        request = self.request(HTTP_USER_AGENT="TokikomApp/2.1 (Android 15)")
+
+        self.assertEqual(client_app_from_rules(request), "mugikorra")
+
+    def test_everything_else_is_not_attributed(self):
+        ClientApp.objects.create(slug="mugikorra", user_agent_patterns="TokikomApp")
+
+        self.assertEqual(client_app_from_rules(self.request()), "")
+
+    def test_the_lowest_priority_wins(self):
+        ClientApp.objects.create(
+            slug="orokorra", user_agent_patterns="tokio", priority=100
+        )
+        ClientApp.objects.create(
+            slug="mugikorra", user_agent_patterns="tokio", priority=10
+        )
+
+        self.assertEqual(
+            client_app_from_rules(self.request(HTTP_USER_AGENT="tokio/1")), "mugikorra"
+        )
+
+    def test_inactive_applications_are_ignored(self):
+        ClientApp.objects.create(
+            slug="zaharra", user_agent_patterns="tokio", is_active=False
+        )
+
+        self.assertEqual(
+            client_app_from_rules(self.request(HTTP_USER_AGENT="tokio/1")), ""
+        )
+
+    def test_invalid_networks_are_skipped(self):
+        ClientApp.objects.create(slug="gaizki", ip_networks="not-a-network")
+
+        self.assertEqual(
+            client_app_from_rules(self.request(REMOTE_ADDR="10.1.2.3")), ""
+        )
+
+    def test_saving_a_rule_invalidates_the_cache(self):
+        self.assertEqual(client_app_from_rules(self.request()), "")
+
+        ClientApp.objects.create(slug="berria", domains="berria.eus")
+
+        request = self.request(HTTP_ORIGIN="https://berria.eus")
+        self.assertEqual(client_app_from_rules(request), "berria")
+
+    def test_middleware_stores_the_application_in_the_counters(self):
+        ClientApp.objects.create(slug="mugikorra", user_agent_patterns="TokikomApp")
+
+        self.client.get("/ping/", HTTP_USER_AGENT="TokikomApp/2.1")
+        flush()
+
+        self.assertEqual(EndpointStat.objects.get().client_app, "mugikorra")
+
+
+class ClientAppAdminTest(UsageTestCase):
+    def setUp(self):
+        super().setUp()
+        self.admin = User.objects.create_superuser("admin", "a@example.com", "pw")
+        self.client.force_login(self.admin)
+        self.endpoint = Endpoint.objects.create(
+            app_label="api", route_path="api/3.0/artikuluak/", method="GET"
+        )
+        self.attributed = EndpointStat.objects.create(
+            endpoint=self.endpoint,
+            date="2026-10-08",
+            client_app="mugikorra",
+            count=2,
+        )
+        self.unattributed = EndpointStat.objects.create(
+            endpoint=self.endpoint,
+            date="2026-10-08",
+            client_type="user",
+            client_app="",
+            count=5,
+        )
+
+    def rows(self, **params):
+        response = self.client.get(reverse(STAT_CHANGELIST), params)
+        self.assertEqual(response.status_code, 200)
+        return set(response.context["cl"].queryset)
+
+    def test_the_table_is_editable_in_the_admin(self):
+        app = ClientApp.objects.create(slug="mugikorra", name="Mugikorra")
+
+        response = self.client.get(
+            reverse("admin:django_api_usage_clientapp_change", args=[app.pk])
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "Matching rules")
+
+    def test_stats_can_be_filtered_by_application(self):
+        self.assertEqual(self.rows(client_app="mugikorra"), {self.attributed})
+
+    def test_stats_can_be_filtered_by_unattributed_calls(self):
+        self.assertEqual(self.rows(client_app="__none__"), {self.unattributed})
+
+    def test_applications_without_traffic_are_still_offered(self):
+        ClientApp.objects.create(slug="erp", name="ERP")
+
+        response = self.client.get(reverse(STAT_CHANGELIST))
+
+        self.assertContains(response, "?client_app=erp")
+        self.assertContains(response, ">ERP</a>")

{django_api_usage-0.1.6 → django_api_usage-0.1.7}/tests/test_csv_export.py

@@ -103,6 +103,7 @@ class CsvExportTest(UsageTestCase):
                 "method",
                 "site_id",
                 "client_type",
+                "client_app",
                 "status_class",
                 "count",
             ],
@@ -121,8 +122,9 @@ class CsvExportTest(UsageTestCase):
         self.assertEqual(body[3], "town-list")
         self.assertEqual(body[4], "GET")
         self.assertEqual(body[6], "anon")
-        self.assertEqual(body[7], "2xx")
-        self.assertEqual(body[8], "7")
+        self.assertEqual(body[7], "")
+        self.assertEqual(body[8], "2xx")
+        self.assertEqual(body[9], "7")
 
     def test_stats_export_only_includes_the_selected_rows(self):
         endpoint = self.make_endpoint()
@@ -133,7 +135,7 @@ class CsvExportTest(UsageTestCase):
 
         rows = self.rows(response)
         self.assertEqual(len(rows), 2)  # header + one row
-        self.assertEqual(rows[1][8], "1")
+        self.assertEqual(rows[1][9], "1")
 
     def test_stats_export_filename_contains_the_date(self):
         endpoint = self.make_endpoint()

{django_api_usage-0.1.6 → django_api_usage-0.1.7}/tests/test_filters.py

@@ -114,9 +114,11 @@ class FilterTest(UsageTestCase):
             self.assertIn("Aplikazioa", html)
             self.assertIn("Metodoa", html)
 
-    def test_total_count_label_is_left_untranslated(self):
-        """The label was requested verbatim, so the eu catalog keeps it English."""
+    def test_total_count_follows_the_active_language(self):
         with translation.override("eu"):
             html = self.client.get(reverse(STAT_CHANGELIST)).content.decode()
+            self.assertIn("GUZTIRA", html)
 
+        with translation.override("en"):
+            html = self.client.get(reverse(STAT_CHANGELIST)).content.decode()
             self.assertIn("TOTAL COUNT", html)

django_api_usage-0.1.6/src/django_api_usage/apps.py

@@ -1,11 +0,0 @@
-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