django_ufilter.filtersets.base module

class django_ufilter.filtersets.base.FilterSet(data=None, queryset=None, context=None, strict_mode=None, *args, **kwargs)

Bases: django_ufilter.filters.BaseFilter

Main user-facing classes to use filtersets.

It 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 attempts to get FilterSpec for each

• in the process, it delegates the job of constructing spec to child filters when any match is found between filter defined on the filter and lookup name in the config

Parameters

• data (QueryDict, optional) – QueryDict of querystring data. Only optional when FilterSet is used as 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 as 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 django_ufilter.constants.StrictMode doc for more information. Default is empty.

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.

default_strict_mode = 'empty'

Default strict mode which should be used when one is not provided in initialization.

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 from the provided data (querystring)

• loops over all configs and attempts to get FilterSet 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 django_ufilter.backends.django.DjangoFilterBackend

filter_options_class

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

alias of django_ufilter.filtersets.base.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 filterset by using BaseFilter.bind().

See also

get_filters, BaseFilter.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 method is meant to be used as a hook in subclasses in order to enhance functionality such as automatically adding filters from model fields.

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 list of FilterSpec for the given querystring data.

This function does:

• unpacks the querystring data to a list of LookupConfig

• loops through all configs and uses appropriate children filters to generate list of FilterSpec

• if any validations fails while generating specs, all errors are collected and depending on strict_mode it re-raises the errors or ignores them.

Returns

List of FilterSpec

Return type

list

repr(prefix='')

Custom representation of the filterset

Parameters

prefix (str) – Prefix with which each line of the representation should be prefixed with. This allows to recursively get the representation of all descendants with correct indentation (children are indented compared to parent)

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.

Useful to filter out invalid filter querystring pairs since not whole querystring is not dedicated for filter purposes but could contain other information such as pagination information. In that case if the key is invalid key for filtering, we can simply ignore it without wasting time trying to get filter specification for it.

Parameters

key (str) – Key as provided in the querystring

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

Bases: object

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

class django_ufilter.filtersets.base.ModelFilterSetOptions(options=None)

Bases: django_ufilter.filtersets.base.FilterSetOptions

Custom options for FilterSet used for model-generated filtersets.

model

Model class from which FilterSet will extract necessary filters.

Type

Model

fields

Specific model fields for which filters should be created for. By default it is None in which case for all fields filters will be created for.

Type

None, list, optional

exclude

Specific model fields for which filters should not be created for.

Type

list, optional

allow_related

Whether related/nested fields should be allowed when model fields are automatically determined (e.g. when explicit fields is not provided).

Type

bool, optional

extra_kwargs

Additional kwargs to be given to auto-generated individual filters

Type

dict, optional