django-admin-select-filter 0.1.0__tar.gz

django_admin_select_filter-0.1.0/.github/workflows/js-tests.yml

@@ -0,0 +1,24 @@
+name: JavaScript Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Tests & Coverage
+        run: npm run coverage:js

django_admin_select_filter-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,31 @@
+name: Python and Playwright Tests
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test-python:
+    name: Python Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Playwright browsers
+        run: uv run playwright install --with-deps chromium
+
+      - name: Run Pytest
+        run: uv run pytest

django_admin_select_filter-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Show project version
+        run: |
+          grep "version" pyproject.toml
+
+      - name: Build release distributions
+        run: |
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+      contents: read
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/django-admin-select-filter/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

django_admin_select_filter-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.sqlite3
+.DS_Store
+
+node_modules/
+coverage/

django_admin_select_filter-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,59 @@
+default_language_version:
+  python: &python-version python3.14
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-json
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-toml
+  - id: debug-statements
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+
+- repo: https://github.com/biomejs/pre-commit
+  rev: d1ce4972fb5ad09afd33b432bca71e8c5dfbb2b5  # frozen: v2.5.6
+  hooks:
+  - id: biome-check
+    additional_dependencies:
+    - '@biomejs/biome@2.3.8'
+    language_version: default
+
+- repo: https://github.com/adamchainz/django-upgrade
+  rev: bdcc9646c249f00ec9781751791e7b75b48b3722  # frozen: 1.31.1
+  hooks:
+  - id: django-upgrade
+    args: [--target-version, "4.2"]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: 39d9ac5938dadb73df0564a45f163e25ff9fa6e2  # frozen: v0.16.1
+  hooks:
+  - id: ruff-check
+    args: [--fix]
+  - id: ruff-format
+
+- repo: local
+  hooks:
+  - id: mypy
+    name: mypy
+    entry: mypy
+    language: system
+    types: [python]
+    files: ^src/
+    pass_filenames: false
+    args: [src/django_admin_select_filter]
+
+- repo: https://github.com/adamchainz/djade-pre-commit
+  rev: 52a7ce253113456c2a1113186a4a19b15c8b68af  # frozen: 1.9.0
+  hooks:
+  - id: djade
+    files: '(/|^)templates/'
+
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: d600c142bb19f521ae6a6a345f94a2efd7937759  # frozen: v2.26.0
+  hooks:
+  - id: pyproject-fmt

