django-admin-search-field 0.1.0__tar.gz

django_admin_search_field-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Valle
+
+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_search_field-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: django-admin-search-field
+Version: 0.1.0
+Summary: Per-field search selector combobox for the Django admin changelist
+Author: Fabio Valle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fdelvalle/django-admin-search-field
+Project-URL: Issues, https://github.com/fdelvalle/django-admin-search-field/issues
+Keywords: django,admin,search,changelist,django-admin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Dynamic: license-file
+
+# django-admin-search-field
+
+A per-field search selector for the Django admin changelist.
+
+By default, the Django admin searches the submitted term across **every**
+field listed in a `ModelAdmin.search_fields` (joined with `OR`). On tables
+with many fields, several relations, or large row counts, that makes the
+search slow — and there is no built-in way to search a single field instead.
+
+This package adds a small combobox next to the search box, letting the user
+restrict the search to **one** field — or keep "All fields" for the native
+behaviour.
+
+## Features
+
+- Adds a `<select>` next to the changelist search box with one option per
+  `search_fields` entry, using a friendly label (`verbose_name`, following
+  relations, e.g. `author__name` → "Author › Name").
+- Restricts the actual search query to the chosen field via the `sf` GET
+  parameter (name configurable).
+- Works globally, for every registered `ModelAdmin`, via a single opt-in
+  call — no need to touch each `admin.py`.
+- Also available as an explicit mixin (`SearchFieldSelectMixin`) if you'd
+  rather opt in per `ModelAdmin`.
+- Defensive by design: any unexpected failure falls back to Django's native
+  search behaviour instead of breaking the admin page.
+- Ships a template override (`admin/search_form.html`) and a small,
+  dependency-free CSS file that follows the admin's own light/dark theme
+  variables.
+
+## Installation
+
+```bash
+pip install django-admin-search-field
+```
+
+Add the app to `INSTALLED_APPS`, **before** `django.contrib.admin` (required
+so the bundled `admin/search_form.html` overrides Django's default template
+via the `app_directories` template loader):
+
+```python
+INSTALLED_APPS = [
+    "django_admin_search_field",
+    "django.contrib.admin",
+    ...
+]
+```
+
+Enable the selector once, globally — e.g. from your own app's
+`AppConfig.ready()`:
+
+```python
+# myapp/apps.py
+from django.apps import AppConfig
+
+
+class MyAppConfig(AppConfig):
+    name = "myapp"
+
+    def ready(self):
+        from django_admin_search_field import install_search_field_selector
+
+        install_search_field_selector()
+```
+
+(Optional) include the bundled CSS in your `admin/base_site.html` (or
+wherever you already extend the admin base template):
+
+```html
+{% load static %}
+<link rel="stylesheet" href="{% static 'django_admin_search_field/css/search_field.css' %}">
+```
+
+That's it — every `ModelAdmin` with `search_fields` configured now shows the
+field selector.
+
+## Usage without the global monkey-patch
+
+If you'd rather enable this on a single `ModelAdmin`, skip
+`install_search_field_selector()` and use the mixin instead:
+
+```python
+from django.contrib import admin
+from django_admin_search_field import SearchFieldSelectMixin
+
+from myapp.models import Book
+
+
+@admin.register(Book)
+class BookAdmin(SearchFieldSelectMixin, admin.ModelAdmin):
+    search_fields = ["title", "isbn", "author__name"]
+```
+
+In this mode you're responsible for including the CSS/template yourself,
+and you don't need to add `django_admin_search_field` to `INSTALLED_APPS` —
+only the Python mixin is used.
+
+## Configuration
+
+| Setting | Default | Description |
+|---|---|---|
+| `ADMIN_SEARCH_FIELD_VAR` | `"sf"` | Name of the GET parameter used to carry the chosen field. Override it if `sf` collides with something else in your project. |
+
+## How it works
+
+- `resolve_search_fields()` restricts `search_fields` to the field selected
+  via the `sf` GET parameter — or returns the original list unchanged when
+  `sf` is empty ("All fields") or points to a field that isn't configured.
+- `sf` is registered in the changelist's `IGNORED_PARAMS`, so it's never
+  misread as a list filter (which would otherwise raise
+  `IncorrectLookupParameters`).
+- The template only receives the `cl` (ChangeList) object, so the combobox
+  data is attached directly to it: `cl.search_field_choices`,
+  `cl.search_field_selected`, `cl.search_field_var`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Compatibility
+
+- Python 3.10+
+- Django 4.2+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_admin_search_field-0.1.0/README.md

