url_filter.filtersets.base module

class url_filter.filtersets.base.FilterSet(source=None, *args, **kwargs)

Bases: url_filter.filters.Filter

Main user-facing classes to use filtersets.

FilterSet primarily does:

• takes queryset to filter
• takes querystring data which will be used to filter given queryset
• from the querystring, it constructs a list of LookupConfig
• loops over the created configs and attemps to get FilterSpec for each
• in the process, if delegates the job of constructing spec to child filters when any match is found between filter defined on the filter and name in the config

Parameters:

• source (str) – Name of the attribute for which which filter applies to within the model of the queryset to be filtered as given to the FilterSet.
• data (QueryDict, optional) – QueryDict of querystring data. Only optional when FilterSet is used a nested filter within another FilterSet.
• queryset (iterable, optional) – Can be any iterable as supported by the filter backend. Only optional when FilterSet is used a nested filter within another FilterSet.
• context (dict, optional) – Context for filtering. This is passed to filtering backend. Usually this would consist of passing request and view object from the Django view.
• strict_mode (str, optional) – Strict mode how FilterSet should behave when any validation fails. See StrictMode doc for more information. Default is drop.

filter_backend_class

Class to be used as filter backend. By default DjangoFilterBackend is used.

filter_options_class

Class to be used to construct Meta during FilterSet class creation time in its metalclass.

default_filter

Cached property for looking up default filter. Default filter is a filter which is defined with is_default=True. Useful when lookup config references nested filter without specifying which field to filter. In that case default filter will be used.

filter()

Main method which should be used on root FilterSet to filter queryset.

This method:

• asserts that filtering is being done on root FilterSet and that all necessary data is provided
• creates ``LookupConfig``s from the provided data (querystring)
• loops over all configs and attemps to get FilterSpec for all of them
• instantiates filter backend
• uses the created filter specs to filter queryset by using specs

Returns:Filtered queryset Return type:querystring

filter_backend

Property for getting instantiated filter backend.

Primarily useful when accessing filter_backend outside of the filterset such as leaf filters or integration layers since backend has useful information for both of those examples.

filter_backend_class

alias of DjangoFilterBackend

filter_options_class

alias of FilterSetOptions

filters

Cached property for accessing filters available in this filteset. In addition to getting filters via get_filters, this property binds all filters to the filtset by using bind.

See also

get_filters, bind

get_filter_backend()

Get instantiated filter backend class.

This backend is then used to actually filter queryset.

get_filters()

Get all filters defined in this filterset. By default only declared filters are returned however this methoc can be used a hook to customize that.

get_spec(config)

Get FilterSpec for the given LookupConfig.

If the config is non leaf config (it has more nested fields), then the appropriate matching child filter is used to get the spec. If the config however is a leaf config, then default_filter is used to get the spec, when available, and if not, this filter is skipped.

Parameters:config (LookupConfig) – Config for which to generate FilterSpec Returns:Individual filter spec Return type:FilterSpec

get_specs()

Get FilterSpecs for the given querystring data.

This function does:

• unpacks the querystring data to ``LookupConfig``s
• loops throught all configs and uses appropriate children filters to generate ``FilterSpec``s
• if any validations fails while generating specs, all errors are collected and depending on strict_mode it reraises the errors or ignores them.

Returns:List of ``FilterSpec``s Return type:list

repr(prefix=u'')

validate_key(key)

Validate that LookupConfig key is correct.

This is the key as provided in the querystring. Currently key is validated against a regex expression.

class url_filter.filtersets.base.FilterSetOptions(options=None)

Bases: object

Base class for handling options passed to FilterSet via Meta attribute.

class url_filter.filtersets.base.StrictMode

Bases: enum.Enum

Strictness mode enum.

Drop (default) (default):  ignores all filter failures. when any occur, FilterSet simply then does not filter provided queryset. Fail:when validation fails for any filter within FilterSet, all error are compiled and cumulative ValidationError is raised.

drop = <StrictMode.drop: u'drop'>

fail = <StrictMode.fail: u'fail'>