django_admin_select_filter-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## Unreleased
+
+- Initial project structure: `BaseSelectFilter`,`ForeignKeyFilter`, async
+  options view/URL, Select2 filter template, and test scaffolding.
+- Extracted shared filter logic into `BaseSelectFilter` and added `ChoiceFilter`,
+  a general-purpose Select2 filter for scalar fields (e.g. `ChoiceField`) or
+  explicit `(value, label)` options, not tied to a related model.
+- `ForeignKeyFilter.model` is now optional: when unset, it's inferred by
+  walking `parameter_name` across the admin model's relations, including a
+  nested lookup like `"publisher__country"`.
+- Extracted that relation-walking into `BaseSelectFilter._resolve_field`, so
+  `ChoiceFilter` also supports a nested `parameter_name` (e.g.
+  `"author__status"`) when deriving options from field `choices`.
+- Moved the Select2 filter template out of the generic `admin/filters/` path
+  into `admin_select_filter/filters/`, namespaced under the app's own label
+  (matching the existing static files and URL namespace) instead of a path
+  other packages could collide with. Split it into a
+  `base.html` with the shared markup and blocks, and a
+  `foreign_key_filter.html`/`choice_filter.html` pair that each extend it —
+  `ForeignKeyFilter` and `ChoiceFilter` now set their own `template`.
+- Added `BaseSelectFilter.multiple`: both filters can now select several
+  values at once, filtering with an `__in` lookup (combined with the null
+  lookup when the null option is also selected). Selected values are joined
+  in the query string via `multiple_separator`. The Select2 widget switches
+  to its native multi-select mode and the JS waits for the dropdown to close
+  before navigating, instead of navigating on every single selection.
+- `BaseSelectFilter`, `ForeignKeyFilter` and `ChoiceFilter` are now importable
+  directly from `django_admin_select_filter` (e.g.
+  `from django_admin_select_filter import ForeignKeyFilter`), not just from
+  `django_admin_select_filter.filters`.
+- Fixed `Select2FilterOptionsView` returning 404 when the target model was
+  registered on a project's own `AdminSite` instead of the default
+  `django.contrib.admin.site`. It now checks every registered `AdminSite`.
+- Added `BaseSelectFilter.searchable`: set to `False` to hide Select2's
+  search input and get a plain dropdown, for a short static option list.
+- Fixed dark-mode styling for `multiple = True`: the CSS only targeted
+  Select2's single-selection markup, leaving the multi-select chips unstyled.
+- Replaced `django_admin_select_filter.urls`'s plain `urlpatterns` list with
+  `django_admin_select_filter_path()`, a function projects drop straight
+  into their own `urlpatterns` — no `include()` needed. It still namespaces
+  the route as `admin_select_filter:options` internally via `include()`, and
+  accepts `route` (defaults to `"django_admin_select_filter/options/"`),
+  `view`, `name` and `as_view_kwargs` to customize it.
+- Added `BaseSelectFilter.async_call_url`: the JS now reads the async
+  endpoint from this per-filter attribute. Left unset (the default), it
+  resolves via `reverse("admin_select_filter:options")` at request time, so
+  it's always correct regardless of the admin page it's rendered on and
+  wherever that urlconf is mounted (a bare relative path there would resolve
+  against the *current page*, not that mount point, and silently hit the
+  wrong URL). Set it explicitly on a filter to point it at a custom view — or
+  to match a custom `name=` passed to `django_admin_select_filter_path()`,
+  which filters otherwise have no way to discover.
+- Added `Select2FilterOptionsView.use_registry`: enabled via
+  `as_view_kwargs={"use_registry": True}`, it resolves the matching filter
+  from a `{site: {app_label: {model_name: {parameter_name: filter}}}}` map
+  built once and cached for the process's lifetime, instead of calling
+  `get_list_filter()` on every registered `ModelAdmin` on every request.
+- Added `field_list_filter()`, adapting `ForeignKeyFilter`/`ChoiceFilter` for
+  `list_filter`'s `(field_name, filter_class)` tuple shorthand so the same
+  class can be reused across fields without a dedicated subclass per field —
+  `parameter_name` (and, for `ForeignKeyFilter`, `model`) is inferred from
+  the field. Only supports `async_call = False`; it raises `TypeError`
+  immediately for a filter with `async_call = True`.

