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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.3
+Version: 0.1.5
 Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
 Author-email: CodeSyntax <teknika@codesyntax.com>
 License-Expression: MIT
@@ -37,11 +37,11 @@ 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)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-api-usage?logo=pypi)
 ![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/codesyntax/django-api-usage/ci.yml?logo=github)
+![PyPI - Version](https://img.shields.io/pypi/v/django-api-usage?logo=pypi)
 
 # django-api-usage
 
@@ -120,6 +120,24 @@ API_USAGE = {
 }
 ```
 
+## Admin
+
+The package ships a read-only admin for the three models, built with plain
+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.
+* **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
+  page (endpoints and their deprecation metadata are kept).
+* **Export selected rows to CSV** on all three admins. Relations are flattened
+  into one analysis-friendly table (a stat row carries its endpoint's path, app
+  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.
+
 ## Deprecation lifecycle
 
 `Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the

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

@@ -1,8 +1,8 @@
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-api-usage)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-api-usage?logo=pypi)
 ![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/codesyntax/django-api-usage/ci.yml?logo=github)
+![PyPI - Version](https://img.shields.io/pypi/v/django-api-usage?logo=pypi)
 
 # django-api-usage
 
@@ -81,6 +81,24 @@ API_USAGE = {
 }
 ```
 
+## Admin
+
+The package ships a read-only admin for the three models, built with plain
+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.
+* **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
+  page (endpoints and their deprecation metadata are kept).
+* **Export selected rows to CSV** on all three admins. Relations are flattened
+  into one analysis-friendly table (a stat row carries its endpoint's path, app
+  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.
+
 ## Deprecation lifecycle
 
 `Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-api-usage"
-version = "0.1.3"
+version = "0.1.5"
 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.3 → django_api_usage-0.1.5}/src/django_api_usage/__init__.py

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

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

@@ -6,14 +6,21 @@
   deprecation metadata) are kept on purpose.
 
 The changelist also shows the **sum of the ``count`` column** for the rows that
-match the current filters.
+match the current filters, and every admin ships an **export to CSV** action for
+the selected rows (all the rows matching the filters can be selected with the
+"select all" link).
+
+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.http import HttpResponseRedirect
+from django.http import HttpResponse, HttpResponseRedirect
 from django.template.response import TemplateResponse
 from django.urls import path, reverse
+from django.utils import timezone
 from django.utils.text import format_lazy
 from django.utils.translation import gettext_lazy as _
 
@@ -21,8 +28,53 @@ from .buffers import flush
 from .models import Consumer, Endpoint, EndpointStat
 
 
+class CsvExportMixin:
+    """Admin action to download the selected rows as CSV.
+
+    ``csv_columns`` is an iterable of ``(header, queryset lookup)`` pairs. The
+    lookups are resolved by the database in a single query, so related rows can
+    be flattened into one analysis-friendly table (for example a stat row plus
+    its endpoint's path and app label).
+    """
+
+    #: ``(header, lookup)`` pairs. The header is written as-is (keep it stable
+    #: and ASCII: the file is meant to be read by pandas or a spreadsheet).
+    csv_columns = ()
+    #: Prefix of the downloaded filename; the date is appended.
+    csv_filename_prefix = "django-api-usage"
+
+    @admin.action(description=_("Export selected rows to CSV"))
+    def export_as_csv(self, request, queryset):
+        columns = list(self.csv_columns)
+        rows = queryset.values_list(*(lookup for _, lookup in columns))
+
+        filename = f"{self.csv_filename_prefix}-{timezone.localdate():%Y-%m-%d}.csv"
+        response = HttpResponse(content_type="text/csv; charset=utf-8")
+        response["Content-Disposition"] = f'attachment; filename="{filename}"'
+        # Byte order mark, so Excel detects UTF-8 (content may be Basque).
+        response.write("\ufeff")
+
+        writer = csv.writer(response)
+        writer.writerow([header for header, _ in columns])
+        writer.writerows(rows)
+        return response
+
+
 @admin.register(Endpoint)
