The following filters are provided by the Extensions framework </extensions>
as official add-ons to the Filters library.
Note that extension filters are located in a different namespace; use filters.ext
to access them instead of filters
. For example:
import filters as f
# Standard filter
f.Unicode().apply('foo')
# Extension filter - note `f.ext`.
f.ext.Country().apply('pe')
Adds filters for Django-specific features. To install this extension:
pip install filters[django]
Attempts to find a database record that matches the incoming value.
The filter initialiser accepts a few arguments:
model
(required) The Django model that will be queried.field
(optional) The name of the field that will be matched against. If not provided, the default ispk
.
You may also provide "predicates" to the initialiser that will allow you to further filter/customise the query as desired.
Here's an example:
import filters as f
filter_ = f.ext.Model(
# Find a Post record with a ``slug`` that matches the input.
model = Post,
field = 'slug',
# Add predicates to the query.
filter={'published': True},
exclude={'comments__isnull': True'},
select_related=('author', 'comments'),
)
runner = f.FilterRunner(filter_, 'introducing-filters-library')
Any method in QuerySet
can be used as a predicate so long as that method returns a QuerySet
object (e.g., filter
and select_related
are valid predicates, but count
and update
are not).
Refer to the QuerySet API for more information.
Adds filters for interpreting standard codes and identifiers. To install this extension:
pip install filters[iso]
Interprets the incoming value as an ISO 3166-1 alpha-2 or alpha-3 country code.
The resulting value is a :pyiso3166.Country
object (provided by the iso3166 library).
import filters as f
from iso3166 import Country
runner = f.FilterRunner(f.ext.Country, 'nz')
assert runner.is_valid() is True
assert isinstance(runner.cleaned_data, Country) is True
assert runner.cleaned_data.name == 'New Zealand'
assert runner.cleaned_data.alpha2 == 'NZ'
assert runner.cleaned_data.alpha3 == 'NZL'
assert runner.cleaned_data.numeric == '554'
assert runner.cleaned_data.apolitical_name == 'New Zealand'
runner = f.FilterRunner(f.ext.Country, 'nzl')
assert runner.is_valid() is True
assert runner.cleaned_data.name == 'New Zealand'
runner = f.FilterRunner(f.ext.Country, 'xxxx')
assert runner.is_valid() is False
# Only ISO codes are accepted.
runner = f.FilterRunner(f.ext.Country, 'New Zealand')
assert runner.is_valid() is False
Interprets the incoming value as an ISO 4217 currency code.
The resulting value is a :pymoneyed.Currency
object (provided by the py-moneyed library).
import filters as f
from moneyed import Currency
runner = f.FilterRunner(f.ext.Currency, 'nzd')
assert runner.is_valid() is True
assert isinstance(runner.cleaned_data, Currency) is True
assert runner.cleaned_data.name == 'New Zealand Dollar'
runner = f.FilterRunner(f.ext.Currency, 'xxxx')
assert runner.is_valid() is False
# Only ISO codes are accepted.
runner = f.FilterRunner(f.ext.Currency, 'New Zealand Dollar')
assert runner.is_valid() is False
Interprets the incoming value as an IETF Language Tag (also known as BCP 47).
The resulting value is a :pylanguage_tags.Tag.Tag
object (provided by the language_tags library).
import filters as f
from language_tags.Tag import Tag
runner = f.FilterRunner(f.ext.Locale, 'en-nz')
assert runner.is_valid() is True
assert isinstance(runner.cleaned_data, Tag) is True
assert runner.cleaned_data.format == 'en-NZ'
runner = f.FilterRunner(f.ext.Locale, 'xx-XX')
assert runner.is_valid() is False
# Only ISO codes are accepted.
runner = f.FilterRunner(f.ext.Locale, 'English')
assert runner.is_valid() is False