API¶

class filternaut.FilterTree(negate=False, *args, **kwargs)¶

FilterTrees instances are the result of ORing or ANDing Filter instances, or other FilterTree instances, together.

FilterTree provides a simple API for dealing with a set of filters. They may also be iterated over to gain access to the Filter instances directly.

Q¶: A Django “Q” object, built by combining input data with the filter definitions. Cannot be read before parse() has been called.

errors¶

A dictionary of errors met while parsing. The errors are keyed by their field’s source value. Each key’s value is a list of errors.

errors cannot be read before parse() has been called.

parse(data)¶: Ask all filters to look through data and thereby configure themselves.

valid¶: A boolean indicating whether all filters parsed successfully. Cannot be read before parse() has been called.

class filternaut.Filter(dest, **kwargs)¶

A Filter instance builds a django.db.models.Q object by pulling a value from arbitrary native data, e.g. a set of query params.

It can be ORed or ANDed together with other Filter instances in the same way Q objects can.

Q¶: A Django “Q” object, built by combining input data with this filter’s definition. Cannot be read before parse() has been called.

clean(value)¶: Validate and normalise value for use in filtering. This implementation is a no-op; subclasses may do more work here.

default_dest_value_pair()¶: Construct a default dest/value pair to be used if no source data was found during parsing (and if this filter has default=True).

dest_value_pairs(sourcevalue_pairs)¶

Return two values:

A list of two-tuples containing dests (ORM relation/field names) and their values.
A dictionary of errors, keyed by the source which they originated from.

dict¶: A dictionary representation of this Filter’s filter configuration. Cannot be read before parse() has been called.

errors¶: A dictionary of errors (keyed by source) listing any problems encountered during parsing. Typical entries include validation errors and failures to provide values where required. Raises a ValueError if parse() has not been called.

get_source_value(key, data, many=False)¶

Pull key from data.

When many is True, a list of values is returned. Otherwise, a single value is returned.

parse(data)¶

Look through the provided dict-like data for keys which match this Filter’s source. This includes keys containg lookup affixes such as ‘contains’ or ‘lte’.

Once this method has been called, the errors, valid and Q attributes become usable.

source_dest_pairs()¶

For each lookup in self.lookups, such as ‘contains’ or ‘lte’, combine it with this field’s source and dest, returning e.g. (username__contains, account_name__contains)

If any lookup is None, that pair becomes (source, dest)

If there is only one lookup, two pairs are listed containing the source both with and without the lookup. This allows source data to omit the lookup from the key, e.g. providing ‘email’ to the filter Filter(‘email’, lookups=[‘iexact’]).

source_value_pairs(data)¶

Return a list of two-tuples containing valid sources for this filter – made by combining this filter’s source and the various lookups – and their values, as pulled from the data handed to parse.

Sources with no found value are excluded.

tree_class¶

Filters combine into FilterTree instances

alias of FilterTree

valid¶: A boolean indicating whether this Filter registered any errors during parsing. Raises a ValueError if parse() has not been called.

class filternaut.filters.FieldFilter(dest, field, **kwargs)¶

FieldFilters use a django.forms.Field to clean their input value when generating a Q object.

This class is designed to be extended by subclasses which provide their own form-field instances. However, you could use it in combination with a custom field like so:

filter = FieldFilter(SpecialField(), dest=’...’)

class filternaut.drf.FilternautBackend¶

FilternautBackend is a “custom generic filtering backend” for Django REST framework: http://www.django-rest-framework.org/api-guide/filtering/#custom-generic-filtering

It allows straightforward filtering of a view’s queryset using request parameters.

filter_attr = 'filternaut_filters'¶: The host view must define filters at this attribute.

filter_queryset(request, queryset, view)¶: Decide whether to apply the filters defined by view.filternaut_filters on the argued queryset. If the filters parse correctly, is_valid is called. If not, is_invalid is called

is_invalid(request, queryset, filters)¶: Raise a ParseError containing the filter errors. This results in a 400 Bad Request whose body details those errors. Provided for convenience when subclassing.

is_valid(request, queryset, filters)¶: Apply filters to queryset. Provided for convenience when subclassing.