django_admin_select_filter-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Development setup
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv sync
+uv run playwright install --with-deps chromium
+npm install
+uv run pytest
+uv run pre-commit install
+```
+
+`uv sync`/`uv run` install the `dev` and `test` dependency groups by default
+(`[tool.uv] default-groups` in `pyproject.toml`) — no `--extra` flags needed.
+
+Without uv:
+
+```bash
+pip install -e ".[test,dev]"
+playwright install --with-deps chromium
+npm install
+pytest
+pre-commit install
+```
+
+## Tests
+
+`tests/e2e/` drives a real Django admin page in a headless browser
+(pytest-playwright) to check the Select2 widget actually renders and works —
+both the synchronous dropdown and the asynchronous one, which exercises the
+JS → `fetch` → view → DB round trip for real. It needs a browser installed
+once via `playwright install`.
+
+`pre-commit` runs ruff, mypy, django-upgrade, djade (template linting),
+pyproject-fmt, biome and vitest (for the bundled JS/CSS). The `mypy` hook
+runs against the project's own environment rather than an isolated one,
+since `django-stubs` needs the package importable to resolve model/queryset
+types — with uv, `uv run pre-commit run --all-files` picks up `.venv/bin`
+automatically; without it, activate the venv first (or prefix commands with
+its `bin/`).
+
+### Coverage
+
+`pytest` always runs with coverage on (`--cov`, see `[tool.pytest]` /
+`[tool.coverage]` in `pyproject.toml`) and prints a terminal report. For the
+bundled JS:
+
+```bash
+npm run coverage:js
+```

django_admin_select_filter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodolfo Becerra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_admin_select_filter-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.5
+Name: django-admin-select-filter
+Version: 0.1.0
+Summary: Select2-powered admin list filters for Django, including an async foreign-key filter.
+Project-URL: Homepage, https://github.com/rodolvbg/django-admin-select-filter
+Project-URL: Repository, https://github.com/rodolvbg/django-admin-select-filter
+Author: Rodolfo Becerra
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: django-stubs>=5; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: inline-snapshot-django>=1.1; extra == 'test'
+Requires-Dist: inline-snapshot>=0.20.10; extra == 'test'
+Requires-Dist: playwright>=1.62; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest-django>=4.8; extra == 'test'
+Requires-Dist: pytest-playwright>=0.9; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# django-admin-select-filter
+
+Select2-powered admin list filters for Django.
+
+![Select2 filters in the admin sidebar](docs/screenshots/hero.png)
+
+## Install
+
+```bash
+pip install django-admin-select-filter
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_admin_select_filter",
+]
+```
+
+## Usage
+
+### `ChoiceFilter`
+
+The main filter: it works on any field with discrete values — a
+`choices`-backed `CharField`/`IntegerField`, a `BooleanField`, or an explicit
+`options` list you provide yourself:
+
+```python
+from django.contrib import admin
+from django_admin_select_filter import ChoiceFilter
+
+from myapp.models import Book
+
+
+class GenreFilter(ChoiceFilter):
+    parameter_name = "genre"  # reads Book.genre.choices
+
+
+class StatusFilter(ChoiceFilter):
+    parameter_name = "status"
+    options = [("draft", "Draft"), ("published", "Published")]
+
+
+@admin.register(Book)
+class BookAdmin(admin.ModelAdmin):
+    list_filter = [GenreFilter, StatusFilter]
+```
+
+![ChoiceFilter dropdown open, listing Fiction/Non-fiction](docs/screenshots/choice-filter.png)
+
+Since `options` accepts any explicit `(value, label)` list, `ChoiceFilter`
+can even filter a `ForeignKey` — pass one pair per related row:
+
+```python
+class AuthorChoiceFilter(ChoiceFilter):
+    parameter_name = "author"
+    options = [(author.pk, str(author)) for author in Author.objects.all()]
+```
+
+This isn't optimal, though: `options` is evaluated once, when the class body
+runs (at import time), so it goes stale as rows are added or renamed —
+there's no live query, search, or async loading behind it. For a real
+`ForeignKey`, use `ForeignKeyFilter` below instead.
+
+### `ForeignKeyFilter`
+
+Built specifically for `ForeignKey`/`ManyToManyField`s: it queries the
+related model live, supports searching through the related model's own
+`ModelAdmin.search_fields`, and can defer loading options until the widget
+is opened (see `async_call` further down).
+
+```python
+from django_admin_select_filter import ForeignKeyFilter
+
+
+class AuthorFilter(ForeignKeyFilter):
+    parameter_name = "author"
+    ordering = ["name"]
+
+
+@admin.register(Book)
+class BookAdmin(admin.ModelAdmin):
+    list_filter = [AuthorFilter]
+```
+
+![ForeignKeyFilter dropdown with a search box, listing authors](docs/screenshots/foreign-key-filter.png)
+
+`model` is only needed when it can't be inferred. By default it's resolved by
+walking `parameter_name` across `Book`'s relations, following a nested lookup
+(e.g. `parameter_name = "author__country"`) segment by segment — forward or
+reverse — and taking the last segment's related model. Set `model` explicitly
+if the lookup isn't a real relation chain, or to point somewhere else.
+
+### `field_list_filter()`
+
+For a one-off filter that doesn't need its own subclass, use Django's own
+`list_filter` shorthand — a `(field_name, filter_class)` tuple — via
+`field_list_filter()`:
+
+```python
+from django_admin_select_filter import ChoiceFilter, ForeignKeyFilter, field_list_filter
+
+
+@admin.register(Book)
+class BookAdmin(admin.ModelAdmin):
+    list_filter = [
+        ("author", field_list_filter(ForeignKeyFilter)),
+        ("genre", field_list_filter(ChoiceFilter)),
+    ]
+```
+
+`parameter_name` (and, for `ForeignKeyFilter`, `model`) is inferred from the
+field automatically — including a nested lookup like `"author__country"` —
+so the same wrapped class can be reused across as many fields as you like.
+It only supports `async_call = False`; for an `async_call` filter, define a
+dedicated subclass instead (`field_list_filter()` raises `TypeError` right
+away if you pass it one, rather than fail silently later).
+
+### Shared options
+
+Both filters share the same options: `filter_only_used_values`, `async_call`,
+`searchable`, `nullable` and `title`. Both also support a nested lookup for
+`parameter_name` (e.g. `"author__status"`), resolving the field — and, for
+`ForeignKeyFilter`, the `model` — by walking each `__`-separated relation in
+turn, forward or reverse.
+
+Set `searchable = False` to hide the search input entirely and get a plain
+dropdown instead — best for a short, static option list.
+
+Set `multiple = True` to let either filter accept several values at once:
+
+```python
+class AuthorFilter(ForeignKeyFilter):
+    parameter_name = "author"
+    multiple = True
+```
+
+![multiple = True with two selected author chips](docs/screenshots/multiple.png)
+
+Selected values are joined in the query string with `multiple_separator`
+(`","` by default) and applied with an `__in` lookup, so configured values
+(primary keys, option values) must not contain that character. The "All"
+option is dropped in this mode — clearing every selected chip already means
+no filter.
+
+## Async options (`async_call = True`)
+
+Set `async_call = True` on a filter to defer loading its options until the
+Select2 widget is opened, fetching them over AJAX instead of rendering every
+option upfront — useful for a related model with many rows. It requires
+wiring an options endpoint: drop `django_admin_select_filter_path()` into
+your root `urlpatterns` — no `include()` needed:
+
+```python
+# urls.py
+from django_admin_select_filter import django_admin_select_filter_path
+
+urlpatterns = [
+    ...
+    django_admin_select_filter_path(),
+]
+```
+
+Its route defaults to `django_admin_select_filter/options/`; pass `route` in
+case it collides with something else in your project:
+
+```python
+django_admin_select_filter_path(route="custom-options/")
+```
+
+The endpoint stays reversible as `admin_select_filter:options` either way —
+`django_admin_select_filter_path()` still namespaces it internally via
+`include()`, that's just no longer something you have to write yourself.
+Pass `route`, `view`, `name` or `as_view_kwargs` to customize it further. If
+you pass a custom `name`, set `async_call_url` explicitly on every
+`async_call` filter to match it — filters resolve the default endpoint by
+its default name, and have no way to discover a custom one chosen here.
+
+Each `async_call` filter reads that shared endpoint through
+`BaseSelectFilter.async_call_url`, resolved automatically at request time via
+`reverse("admin_select_filter:options")`. Set `async_call_url` on a specific
+filter to point it at a different view instead:
+
+```python
+class AuthorFilter(ForeignKeyFilter):
+    parameter_name = "author"
+    async_call = True
+    async_call_url = "/api/custom-author-options/"
+```
+
+If its route shares a prefix with your admin mount (e.g. both under
+`admin/`), list `django_admin_select_filter_path()` **before**
+`path("admin/", admin.site.urls)`. Since Django 4.1, `AdminSite` registers a
+catch-all view (`AdminSite.final_catch_all_view`, enabled by default) that
+matches every otherwise-unmatched URL under its own prefix and raises
+`Http404` itself — so if the admin mount comes first, it swallows requests to
+this app's options endpoint before its URLs ever get a chance to match, and
+you'll see a 404 with a full HTML body (the admin's own "Page not found"
+page) instead of this app's JSON response.
+
+The filter template loads jQuery/Select2 from Django admin's bundled vendor
+assets on demand, so no extra JS dependency is required. Make sure
+`django.contrib.staticfiles` is installed and configured.
+
+The endpoint only serves filters with `async_call = True` and requires the
+requesting user to have view permission on the target model (checked via
+`ModelAdmin.has_view_permission`) — anonymous or unprivileged requests get a
+403, and a `parameter_name` matching a non-async filter gets a 404. It looks
+the model up across every registered `AdminSite` (not just the default
+`django.contrib.admin.site`), so a project using its own `AdminSite` works too.
+
+By default it does this by calling `get_list_filter()` on every matching
+`ModelAdmin` on every request. For a project with many admins or filters,
+pass `as_view_kwargs={"use_registry": True}` to
+`django_admin_select_filter_path()` instead: it resolves filters from a
+`{site: {app_label: {model_name: {parameter_name: filter}}}}` map built once
+and cached for the process's lifetime (admin registrations are static after
+startup), turning that per-request scan into a single dict lookup. The
+trade-off: it calls `get_list_filter(request=None)` while building the
+cache, so a `get_list_filter()` override that depends on the request isn't
+supported in this mode.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, running the
+test suite (including the browser-driven e2e tests), and pre-commit hooks.