django-api-usage 0.1.0__tar.gz → 0.1.2__tar.gz

{django_api_usage-0.1.0/src/django_api_usage.egg-info → django_api_usage-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
 Author-email: CodeSyntax <teknika@codesyntax.com>
 License-Expression: MIT

{django_api_usage-0.1.0 → django_api_usage-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-api-usage"
-version = "0.1.0"
+version = "0.1.2"
 description = "Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer."
 readme = "README.md"
 license = "MIT"
@@ -41,6 +41,9 @@ Issues = "https://github.com/codesyntax/django-api-usage/issues"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+django_api_usage = ["templates/admin/django_api_usage/endpointstat/*.html"]
+
 [tool.black]
 line-length = 88
 target-version = ["py310"]

{django_api_usage-0.1.0 → django_api_usage-0.1.2}/src/django_api_usage/__init__.py

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

django_api_usage-0.1.2/src/django_api_usage/admin.py

@@ -0,0 +1,164 @@
+"""Read-only admin for usage counters, with two maintenance buttons.
+
+* **Flush now** moves counters buffered in the cache to the database, so they
+  show up here immediately when ``BUFFER_BACKEND = "cache"``.
+* **Clear statistics** empties the aggregated counters. Endpoints (and their
+  deprecation metadata) are kept on purpose.
+
+The changelist also shows the **sum of the ``count`` column** for the rows that
+match the current filters.
+"""
+
+from django.contrib import admin, messages
+from django.db.models import Sum
+from django.http import HttpResponseRedirect
+from django.template.response import TemplateResponse
+from django.urls import path, reverse
+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
+
+
+@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"
+    # Search across the related endpoint (case-insensitive "contains").
+    search_fields = (
+        "endpoint__route_name",
+        "endpoint__app_label",
+        "endpoint__method",
+        "endpoint__replacement",
+    )
+    search_help_text = _(
+        "Search by endpoint route, app, method or replacement (for example "
+        "'artikuluak' or 'gida')."
+    )
+    change_list_template = "admin/django_api_usage/endpointstat/change_list.html"
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    # -- changelist total ---------------------------------------------------
+
+    def changelist_view(self, request, extra_context=None):
+        """Add the sum of ``count`` over the *filtered* queryset to the context."""
+        response = super().changelist_view(request, extra_context=extra_context)
+        try:
+            changelist = response.context_data["cl"]
+        except (AttributeError, KeyError):
+            return response
+        response.context_data["usage_total"] = (
+            changelist.queryset.aggregate(total=Sum("count"))["total"] or 0
+        )
+        return response
+
+    # -- custom maintenance views -------------------------------------------
+
+    def get_urls(self):
+        app_label, model_name = self.opts.app_label, self.opts.model_name
+        custom = [
+            path(
+                "flush/",
+                self.admin_site.admin_view(self.flush_view),
+                name=f"{app_label}_{model_name}_flush",
+            ),
+            path(
+                "clear/",
+                self.admin_site.admin_view(self.clear_view),
+                name=f"{app_label}_{model_name}_clear",
+            ),
+        ]
+        return custom + super().get_urls()
+
+    def _changelist_url(self):
+        app_label, model_name = self.opts.app_label, self.opts.model_name
+        return reverse(f"admin:{app_label}_{model_name}_changelist")
+
+    def flush_view(self, request):
+        """Move buffered counters from the cache into the database."""
+        if request.method != "POST":
+            return HttpResponseRedirect(self._changelist_url())
+        written = flush()
+        if written:
+            self.message_user(
+                request,
+                format_lazy(_("Flushed {count} buffered counter(s)."), count=written),
+                messages.SUCCESS,
+            )
+        else:
+            self.message_user(
+                request,
+                _(
+                    "Nothing was buffered: with BUFFER_BACKEND='db' counters are "
+                    "already in the database."
+                ),
+                messages.INFO,
+            )
+        return HttpResponseRedirect(self._changelist_url())
+
+    def clear_view(self, request):
+        """Empty the aggregated counters (a confirmation page is shown first)."""
+        if request.method != "POST":
+            context = {
+                **self.admin_site.each_context(request),
+                "title": _("Clear statistics"),
+                "opts": self.opts,
+                "total": EndpointStat.objects.count(),
+            }
+            return TemplateResponse(
+                request,
+                "admin/django_api_usage/endpointstat/confirm_clear.html",
+                context,
+            )
+        deleted = EndpointStat.objects.all().delete()[0]
+        self.message_user(
+            request,
+            format_lazy(_("Deleted {count} statistic row(s)."), count=deleted),
+            messages.SUCCESS,
+        )
+        return HttpResponseRedirect(self._changelist_url())
+
+
+@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.2/src/django_api_usage/templates/admin/django_api_usage/endpointstat/change_list.html

@@ -0,0 +1,24 @@
+{% extends "admin/change_list.html" %}
+{% load i18n %}
+
+{% block object-tools-items %}
+  <li>
+    <form method="post" action="{% url 'admin:django_api_usage_endpointstat_flush' %}">
+      {% csrf_token %}
+      <button type="submit" class="button">{% translate "Flush now" %}</button>
+    </form>
+  </li>
+  <li>
+    <a href="{% url 'admin:django_api_usage_endpointstat_clear' %}" class="button">{% translate "Clear statistics" %}</a>
+  </li>
+  {{ block.super }}
+{% endblock %}
+
+{% block result_list %}
+  {{ block.super }}
+  {% if usage_total is not None %}
+    <p class="help" style="text-align: right; padding: 0.5em 1em; font-weight: bold;">
+      {% blocktranslate with total=usage_total %}TOTAL COUNT: {{ total }}{% endblocktranslate %}
+    </p>
+  {% endif %}
+{% endblock %}

django_api_usage-0.1.2/src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear.html

@@ -0,0 +1,27 @@
+{% extends "admin/base_site.html" %}
+{% load i18n %}
+
+{% block breadcrumbs %}
+  <div class="breadcrumbs">
+    <a href="{% url 'admin:index' %}">{% translate "Home" %}</a>
+    &rsaquo; <a href="{% url 'admin:django_api_usage_endpointstat_changelist' %}">{% translate "Endpoint stats" %}</a>
+    &rsaquo; {% translate "Clear statistics" %}
+  </div>
+{% endblock %}
+
+{% block content %}
+  <p>
+    {% blocktranslate count counter=total %}
+      This will delete the only aggregated statistic row. Endpoints and their
+      deprecation metadata are kept.
+    {% plural %}
+      This will delete all {{ counter }} aggregated statistic rows. Endpoints
+      and their deprecation metadata are kept.
+    {% endblocktranslate %}
+  </p>
+  <form method="post">
+    {% csrf_token %}
+    <input type="submit" value="{% translate 'Yes, clear statistics' %}">
+    <a href="{% url 'admin:django_api_usage_endpointstat_changelist' %}">{% translate "Cancel" %}</a>
+  </form>
+{% endblock %}

{django_api_usage-0.1.0 → django_api_usage-0.1.2/src/django_api_usage.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
 Author-email: CodeSyntax <teknika@codesyntax.com>
 License-Expression: MIT

{django_api_usage-0.1.0 → django_api_usage-0.1.2}/src/django_api_usage.egg-info/SOURCES.txt

@@ -25,6 +25,9 @@ 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/__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_commands.py
 tests/test_drf.py

django_api_usage-0.1.2/tests/test_admin.py

@@ -0,0 +1,172 @@
+from django.contrib.auth.models import User
+from django.urls import reverse
+
+from django_api_usage.models import Endpoint, EndpointStat
+
+from .base import UsageTestCase
+
+CHANGELIST = "admin:django_api_usage_endpointstat_changelist"
+FLUSH_URL = "admin:django_api_usage_endpointstat_flush"
+CLEAR_URL = "admin:django_api_usage_endpointstat_clear"
+
+
+class AdminButtonsTest(UsageTestCase):
+    def setUp(self):
+        super().setUp()
+        self.admin = User.objects.create_superuser(
+            "admin", "admin@example.com", "password"
+        )
+        self.client.force_login(self.admin)
+
+    def _make_stat(self, count=1):
+        endpoint = Endpoint.objects.create(
+            app_label="api", route_name="artikuluak-list", method="GET"
+        )
+        return EndpointStat.objects.create(
+            endpoint=endpoint, date="2026-10-08", count=count
+        )
+
+    def test_buttons_are_rendered(self):
+        response = self.client.get(reverse(CHANGELIST))
+
+        self.assertEqual(response.status_code, 200)
+        content = response.content.decode()
+        self.assertIn(reverse(FLUSH_URL), content)
+        self.assertIn(reverse(CLEAR_URL), content)
+
+    def test_flush_reports_when_nothing_is_buffered(self):
+        response = self.client.post(reverse(FLUSH_URL), follow=True)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "already in the database")
+
+    def test_flush_moves_buffered_counters_to_the_database(self):
+        # A request fills the cache buffer.
+        self.client.get("/ping/")
+        self.assertFalse(EndpointStat.objects.exists())
+
+        response = self.client.post(reverse(FLUSH_URL), follow=True)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(
+            EndpointStat.objects.filter(endpoint__route_name="ping").exists()
+        )
+
+    def test_flush_rejects_get(self):
+        response = self.client.get(reverse(FLUSH_URL))
+
+        self.assertRedirects(response, reverse(CHANGELIST))
+
+    def test_clear_asks_for_confirmation_first(self):
+        self._make_stat()
+
+        response = self.client.get(reverse(CLEAR_URL))
+
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(EndpointStat.objects.exists())
+
+    def test_clear_deletes_statistics_but_keeps_endpoints(self):
+        self._make_stat()
+
+        response = self.client.post(reverse(CLEAR_URL), follow=True)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(EndpointStat.objects.exists())
+        self.assertTrue(Endpoint.objects.exists())
+
+    def test_total_sums_the_count_column(self):
+        api = Endpoint.objects.create(app_label="api", route_name="a", method="GET")
+        gida = Endpoint.objects.create(app_label="gida", route_name="b", method="GET")
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="anon", count=5
+        )
+        EndpointStat.objects.create(
+            endpoint=gida, date="2026-10-08", client_type="user", count=7
+        )
+
+        response = self.client.get(reverse(CHANGELIST))
+
+        self.assertEqual(response.context_data["usage_total"], 12)
+        self.assertContains(response, "TOTAL COUNT")
+
+    def test_total_respects_the_selected_filters(self):
+        api = Endpoint.objects.create(app_label="api", route_name="a", method="GET")
+        gida = Endpoint.objects.create(app_label="gida", route_name="b", method="GET")
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="anon", count=5
+        )
+        EndpointStat.objects.create(
+            endpoint=gida, date="2026-10-08", client_type="user", count=7
+        )
+
+        response = self.client.get(reverse(CHANGELIST), {"client_type": "user"})
+
+        self.assertEqual(response.context_data["usage_total"], 7)
+
+    def test_search_box_is_rendered(self):
+        response = self.client.get(reverse(CHANGELIST))
+
+        self.assertContains(response, 'id="searchbar"')
+
+    def test_search_filters_rows_by_endpoint_text(self):
+        api = Endpoint.objects.create(
+            app_label="api", route_name="artikuluak-list", method="GET"
+        )
+        gida = Endpoint.objects.create(
+            app_label="gida", route_name="gida-sailak-list", method="GET"
+        )
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="anon", count=5
+        )
+        EndpointStat.objects.create(
+            endpoint=gida, date="2026-10-08", client_type="anon", count=7
+        )
+
+        response = self.client.get(reverse(CHANGELIST), {"q": "artikuluak"})
+
+        self.assertEqual(response.context_data["usage_total"], 5)
+        self.assertEqual(len(response.context_data["cl"].result_list), 1)
+
+    def test_search_matches_the_app_label(self):
+        api = Endpoint.objects.create(
+            app_label="api", route_name="artikuluak-list", method="GET"
+        )
+        gida = Endpoint.objects.create(
+            app_label="gida", route_name="gida-sailak-list", method="GET"
+        )
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="anon", count=5
+        )
+        EndpointStat.objects.create(
+            endpoint=gida, date="2026-10-08", client_type="anon", count=7
+        )
+
+        response = self.client.get(reverse(CHANGELIST), {"q": "gida"})
+
+        self.assertEqual(response.context_data["usage_total"], 7)
+
+    def test_search_combines_with_list_filters(self):
+        api = Endpoint.objects.create(
+            app_label="api", route_name="artikuluak-list", method="GET"
+        )
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="anon", count=5
+        )
+        EndpointStat.objects.create(
+            endpoint=api, date="2026-10-08", client_type="user", count=3
+        )
+
+        response = self.client.get(
+            reverse(CHANGELIST), {"q": "artikuluak", "client_type": "user"}
+        )
+
+        self.assertEqual(response.context_data["usage_total"], 3)
+
+    def test_clear_is_not_available_without_admin_permission(self):
+        self._make_stat()
+        self.client.force_login(User.objects.create_user("plain", password="x"))
+
+        response = self.client.post(reverse(CLEAR_URL))
+
+        self.assertIn(response.status_code, (302, 403))
+        self.assertTrue(EndpointStat.objects.exists())

django_api_usage-0.1.0/src/django_api_usage/admin.py

@@ -1,56 +0,0 @@
-"""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]