django_ufilter.filtersets.base module¶
- class django_ufilter.filtersets.base.FilterSet(data=None, queryset=None, context=None, strict_mode=None, *args, **kwargs)[source]¶
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 eachin 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 whenFilterSet
is used as a nested filter within anotherFilterSet
.queryset (iterable, optional) – Can be any iterable as supported by the filter backend. Only optional when
FilterSet
is used as a nested filter within anotherFilterSet
.context (dict, optional) – Context for filtering. This is passed to filtering backend. Usually this would consist of passing
request
andview
object from the Django view.strict_mode (str, optional) – Strict mode how
FilterSet
should behave when any validation fails. Seedjango_ufilter.constants.StrictMode
doc for more information. Default isempty
.
- 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()[source]¶
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 providedcreates
LookupConfig
from the provided data (querystring)loops over all configs and attempts to get
FilterSet
for all of theminstantiates 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¶
- filter_options_class¶
Class to be used to construct
Meta
duringFilterSet
class creation time in its metaclass.
- 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 usingBaseFilter.bind()
.See also
- get_filter_backend()[source]¶
Get instantiated filter backend class.
This backend is then used to actually filter queryset.
- get_filters()[source]¶
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)[source]¶
Get
FilterSpec
for the givenLookupConfig
.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
- get_specs()[source]¶
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='')[source]¶
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)[source]¶
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)[source]¶
Bases:
object
Base class for handling options passed to
FilterSet
viaMeta
attribute.
- class django_ufilter.filtersets.base.ModelFilterSetOptions(options=None)[source]¶
Bases:
django_ufilter.filtersets.base.FilterSetOptions
Custom options for
FilterSet
used for model-generated filtersets.- 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
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