-class EndpointAdmin(admin.ModelAdmin):
+class EndpointAdmin(CsvExportMixin, admin.ModelAdmin):
+    actions = ("export_as_csv",)
+    csv_columns = (
+        ("app_label", "app_label"),
+        ("route_path", "route_path"),
+        ("route_name", "route_name"),
+        ("method", "method"),
+        ("site_id", "site_id"),
+        ("deprecated", "deprecated"),
+        ("sunset_date", "sunset_date"),
+        ("replacement", "replacement"),
+        ("owner", "owner"),
+        ("notes", "notes"),
+    )
     list_display = (
         "app_label",
         "route_path",
@@ -40,7 +92,21 @@ class EndpointAdmin(admin.ModelAdmin):
 
 
 @admin.register(EndpointStat)
-class EndpointStatAdmin(admin.ModelAdmin):
+class EndpointStatAdmin(CsvExportMixin, admin.ModelAdmin):
+    actions = ("export_as_csv",)
+    # Flattened on purpose: the CSV is meant for analysis (pandas, spreadsheet)
+    # without having to join endpoints by hand.
+    csv_columns = (
+        ("date", "date"),
+        ("app_label", "endpoint__app_label"),
+        ("route_path", "endpoint__route_path"),
+        ("route_name", "endpoint__route_name"),
+        ("method", "endpoint__method"),
+        ("site_id", "endpoint__site_id"),
+        ("client_type", "client_type"),
+        ("status_class", "status_class"),
+        ("count", "count"),
+    )
     list_display = ("date", "endpoint", "client_type", "status_class", "count")
     list_filter = ("date", "client_type", "status_class")
     list_select_related = ("endpoint",)
@@ -147,7 +213,18 @@ class EndpointStatAdmin(admin.ModelAdmin):
 
 
 @admin.register(Consumer)
-class ConsumerAdmin(admin.ModelAdmin):
+class ConsumerAdmin(CsvExportMixin, admin.ModelAdmin):
+    actions = ("export_as_csv",)
+    csv_columns = (
+        ("kind", "kind"),
+        ("ref_hash", "ref_hash"),
+        ("user_agent_family", "user_agent_family"),
+        ("request_count", "request_count"),
+        ("first_seen", "first_seen"),
+        ("last_seen", "last_seen"),
+        ("contact", "contact"),
+        ("notes", "notes"),
+    )
     list_display = (
         "kind",
         "ref_short",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-api-usage
-Version: 0.1.3
+Version: 0.1.5
 Summary: Lightweight, privacy-first usage metering for Django APIs, with an optional deprecation lifecycle layer.
 Author-email: CodeSyntax <teknika@codesyntax.com>
 License-Expression: MIT
@@ -37,11 +37,11 @@ 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)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-api-usage?logo=pypi)
 ![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)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/codesyntax/django-api-usage/ci.yml?logo=github)