@@ -0,0 +1,130 @@
+# django-admin-search-field
+
+A per-field search selector for the Django admin changelist.
+
+By default, the Django admin searches the submitted term across **every**
+field listed in a `ModelAdmin.search_fields` (joined with `OR`). On tables
+with many fields, several relations, or large row counts, that makes the
+search slow — and there is no built-in way to search a single field instead.
+
+This package adds a small combobox next to the search box, letting the user
+restrict the search to **one** field — or keep "All fields" for the native
+behaviour.
+
+## Features
+
+- Adds a `<select>` next to the changelist search box with one option per
+  `search_fields` entry, using a friendly label (`verbose_name`, following
+  relations, e.g. `author__name` → "Author › Name").
+- Restricts the actual search query to the chosen field via the `sf` GET
+  parameter (name configurable).
+- Works globally, for every registered `ModelAdmin`, via a single opt-in
+  call — no need to touch each `admin.py`.
+- Also available as an explicit mixin (`SearchFieldSelectMixin`) if you'd
+  rather opt in per `ModelAdmin`.
+- Defensive by design: any unexpected failure falls back to Django's native
+  search behaviour instead of breaking the admin page.
+- Ships a template override (`admin/search_form.html`) and a small,
+  dependency-free CSS file that follows the admin's own light/dark theme
+  variables.
+
+## Installation
+
+```bash
+pip install django-admin-search-field
+```
+
+Add the app to `INSTALLED_APPS`, **before** `django.contrib.admin` (required
+so the bundled `admin/search_form.html` overrides Django's default template
+via the `app_directories` template loader):
+
+```python
+INSTALLED_APPS = [
+    "django_admin_search_field",
+    "django.contrib.admin",
+    ...
+]
+```
+
+Enable the selector once, globally — e.g. from your own app's
+`AppConfig.ready()`:
+
+```python
+# myapp/apps.py
+from django.apps import AppConfig
+
+
+class MyAppConfig(AppConfig):
+    name = "myapp"
+
+    def ready(self):
+        from django_admin_search_field import install_search_field_selector
+
+        install_search_field_selector()
+```
+
+(Optional) include the bundled CSS in your `admin/base_site.html` (or
+wherever you already extend the admin base template):
+
+```html
+{% load static %}
+<link rel="stylesheet" href="{% static 'django_admin_search_field/css/search_field.css' %}">
+```
+
+That's it — every `ModelAdmin` with `search_fields` configured now shows the
+field selector.
+
+## Usage without the global monkey-patch
+
+If you'd rather enable this on a single `ModelAdmin`, skip
+`install_search_field_selector()` and use the mixin instead:
+
+```python
+from django.contrib import admin
+from django_admin_search_field import SearchFieldSelectMixin
+
+from myapp.models import Book
+
+
+@admin.register(Book)
+class BookAdmin(SearchFieldSelectMixin, admin.ModelAdmin):
+    search_fields = ["title", "isbn", "author__name"]
+```
+
+In this mode you're responsible for including the CSS/template yourself,
+and you don't need to add `django_admin_search_field` to `INSTALLED_APPS` —
+only the Python mixin is used.
+
+## Configuration
+
+| Setting | Default | Description |
+|---|---|---|
+| `ADMIN_SEARCH_FIELD_VAR` | `"sf"` | Name of the GET parameter used to carry the chosen field. Override it if `sf` collides with something else in your project. |
+
+## How it works
+
+- `resolve_search_fields()` restricts `search_fields` to the field selected
+  via the `sf` GET parameter — or returns the original list unchanged when
+  `sf` is empty ("All fields") or points to a field that isn't configured.
+- `sf` is registered in the changelist's `IGNORED_PARAMS`, so it's never
+  misread as a list filter (which would otherwise raise
+  `IncorrectLookupParameters`).
+- The template only receives the `cl` (ChangeList) object, so the combobox
+  data is attached directly to it: `cl.search_field_choices`,
+  `cl.search_field_selected`, `cl.search_field_var`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Compatibility
+
+- Python 3.10+
+- Django 4.2+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_admin_search_field-0.1.0/django_admin_search_field/__init__.py

@@ -0,0 +1,71 @@
+"""A per-field search selector for the Django admin changelist.
+
+By default, the Django admin searches the submitted term across every field
+in ``search_fields`` (joined with OR). On large tables with many fields and
+relations, that makes search slow. This package adds a combobox next to the
+search box so users can restrict a search to a single field.
+
+Installation
+------------
+1. ``pip install django-admin-search-field``
+
+2. Add ``"django_admin_search_field"`` to ``INSTALLED_APPS``, **before**
+   ``"django.contrib.admin"`` (required so the bundled
+   ``admin/search_form.html`` template overrides Django's default one)::
+
+    INSTALLED_APPS = [
+        "django_admin_search_field",
+        "django.contrib.admin",
+        ...
+    ]
+
+3. Enable the selector globally, once — e.g. in your own app's
+   ``AppConfig.ready()``::
+
+    from django_admin_search_field import install_search_field_selector
+
+    class MyAppConfig(AppConfig):
+        def ready(self):
+            install_search_field_selector()
+
+4. (Optional) include the bundled CSS in your ``admin/base_site.html``::
+
+    {% load static %}
+    <link rel="stylesheet" href="{% static 'django_admin_search_field/css/search_field.css' %}">
+
+Explicit, per-admin use (no global monkey-patch)
+-------------------------------------------------
+To enable the selector on a single ``ModelAdmin`` only, use the mixin::
+
+    from django_admin_search_field import SearchFieldSelectMixin
+
+    @admin.register(MyModel)
+    class MyModelAdmin(SearchFieldSelectMixin, admin.ModelAdmin):
+        search_fields = ["name", "owner__email"]
+"""
+
+from __future__ import annotations
+
+from django_admin_search_field.fields import (
+    SearchFieldSelectMixin,
+    build_search_field_choices,
+    get_selected_search_field,
+    label_for_search_field,
+    resolve_search_fields,
+    strip_search_prefix,
+)
+from django_admin_search_field.install import install_search_field_selector
+
+__version__ = "0.1.0"
+
+default_app_config = "django_admin_search_field.apps.AdminSearchFieldConfig"
+
+__all__ = [
+    "SearchFieldSelectMixin",
+    "build_search_field_choices",
+    "get_selected_search_field",
+    "install_search_field_selector",
+    "label_for_search_field",
+    "resolve_search_fields",
+    "strip_search_prefix",
+]

