Official Extensions

The following filters are provided by the Extensions framework 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')

Django Filters

Adds filters for Django-specific features. To install this extension:

pip install filters[django]

Model

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 is pk.

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.

ISO Filters

Adds filters for interpreting standard codes and identifiers. To install this extension:

pip install filters[iso]

Country

Interprets the incoming value as an ISO 3166-1 alpha-2 or alpha-3 country code.

The resulting value is a iso3166.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

Currency

Interprets the incoming value as an ISO 4217 currency code.

The resulting value is a moneyed.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

Locale

Interprets the incoming value as an IETF Language Tag (also known as BCP 47).

The resulting value is a language_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