+![PyPI - Version](https://img.shields.io/pypi/v/django-api-usage?logo=pypi)
 
 # django-api-usage
 
@@ -120,6 +120,24 @@ API_USAGE = {
 }
 ```
 
+## Admin
+
+The package ships a read-only admin for the three models, built with plain
+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.
+* **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
+  page (endpoints and their deprecation metadata are kept).
+* **Export selected rows to CSV** on all three admins. Relations are flattened
+  into one analysis-friendly table (a stat row carries its endpoint's path, app
+  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.
+
 ## Deprecation lifecycle
 
 `Endpoint` carries `deprecated`, `sunset_date`, `replacement` and `owner`, so the

{django_api_usage-0.1.3 → django_api_usage-0.1.5}/src/django_api_usage.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/django_api_usage/templates/admin/django_api_usage/endpointstat/confirm_clear
 tests/test_admin.py
 tests/test_checks.py
 tests/test_commands.py
+tests/test_csv_export.py
 tests/test_drf.py
 tests/test_middleware.py
 tests/test_models.py

django_api_usage-0.1.5/tests/test_csv_export.py

@@ -0,0 +1,209 @@
+"""Tests for the "export selected rows to CSV" admin action."""
+
+import csv
+import io
+
+from django.contrib.auth.models import User
+from django.urls import reverse
+
+from django_api_usage.models import Consumer, Endpoint, EndpointStat
+
+from .base import UsageTestCase
+
+ENDPOINT_CHANGELIST = "admin:django_api_usage_endpoint_changelist"
+STAT_CHANGELIST = "admin:django_api_usage_endpointstat_changelist"
+CONSUMER_CHANGELIST = "admin:django_api_usage_consumer_changelist"
+
+BOM = b"\xef\xbb\xbf"
+
+
+class CsvExportTest(UsageTestCase):
+    def setUp(self):
+        super().setUp()
+        self.admin = User.objects.create_superuser("admin", "a@example.com", "pw")
+        self.client.force_login(self.admin)
+
+    # -- helpers ------------------------------------------------------------
+
+    def export(self, changelist, objects, action="export_as_csv"):
+        return self.client.post(
+            reverse(changelist),
+            {
+                "action": action,
+                "select_across": "0",
+                "index": "0",
+                "_selected_action": [str(obj.pk) for obj in objects],
+            },
+        )
+
+    def rows(self, response):
+        """Return the CSV as a list of rows (BOM stripped)."""
+        content = response.content.decode("utf-8-sig")
+        return list(csv.reader(io.StringIO(content)))
+
+    def make_endpoint(self, route_path="api/3.0/herriak/", app_label="api"):
+        return Endpoint.objects.create(
+            app_label=app_label,
+            route_path=route_path,
+            route_name="town-list",
+            method="GET",
+        )
+
+    def make_stat(self, endpoint, count=1, client_type="anon"):
+        return EndpointStat.objects.create(
+            endpoint=endpoint,
+            date="2026-10-08",
+            client_type=client_type,
+            status_class="2xx",
+            count=count,
+        )
+
+    def assert_csv_response(self, response):
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response["Content-Type"], "text/csv; charset=utf-8")
+        self.assertIn("attachment;", response["Content-Disposition"])
+        self.assertIn(".csv", response["Content-Disposition"])
+        # The BOM makes Excel detect UTF-8.
+        self.assertTrue(response.content.startswith(BOM))
+
+    # -- action availability ------------------------------------------------
+
+    def test_action_is_offered_in_the_changelist(self):
+        endpoint = self.make_endpoint()
+        self.make_stat(endpoint)
+
+        response = self.client.get(reverse(STAT_CHANGELIST))
+
+        self.assertContains(response, "Export selected rows to CSV")
+        self.assertContains(response, 'value="export_as_csv"')
+
+    def test_delete_selected_is_still_available(self):
+        self.make_endpoint()
+
+        changelist = self.client.get(reverse(ENDPOINT_CHANGELIST))
+
+        self.assertContains(changelist, "delete_selected")
+
+    # -- stats export -------------------------------------------------------
+
+    def test_stats_export_header_is_stable(self):
+        endpoint = self.make_endpoint()
+        stat = self.make_stat(endpoint)
+
+        response = self.export(STAT_CHANGELIST, [stat])
+
+        self.assert_csv_response(response)
+        self.assertEqual(
+            self.rows(response)[0],
+            [
+                "date",
+                "app_label",
+                "route_path",
+                "route_name",
+                "method",
+                "site_id",
+                "client_type",
+                "status_class",
+                "count",
+            ],
+        )
+
+    def test_stats_export_flattens_the_endpoint(self):
+        endpoint = self.make_endpoint(route_path="^api/3.0/herriak/$")
+        stat = self.make_stat(endpoint, count=7)
+
+        response = self.export(STAT_CHANGELIST, [stat])
+
+        body = self.rows(response)[1]
+        self.assertEqual(body[0], "2026-10-08")
+        self.assertEqual(body[1], "api")
+        self.assertEqual(body[2], "^api/3.0/herriak/$")
+        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")
+
+    def test_stats_export_only_includes_the_selected_rows(self):
+        endpoint = self.make_endpoint()
+        selected = self.make_stat(endpoint, count=1)
+        self.make_stat(endpoint, count=99, client_type="user")
+
+        response = self.export(STAT_CHANGELIST, [selected])
+
+        rows = self.rows(response)
+        self.assertEqual(len(rows), 2)  # header + one row
+        self.assertEqual(rows[1][8], "1")
+
+    def test_stats_export_filename_contains_the_date(self):
+        endpoint = self.make_endpoint()
+        stat = self.make_stat(endpoint)
+
+        response = self.export(STAT_CHANGELIST, [stat])
+
+        self.assertIn('filename="django-api-usage-', response["Content-Disposition"])
+
+    # -- endpoints and consumers export -------------------------------------
+
+    def test_endpoints_export(self):
+        endpoint = self.make_endpoint()
+        Endpoint.objects.filter(pk=endpoint.pk).update(
+            deprecated=True, replacement="api/4.0/herriak/"
+        )
+
+        response = self.export(ENDPOINT_CHANGELIST, [endpoint])
+
+        self.assert_csv_response(response)
+        rows = self.rows(response)
+        self.assertIn("deprecated", rows[0])
+        self.assertIn("replacement", rows[0])
+        self.assertIn("True", rows[1])
+        self.assertIn("api/4.0/herriak/", rows[1])
+
+    def test_consumers_export(self):
+        consumer = Consumer.objects.create(
+            kind="ip_hash",
+            ref_hash="a" * 64,
+            user_agent_family="firefox",
+            request_count=12,
+        )
+
+        response = self.export(CONSUMER_CHANGELIST, [consumer])
+
+        self.assert_csv_response(response)
+        rows = self.rows(response)
+        self.assertEqual(rows[0][0], "kind")
+        self.assertEqual(rows[0][1], "ref_hash")
+        self.assertEqual(rows[1][0], "ip_hash")
+        self.assertEqual(rows[1][1], "a" * 64)
+
+    # -- edge cases ---------------------------------------------------------
+
+    def test_export_without_selection_is_not_a_csv(self):
+        """Django warns and redirects instead of downloading an empty file."""
+        response = self.client.post(
+            reverse(STAT_CHANGELIST),
+            {"action": "export_as_csv", "select_across": "0", "index": "0"},
+        )
+
+        self.assertEqual(response.status_code, 302)
+        self.assertNotEqual(response.get("Content-Type"), "text/csv; charset=utf-8")
+
+    def test_export_all_matching_rows_with_select_across(self):
+        """One checked row + "select all" exports every row matching the filters."""
+        endpoint = self.make_endpoint()
+        first = self.make_stat(endpoint, count=1)
+        self.make_stat(endpoint, count=2, client_type="user")
+
+        response = self.client.post(
+            reverse(STAT_CHANGELIST),
+            {
+                "action": "export_as_csv",
+                "select_across": "1",
+                "index": "0",
+                "_selected_action": [str(first.pk)],
+            },
+        )
+
+        self.assert_csv_response(response)
+        self.assertEqual(len(self.rows(response)), 3)  # header + two rows