django_admin_search_field-0.1.0/django_admin_search_field/apps.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class AdminSearchFieldConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_search_field"
+    label = "admin_search_field"
+    verbose_name = "Admin Search Field Selector"

django_admin_search_field-0.1.0/django_admin_search_field/fields.py

@@ -0,0 +1,196 @@
+"""Search field selector logic for the Django admin.
+
+By default, the Django admin searches the submitted term across every field
+listed in ``search_fields`` (joined with OR). On large tables with many
+fields and relations, this makes search slow.
+
+This module adds a combobox next to the search box, letting the user pick a
+**single** field to search — or "All fields" to keep the native behaviour.
+
+How it works
+-------------
+* The bundled ``admin/search_form.html`` template renders a ``<select>`` with
+  one option per entry in ``search_fields`` (with a friendly label for each
+  field) plus an "All fields" option. The chosen field is submitted via the
+  ``sf`` GET parameter (configurable, see ``SEARCH_FIELD_VAR`` below).
+* ``resolve_search_fields`` restricts the search to the chosen field when
+  ``sf`` is valid; otherwise it returns the original fields unchanged.
+* The ``sf`` parameter must be registered in the changelist's
+  ``IGNORED_PARAMS`` so it isn't treated as a list filter — this is handled by
+  :func:`django_admin_search_field.install.install_search_field_selector`.
+
+The feature is enabled globally by ``install_search_field_selector`` (an
+additive monkey-patch on the base ``ModelAdmin`` class). Everything here is
+defensive: any failure falls back to native admin behaviour.
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.exceptions import FieldDoesNotExist
+from django.db.models.constants import LOOKUP_SEP
+
+# Lookup prefixes accepted by Django in ``search_fields``.
+_LOOKUP_PREFIXES = ("^", "=", "@")
+
+
+def _search_field_var() -> str:
+    """Name of the GET parameter carrying the chosen field.
+
+    Override with ``ADMIN_SEARCH_FIELD_VAR`` in your Django settings if ``sf``
+    collides with something else in your project.
+    """
+    return getattr(settings, "ADMIN_SEARCH_FIELD_VAR", "sf")
+
+
+# Kept as a module-level constant for convenience/backwards compatibility.
+# Prefer calling ``_search_field_var()`` internally so overrides via settings
+# take effect even after this module has been imported.
+SEARCH_FIELD_VAR = "sf"
+
+
+def strip_search_prefix(field: str) -> str:
+    """Strip the lookup prefixes (``^``, ``=``, ``@``) from a search_field entry."""
+    field = str(field)
+    while field and field[0] in _LOOKUP_PREFIXES:
+        field = field[1:]
+    return field
+
+
+def label_for_search_field(model, field: str) -> str:
+    """Derive a friendly label for a ``search_fields`` entry.
+
+    Tries to use the field's ``verbose_name`` (following relations, e.g.
+    ``owner__name``). Falls back to a label derived from the raw field name
+    (``owner__name`` -> "Owner name") when it can't be resolved.
+    """
+    clean = strip_search_prefix(field)
+    parts = clean.split(LOOKUP_SEP)
+
+    opts = getattr(model, "_meta", None)
+    labels: list[str] = []
+    resolved = True
+
+    for part in parts:
+        if opts is None:
+            resolved = False
+            break
+        name = opts.pk.name if part == "pk" else part
+        try:
+            model_field = opts.get_field(name)
+        except (FieldDoesNotExist, AttributeError):
+            resolved = False
+            break
+
+        verbose = getattr(model_field, "verbose_name", None) or name
+        labels.append(str(verbose).strip().capitalize())
+
+        # Follow the relation, if any, to resolve the next part.
+        related = getattr(model_field, "related_model", None)
+        opts = getattr(related, "_meta", None) if related else None
+
+    if resolved and labels:
+        return " › ".join(labels)
+
+    # Fallback: build a label from the raw name.
+    return clean.replace(LOOKUP_SEP, " ").replace("_", " ").strip().capitalize()
+
+
+def get_selected_search_field(request) -> str:
+    """Return the field chosen in the GET params, or ``""`` for "All fields"."""
+    try:
+        return (request.GET.get(_search_field_var()) or "").strip()
+    except Exception:
+        return ""
+
+
+def resolve_search_fields(original_search_fields, request):
+    """Restrict ``search_fields`` to the field chosen in the combobox.
+
+    If the selector is empty ("All fields") or points to a field that isn't
+    configured (e.g. an arbitrary value from the URL), the original list is
+    returned unchanged — keeping native admin behaviour.
+    """
+    selected = get_selected_search_field(request)
+    if not selected:
+        return original_search_fields
+    if selected in {str(f) for f in (original_search_fields or ())}:
+        return (selected,)
+    return original_search_fields
+
+
+def build_search_field_choices(model_admin, request) -> list[dict]:
+    """Build the combobox options from ``search_fields``.
+
+    Returns a list of dicts ``{"value", "label", "selected"}``. Does not
+    include the "All fields" option (the template handles that). Returns an
+    empty list if the admin has no ``search_fields``.
+
+    Uses the FULL list of fields (stashed on ``_original_search_fields`` by
+    ``get_search_fields``) so every option is always listed, even once the
+    search is already restricted to a single field.
+    """
+    search_fields = getattr(model_admin, "_original_search_fields", None)
+    if search_fields is None:
+        try:
+            search_fields = model_admin.get_search_fields(request)
+        except Exception:
+            search_fields = getattr(model_admin, "search_fields", None) or ()
+
+    selected = get_selected_search_field(request)
+    model = getattr(model_admin, "model", None)
+
+    choices: list[dict] = []
+    seen: set[str] = set()
+    for field in search_fields or ():
+        value = str(field)
+        if value in seen:
+            continue
+        seen.add(value)
+        choices.append(
+            {
+                "value": value,
+                "label": label_for_search_field(model, value),
+                "selected": value == selected,
+            }
+        )
+    return choices
+
+
+class SearchFieldSelectMixin:
+    """Restrict search to the field chosen in the combobox (``sf`` param).
+
+    ``install_search_field_selector`` applies this behaviour globally via a
+    monkey-patch (every ``ModelAdmin`` gets the selector). This mixin is also
+    available for explicit use/tests, or to enable the feature on a single
+    admin class without the global monkey-patch.
+    """
+
+    def get_search_fields(self, request):
+        original = super().get_search_fields(request)
+        # Stash the full list so the template can list every option, even
+        # when the search is currently restricted to one field.
+        try:
+            self._original_search_fields = tuple(original)
+        except Exception:
+            self._original_search_fields = original
+        return resolve_search_fields(original, request)
+
+    def get_changelist_instance(self, request):
+        """Attach the selector's data to the ChangeList instance.
+
+        The ``admin/search_form.html`` template only receives the ``cl``
+        object (the ``search_form`` inclusion tag builds its context from
+        it), so we expose the options there: ``cl.search_field_choices``,
+        ``cl.search_field_selected`` and ``cl.search_field_var``.
+        """
+        cl = super().get_changelist_instance(request)
+        try:
+            cl.search_field_choices = build_search_field_choices(self, request)
+            cl.search_field_selected = get_selected_search_field(request)
+            cl.search_field_var = _search_field_var()
+        except Exception:
+            cl.search_field_choices = []
+            cl.search_field_selected = ""
+            cl.search_field_var = _search_field_var()
+        return cl

django_admin_search_field-0.1.0/django_admin_search_field/install.py

@@ -0,0 +1,79 @@
+"""Global installation of the search field selector on every ModelAdmin."""
+
+from __future__ import annotations
+
+from django_admin_search_field.fields import (
+    _search_field_var,
+    build_search_field_choices,
+    get_selected_search_field,
+    resolve_search_fields,
+)
+
+
+def install_search_field_selector() -> None:
+    """Enable the search field selector on EVERY ``ModelAdmin``.
+
+    Instead of reclassifying every admin registered with ``@admin.register``,
+    this patches the base ``ModelAdmin`` class itself (additive, idempotent
+    monkey-patch):
+
+    * ``get_search_fields`` now honours the ``sf`` GET parameter (restricts
+      the search to a single field) — via
+      :class:`django_admin_search_field.fields.SearchFieldSelectMixin`.
+    * ``get_changelist_instance`` attaches the combobox options to the ``cl``
+      object.
+    * The ``sf`` parameter is registered in the changelist's
+      ``IGNORED_PARAMS`` so it isn't treated as a list filter.
+
+    Call this once, for example from your own app's ``AppConfig.ready()``:
+
+        # myapp/apps.py
+        class MyAppConfig(AppConfig):
+            def ready(self):
+                from django_admin_search_field import install_search_field_selector
+                install_search_field_selector()
+
+    Defensive: any failure here must never break the admin.
+    """
+    from django.contrib.admin.options import ModelAdmin
+
+    if getattr(ModelAdmin, "_admin_search_field_installed", False):
+        return
+
+    # 1) 'sf' (or the configured override) must not be read as a list filter.
+    from django.contrib.admin.views import main as admin_main
+
+    search_field_var = _search_field_var()
+    if search_field_var not in admin_main.IGNORED_PARAMS:
+        admin_main.IGNORED_PARAMS = tuple(admin_main.IGNORED_PARAMS) + (search_field_var,)
+
+    # 2) Wrap the original base-class methods, preserving them.
+    original_get_search_fields = ModelAdmin.get_search_fields
+    original_get_changelist_instance = ModelAdmin.get_changelist_instance
+
+    def get_search_fields(self, request):
+        original = original_get_search_fields(self, request)
+        try:
+            self._original_search_fields = tuple(original)
+        except Exception:
+            self._original_search_fields = original
+        try:
+            return resolve_search_fields(original, request)
+        except Exception:
+            return original
+
+    def get_changelist_instance(self, request):
+        cl = original_get_changelist_instance(self, request)
+        try:
+            cl.search_field_choices = build_search_field_choices(self, request)
+            cl.search_field_selected = get_selected_search_field(request)
+            cl.search_field_var = _search_field_var()
+        except Exception:
+            cl.search_field_choices = []
+            cl.search_field_selected = ""
+            cl.search_field_var = _search_field_var()
+        return cl
+
+    ModelAdmin.get_search_fields = get_search_fields
+    ModelAdmin.get_changelist_instance = get_changelist_instance
+    ModelAdmin._admin_search_field_installed = True

django_admin_search_field-0.1.0/django_admin_search_field/static/django_admin_search_field/css/search_field.css

@@ -0,0 +1,55 @@
+/* Styling for the search field selector combobox (django-admin-search-field).
+ * Uses the Django admin's own theme variables (--border-color, --body-fg,
+ * --body-bg, --link-fg), so it automatically follows the admin's light/dark
+ * mode without depending on any project-specific visual component. */
+
+#changelist-search .admin-search-field-group {
+    display: inline-flex;
+    align-items: stretch;
+    vertical-align: middle;
+    border: 1px solid var(--border-color);
+    border-radius: 4px;
+    overflow: hidden;
+    background: var(--body-bg);
+}
+
+#changelist-search .admin-search-field-group .admin-search-field-select,
+#changelist-search .admin-search-field-group #searchbar,
+#changelist-search .admin-search-field-group .admin-search-field-submit {
+    border: none;
+    border-radius: 0;
+    background: transparent;
+    color: var(--body-fg);
+    height: 2.25rem;
+    box-sizing: border-box;
+}
+
+#changelist-search .admin-search-field-group .admin-search-field-select {
+    border-right: 1px solid var(--border-color);
+    padding: 0 0.5rem;
+    max-width: 12rem;
+}
+
+#changelist-search .admin-search-field-group #searchbar {
+    padding: 0 0.5rem;
+    flex: 1 1 auto;
+}
+
+#changelist-search .admin-search-field-group .admin-search-field-submit {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0 0.75rem;
+    cursor: pointer;
+    color: var(--link-fg);
+}
+
+#changelist-search .admin-search-field-group .admin-search-field-submit:hover {
+    color: var(--link-hover-color, var(--link-fg));
+}
+
+#changelist-search .admin-search-field-group .admin-search-field-select:focus,
+#changelist-search .admin-search-field-group #searchbar:focus {
+    outline: none;
+    box-shadow: inset 0 0 0 2px var(--link-fg);
+}

django_admin_search_field-0.1.0/django_admin_search_field/templates/admin/search_form.html

@@ -0,0 +1,34 @@
+{% load i18n static %}
+{% if cl.search_fields %}
+<div id="toolbar"><form id="changelist-search" method="get" role="search">
+<div><!-- DIV needed for valid HTML -->
+<div class="admin-search-field-group">
+{% if cl.search_field_choices %}
+    <select name="{{ cl.search_field_var|default:'sf' }}" id="search-field-select" class="admin-search-field-select" title="{% translate 'Search by field' %}" aria-label="{% translate 'Search by field' %}">
+        <option value=""{% if not cl.search_field_selected %} selected{% endif %}>{% translate 'All fields' %}</option>
+        {% for choice in cl.search_field_choices %}
+        <option value="{{ choice.value }}"{% if choice.selected %} selected{% endif %}>{{ choice.label }}</option>
+        {% endfor %}
+    </select>
+{% endif %}
+    <input type="text" size="40" name="{{ search_var }}" value="{{ cl.query }}" id="searchbar"{% if cl.search_help_text %} aria-describedby="searchbar_helptext"{% endif %} placeholder="{% translate 'Search' %}">
+    <button type="submit" class="admin-search-field-submit" title="{% translate 'Search' %}" aria-label="{% translate 'Search' %}">
+        <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
+            <circle cx="11" cy="11" r="7"></circle>
+            <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+        </svg>
+    </button>
+</div>
+{% if show_result_count %}
+    <span class="small quiet">{% blocktranslate count counter=cl.result_count %}{{ counter }} result{% plural %}{{ counter }} results{% endblocktranslate %} (<a href="?{% if cl.is_popup %}{{ is_popup_var }}=1{% if cl.add_facets %}&{% endif %}{% endif %}{% if cl.add_facets %}{{ is_facets_var }}{% endif %}">{% if cl.show_full_result_count %}{% blocktranslate with full_result_count=cl.full_result_count %}{{ full_result_count }} total{% endblocktranslate %}{% else %}{% translate "Show all" %}{% endif %}</a>)</span>
+{% endif %}
+{% for pair in cl.params.items %}
+    {% if pair.0 != search_var and pair.0 != cl.search_field_var %}<input type="hidden" name="{{ pair.0 }}" value="{{ pair.1 }}">{% endif %}
+{% endfor %}
+</div>
+{% if cl.search_help_text %}
+<br class="clear">
+<div class="help" id="searchbar_helptext">{{ cl.search_help_text }}</div>
+{% endif %}
+</form></div>
+{% endif %}

django_admin_search_field-0.1.0/django_admin_search_field.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: django-admin-search-field
+Version: 0.1.0
+Summary: Per-field search selector combobox for the Django admin changelist
+Author: Fabio Valle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fdelvalle/django-admin-search-field
+Project-URL: Issues, https://github.com/fdelvalle/django-admin-search-field/issues
+Keywords: django,admin,search,changelist,django-admin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Dynamic: license-file
+
+# django-admin-search-field
+
+A per-field search selector for the Django admin changelist.
+
+By default, the Django admin searches the submitted term across **every**
+field listed in a `ModelAdmin.search_fields` (joined with `OR`). On tables
+with many fields, several relations, or large row counts, that makes the
+search slow — and there is no built-in way to search a single field instead.
+
+This package adds a small combobox next to the search box, letting the user
+restrict the search to **one** field — or keep "All fields" for the native
+behaviour.
+
+## Features
+
+- Adds a `<select>` next to the changelist search box with one option per
+  `search_fields` entry, using a friendly label (`verbose_name`, following
+  relations, e.g. `author__name` → "Author › Name").
+- Restricts the actual search query to the chosen field via the `sf` GET
+  parameter (name configurable).
+- Works globally, for every registered `ModelAdmin`, via a single opt-in
+  call — no need to touch each `admin.py`.
+- Also available as an explicit mixin (`SearchFieldSelectMixin`) if you'd
+  rather opt in per `ModelAdmin`.
+- Defensive by design: any unexpected failure falls back to Django's native
+  search behaviour instead of breaking the admin page.
+- Ships a template override (`admin/search_form.html`) and a small,
+  dependency-free CSS file that follows the admin's own light/dark theme
+  variables.
+
+## Installation
+
+```bash
+pip install django-admin-search-field
+```
+
+Add the app to `INSTALLED_APPS`, **before** `django.contrib.admin` (required
+so the bundled `admin/search_form.html` overrides Django's default template
+via the `app_directories` template loader):
+
+```python
+INSTALLED_APPS = [
+    "django_admin_search_field",
+    "django.contrib.admin",
+    ...
+]
+```
+
+Enable the selector once, globally — e.g. from your own app's
+`AppConfig.ready()`:
+
+```python
+# myapp/apps.py
+from django.apps import AppConfig
+
+
+class MyAppConfig(AppConfig):
+    name = "myapp"
+
+    def ready(self):
+        from django_admin_search_field import install_search_field_selector
+
+        install_search_field_selector()
+```
+
+(Optional) include the bundled CSS in your `admin/base_site.html` (or
+wherever you already extend the admin base template):
+
+```html
+{% load static %}
+<link rel="stylesheet" href="{% static 'django_admin_search_field/css/search_field.css' %}">
+```
+
+That's it — every `ModelAdmin` with `search_fields` configured now shows the
+field selector.
+
+## Usage without the global monkey-patch
+
+If you'd rather enable this on a single `ModelAdmin`, skip
+`install_search_field_selector()` and use the mixin instead:
+
+```python
+from django.contrib import admin
+from django_admin_search_field import SearchFieldSelectMixin
+
+from myapp.models import Book
+
+
+@admin.register(Book)
+class BookAdmin(SearchFieldSelectMixin, admin.ModelAdmin):
+    search_fields = ["title", "isbn", "author__name"]
+```
+
+In this mode you're responsible for including the CSS/template yourself,
+and you don't need to add `django_admin_search_field` to `INSTALLED_APPS` —
+only the Python mixin is used.
+
+## Configuration
+
+| Setting | Default | Description |
+|---|---|---|
+| `ADMIN_SEARCH_FIELD_VAR` | `"sf"` | Name of the GET parameter used to carry the chosen field. Override it if `sf` collides with something else in your project. |
+
+## How it works
+
+- `resolve_search_fields()` restricts `search_fields` to the field selected
+  via the `sf` GET parameter — or returns the original list unchanged when
+  `sf` is empty ("All fields") or points to a field that isn't configured.
+- `sf` is registered in the changelist's `IGNORED_PARAMS`, so it's never
+  misread as a list filter (which would otherwise raise
+  `IncorrectLookupParameters`).
+- The template only receives the `cl` (ChangeList) object, so the combobox
+  data is attached directly to it: `cl.search_field_choices`,
+  `cl.search_field_selected`, `cl.search_field_var`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Compatibility
+
+- Python 3.10+
+- Django 4.2+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_admin_search_field-0.1.0/django_admin_search_field.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+django_admin_search_field/__init__.py
+django_admin_search_field/apps.py
+django_admin_search_field/fields.py
+django_admin_search_field/install.py
+django_admin_search_field.egg-info/PKG-INFO
+django_admin_search_field.egg-info/SOURCES.txt
+django_admin_search_field.egg-info/dependency_links.txt
+django_admin_search_field.egg-info/requires.txt
+django_admin_search_field.egg-info/top_level.txt
+django_admin_search_field/static/django_admin_search_field/css/search_field.css
+django_admin_search_field/templates/admin/search_form.html
+tests/test_fields.py
+tests/test_install.py

django_admin_search_field-0.1.0/django_admin_search_field.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_admin_search_field-0.1.0/django_admin_search_field.egg-info/requires.txt

@@ -0,0 +1,5 @@
+Django>=4.2
+
+[dev]
+pytest>=8.0
+pytest-django>=4.8

django_admin_search_field-0.1.0/django_admin_search_field.egg-info/top_level.txt

@@ -0,0 +1 @@
+django_admin_search_field

django_admin_search_field-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-admin-search-field"
+version = "0.1.0"
+description = "Per-field search selector combobox for the Django admin changelist"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fabio Valle" }]
+keywords = ["django", "admin", "search", "changelist", "django-admin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+dependencies = [
+    "Django>=4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/fdelvalle/django-admin-search-field"
+Issues = "https://github.com/fdelvalle/django-admin-search-field/issues"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["django_admin_search_field*"]
+
+[tool.setuptools.package-data]
+django_admin_search_field = [
+    "templates/admin/*.html",
+    "static/django_admin_search_field/css/*.css",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [".git", "__pycache__", "migrations", ".venv", "dist", "build"]
+
+lint.select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+lint.ignore = ["E501", "B008"]
+fix = true
+
+[tool.ruff.lint.isort]
+known-first-party = ["django_admin_search_field"]
+combine-as-imports = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

django_admin_search_field-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_admin_search_field-0.1.0/tests/test_fields.py

@@ -0,0 +1,90 @@
+"""Tests for django_admin_search_field.fields.
+
+Covers:
+* ``strip_search_prefix`` / ``label_for_search_field`` (friendly labels).
+* ``resolve_search_fields`` (restricting search to the chosen field).
+* ``build_search_field_choices`` (options exposed to the template).
+"""
+
+from unittest.mock import MagicMock
+
+from django.test import RequestFactory, SimpleTestCase
+
+from django_admin_search_field.fields import (
+    build_search_field_choices,
+    label_for_search_field,
+    resolve_search_fields,
+    strip_search_prefix,
+)
+from tests.testapp.models import Book
+
+
+def _request(sf=None):
+    factory = RequestFactory()
+    data = {}
+    if sf is not None:
+        data["sf"] = sf
+    return factory.get("/admin/", data)
+
+
+class StripPrefixTests(SimpleTestCase):
+    def test_strips_known_prefixes(self):
+        self.assertEqual(strip_search_prefix("^title"), "title")
+        self.assertEqual(strip_search_prefix("=isbn"), "isbn")
+        self.assertEqual(strip_search_prefix("@title"), "title")
+
+    def test_no_prefix_unchanged(self):
+        self.assertEqual(strip_search_prefix("author__name"), "author__name")
+
+
+class LabelTests(SimpleTestCase):
+    def test_label_uses_verbose_name(self):
+        # verbose_name="ISBN" is title-cased by .capitalize(), same as any
+        # other field label in this module.
+        label = label_for_search_field(Book, "isbn")
+        self.assertEqual(label, "Isbn")
+
+    def test_label_follows_relation(self):
+        label = label_for_search_field(Book, "author__name")
+        self.assertIn("›", label)
+
+    def test_label_strips_prefix(self):
+        self.assertEqual(
+            label_for_search_field(Book, "=title"),
+            label_for_search_field(Book, "title"),
+        )
+
+    def test_label_fallback_for_unknown_field(self):
+        label = label_for_search_field(Book, "does_not_exist")
+        self.assertEqual(label, "Does not exist")
+
+
+class ResolveSearchFieldsTests(SimpleTestCase):
+    def setUp(self):
+        self.fields = ("title", "isbn", "author__name")
+
+    def test_all_when_no_sf(self):
+        self.assertEqual(resolve_search_fields(self.fields, _request()), self.fields)
+        self.assertEqual(resolve_search_fields(self.fields, _request("")), self.fields)
+
+    def test_restricts_to_selected(self):
+        out = resolve_search_fields(self.fields, _request("title"))
+        self.assertEqual(out, ("title",))
+
+    def test_ignores_unknown_field(self):
+        out = resolve_search_fields(self.fields, _request("hacker__field"))
+        self.assertEqual(out, self.fields)
+
+
+class BuildChoicesTests(SimpleTestCase):
+    def test_choices_include_all_fields_with_selection(self):
+        admin_obj = MagicMock()
+        admin_obj.model = Book
+        admin_obj._original_search_fields = ("title", "isbn", "author__name")
+        choices = build_search_field_choices(admin_obj, _request("isbn"))
+        values = [c["value"] for c in choices]
+        self.assertEqual(values, ["title", "isbn", "author__name"])
+        selected = [c["value"] for c in choices if c["selected"]]
+        self.assertEqual(selected, ["isbn"])
+        for c in choices:
+            self.assertTrue(c["label"])

django_admin_search_field-0.1.0/tests/test_install.py

@@ -0,0 +1,90 @@
+"""Integration tests for django_admin_search_field.install.
+
+Uses the real BookAdmin (registered in tests/testapp/admin.py) with the
+global monkey-patch applied, plus a template-resolution check confirming the
+packaged admin/search_form.html actually overrides Django's default one.
+"""
+
+from django.contrib import admin
+from django.contrib.auth import get_user_model
+from django.template import loader
+from django.test import RequestFactory, TestCase
+
+from django_admin_search_field.install import install_search_field_selector
+from tests.testapp.models import Book
+
+
+def _request(sf=None):
+    factory = RequestFactory()
+    data = {}
+    if sf is not None:
+        data["sf"] = sf
+    return factory.get("/admin/testapp/book/", data)
+
+
+class InstallIdempotencyTests(TestCase):
+    def test_install_is_idempotent(self):
+        install_search_field_selector()
+        patched_get_search_fields = admin.ModelAdmin.get_search_fields
+        install_search_field_selector()
+        self.assertIs(admin.ModelAdmin.get_search_fields, patched_get_search_fields)
+
+
+class ModelAdminIntegrationTests(TestCase):
+    def setUp(self):
+        install_search_field_selector()
+        self.model_admin = admin.site._registry[Book]
+
+    def test_get_search_fields_all_by_default(self):
+        req = _request()
+        fields = self.model_admin.get_search_fields(req)
+        self.assertIn("title", fields)
+        self.assertIn("author__name", fields)
+
+    def test_get_search_fields_restricted_by_sf(self):
+        req = _request("title")
+        fields = self.model_admin.get_search_fields(req)
+        self.assertEqual(tuple(fields), ("title",))
+        # The full list stays available for the template.
+        self.assertIn("author__name", self.model_admin._original_search_fields)
+
+    def test_changelist_instance_exposes_choices(self):
+        User = get_user_model()
+        user = User.objects.create_superuser(username="admin_sf", email="a@b.co", password="x")
+        req = _request("title")
+        req.user = user
+        cl = self.model_admin.get_changelist_instance(req)
+        self.assertTrue(getattr(cl, "search_field_choices", None))
+        self.assertEqual(cl.search_field_selected, "title")
+        self.assertEqual(cl.search_field_var, "sf")
+
+
+class TemplateOverrideTests(TestCase):
+    def test_packaged_template_wins_over_django_default(self):
+        template = loader.get_template("admin/search_form.html")
+        origin_name = template.template.origin.name
+        self.assertIn("django_admin_search_field", origin_name)
+
+
+class ChangelistRenderTests(TestCase):
+    """Full-stack check: hit the real changelist view and inspect the HTML."""
+
+    def setUp(self):
+        install_search_field_selector()
+        User = get_user_model()
+        self.user = User.objects.create_superuser(username="root", email="root@example.com", password="x")
+        self.client.force_login(self.user)
+
+    def test_combobox_rendered_with_all_options(self):
+        response = self.client.get("/admin/testapp/book/")
+        self.assertEqual(response.status_code, 200)
+        html = response.content.decode()
+        self.assertIn('id="search-field-select"', html)
+        self.assertIn(">Title<", html)
+        self.assertIn(">Author › Name<", html)
+
+    def test_selected_field_marked_in_combobox(self):
+        response = self.client.get("/admin/testapp/book/", {"sf": "title"})
+        self.assertEqual(response.status_code, 200)
+        html = response.content.decode()
+        self.assertIn('value="title" selected', html)