API reference

Lookups

izaya.register(lookup: T) → T

Make a lookup reachable through the search endpoint.

class izaya.Lookup

Base class for lookups over any data source.

Subclasses implement search and get_selected. Both return a sequence of results that to_item understands, which by default means (key, label) pairs.

min_length = 3

max_results = 100

max_query_length = 100

placeholder = ''

no_results_text = 'No results found.'

more_results_text = 'Showing the first %(count)s results. Narrow your search to see more.'

min_length_text = 'Type at least %(count)s characters.'

access_denied_text = "You don't have access to this search."

login_required_text = 'Log in to use this search.'

has_access(request: HttpRequest) → bool

Return whether request may search this lookup.

denied_text(request: HttpRequest) → str

Return the message for a search that has_access refused.

clean_query(query: str) → str

Return the search text for the raw q parameter.

The default strips surrounding whitespace. Override this to keep whitespace that means something to search, such as a leading space.

search(query: str, request: HttpRequest) → Sequence[Any] | QuerySet

Return a sliceable sequence of results matching query.

get_selected(keys: Sequence[str]) → Sequence[Any]

Return the results for keys when rendering a form’s value.

There is no request here, so this must not depend on the current user. Submitted values still have to be validated by the form field.

to_item(result: Any) → Item

Return the Item for a result from search or get_selected.

class izaya.ModelLookup

Bases: Lookup

Lookup over a Django model.

search_fields holds complete text field lookups, such as name__icontains, and a record matches if any of them do. Each one receives the search text as is, so other fields need a search override. key_field names the unique field whose value is submitted, and must match the form field’s to_field_name.

rank_fields optionally names text fields, such as name__unaccent, that put the closest matches first. A record ranks by its best match in any of them: the whole value, the start of the value, the start of a word, then everything else. Ties keep the queryset’s existing order, then fall back to the primary key.

model: type[Model]

search_fields: Sequence[str] = ()

rank_fields: Sequence[str] = ()

key_field = 'pk'

property key_name: str

The name of the field behind key_field, with pk resolved.

get_base_queryset() → QuerySet

Return the records used for labels, such as with select_related applied.

get_queryset(request: HttpRequest) → QuerySet

Return the records request may search.

label(record: Any) → str

Return the text shown for record.

search(query: str, request: HttpRequest) → QuerySet

Return a sliceable sequence of results matching query.

rank(queryset: QuerySet, query: str) → QuerySet

Return queryset with the closest matches to query first.

classmethod spawns_duplicates(fields: Iterable[str]) → bool

Return whether any of fields can match one record through several rows.

get_selected(keys: Sequence[str]) → Sequence[Model]

Return the results for keys when rendering a form’s value.

There is no request here, so this must not depend on the current user. Submitted values still have to be validated by the form field.

to_item(result: Any) → Item

Return the Item for a result from search or get_selected.

class izaya.Item(key: str, label: str)

A result as the templates render it: the submitted key and the visible label.

Widget

class izaya.LookupWidget(lookup: type[Lookup], *, multiple: bool = False, classes: dict[str, str] | None = None, attrs: dict[str, Any] | None = None)

Form widget that picks one or more values from a registered lookup.

lookup is a Lookup subclass decorated with @register. multiple=True selects any number of values, for a multiple choice field. classes maps the widget’s elements to CSS classes, replacing the IZAYA_CLASSES setting’s value for each key it sets.

Settings

IZAYA_CLASSES

A dict mapping the widget’s elements to CSS classes. A widget’s classes= replaces its value for each key it sets. See Styling.

IZAYA_LOGIN_REQUIRED

When True, every lookup denies anonymous searches unless it overrides has_access. Defaults to False. See Private data.

System checks

izaya.E001

A lookup’s rank_fields crosses a to-many relation.

izaya.W001

IZAYA_LOGIN_REQUIRED is set, but AuthenticationMiddleware isn’t in MIDDLEWARE.