Changelog¶

To install unreleased versions of a workspace package, see developmental releases.

This changelog covers the whole workspace in one place: the core django-search-query package and the optional django-admin-search-query integration. Deliverables specific to the admin package name it in their heading.

django-search-query 0.1.0a1 (unreleased)¶

Upcoming changes will be written here.

Documentation¶

Tutorials, reference, and highlighted query examples (#4)¶

The docs are now a full guided site for both packages: a tutorial that runs a search against a real queryset, how-to guides, an API reference, and explanation pages. Query examples are syntax-highlighted, and an interactive install picker shows the matching pip/uv command for each package.

A dedicated query-language page with worked examples (#6)¶

The query language now has its own top-level page that shows the payoff up front: a search string becoming a Django Q, filtering a queryset, and the SQL it runs – with results checked against a live table so the examples stay honest. Query snippets are highlighted inline in prose too, not just in code blocks.

django-search-query 0.1.0a0 (2026-07-19)¶

django-search-query 0.1.0a0 is the first alpha of the workspace, shipping the core query language together with its optional Django admin integration. The core compiles a Lucene-inspired search string into a Django Q object, backed by a field registry that keeps the searchable surface decoupled from your models and a highlighter for syntax-colored search boxes. The companion django-admin-search-query brings the language to admin changelists, adding a client-side colored, autocompleting search input that degrades to a plain field without JavaScript. As an alpha, the APIs may still change before the 0.1.0 release.

What’s new¶

Structured search query language (#1)¶

Turn a user’s search string into a Django Q object with one search_query_to_q() call. The Lucene-inspired syntax covers field-scoped terms (status:open), quoted phrases, boolean AND/OR/NOT with grouping, comparison and range operators, wildcards, and +/- negation. Half-typed or unparseable input degrades to a match instead of raising, so a query runs while the user is still typing.

Searchable-field registry (#1)¶

A FieldRegistry declares which fields are searchable and maps user-facing names and aliases to ORM lookups, keeping the search surface decoupled from your models. Unknown fields and out-of-enum values are rejected as the query compiles, rather than silently mis-querying.

Query highlighting (#2)¶

highlight_query_spans() lexes a query string into contiguous (start, role, text) spans – fields, phrases, keywords, operators, negation, and wildcards – ready to drive a syntax-highlighted search box. A registry-aware pass flags unknown fields and out-of-enum values with an error role, and the lexer never raises on half-typed input.

`django-admin-search-query`: Structured search in the changelist (#1)¶

SearchQueryAdminMixin teaches the admin search box the query language: drop it before ModelAdmin and the changelist accepts field-scoped, boolean, and phrase queries. Anything it can’t parse – including a plain word – falls back to Django’s built-in search_fields, so the box never behaves worse than stock admin.

`django-admin-search-query`: Colored, autocompleting search input (#2)¶

The changelist search box highlights the query as you type – field-scoped terms, phrases, operators, and errors are colored live and entirely client-side, with no per-keystroke request. A keyboard-navigable combobox suggests field names, enum values, and comparison/range operators. With JavaScript off it degrades to the plain search box, so nothing regresses below stock admin.

Development¶

Automated documentation publishing (#3)¶

Sphinx docs now build on every pull request, so a broken docs build is caught in review rather than after merge. Merges to master publish the rendered site automatically, keeping the documentation site current without a manual release step.