Filternaut¶

Examples¶

from filternaut import Filter

user_data = {'username': 'nostromo'}
filters = Filter('username')
filters.parse(user_data)
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE "auth_user"."username" = nostromo

from filternaut.filters import Filter

filters = Filter('username', lookups=['icontains', 'contains'])
filters.parse({'username__icontains': 'nostromo'})
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE "auth_user"."username" LIKE %nostromo%...

filters = Filter('last_login', lookups=['year', 'exact'])

from filternaut.filters import Filter

filters = Filter('email', lookups=['iexact'])

# the lookup can be omitted...
filters.parse({'email': 'Sentence@Case.COM'})

# ...or included
filters.parse({'email__iexact': 'Sentence@Case.COM'})

from filternaut import Filter

user_data = {'email': 'user3@example.org', 'username': 'user3'}
filters = (
    Filter('email') |
    Filter('username') |
    (Filter('first_name') & Filter('last_name')))
filters.parse(user_data)
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE ("auth_user"."email" = user3@example.org OR
       "auth_user"."username" = user3)

user_data = {'first_name': 'Art', 'last_name': 'Vandelay'}
filters.parse(user_data)
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE ("auth_user"."first_name" = Art AND
       "auth_user"."last_name" = Vandelay)

from filternaut.filters import Filter
from django.utils.datastructures import MultiValueDict

filters = Filter(source='groups', dest='groups__name', lookups=['in'])
user_data = MultiValueDict({'groups': ['foo', 'bar']})
filters.parse(user_data)
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE "auth_group"."name" IN (foo, bar)

from filternaut import Filter
filters = Filter(
    source='last_payment',
    dest='order__transaction__created_date',
    lookups=['lt', 'lte', 'gt', 'gte'])

from filternaut import Filter
filters = Filter('is_active', default=True)
filters.parse({})  # no 'is_active'
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE "auth_user"."is_active" = True

from datetime import datetime
from filternaut import Filter
filters = Filter('last_login', lookups=['lte', 'lt', 'gt', 'gte'],
                 default=datetime.now(), default_lookup='lte')
filters.parse({})  # no 'last_login'
print(User.objects.filter(filters.Q).query)

SELECT "auth_user"."id", ...
WHERE "auth_user"."last_login" <= ...

from filternaut import Filter

filters = Filter('username', required=True)
filters.parse({})  # no 'username'

print(filters.valid)
print(filters.errors)

False
{'username': ['This field is required']}

from filternaut import Filter, Optional

filters = (
   Optional(
      Filter('first_name', required=True),
      Filter('middle_name'),
      Filter('last_name', required=True)) &
   Filter('badgers_defeated'))

filters.parse({'first_name': 'Nostromo'})
print(filters.errors['__all__'])
print(filters.errors['last_name'])

['If any of first_name, last_name, middle_name are provided,
  all must be provided']
['This field is required']

filters.parse({'middle_name': 'Boone'})
print(filters.errors['__all__'])
print(filters.errors['first_name'])
print(filters.errors['last_name'])

['If any of first_name, last_name, middle_name are provided,
  all must be provided']
['This field is required']
['This field is required']

filters.parse({
   'first_name': 'Nostromo',
   'last_name': 'Cheradenine'})
assert filters.valid

filters.parse({})
assert filters.valid

from django.forms import DateTimeField
from filternaut.filters import FieldFilter

filters = FieldFilter('signup_date', field=DateTimeField())
filters.parse({'signup_date': 'potato'})

print(filters.valid)
print(filters.errors)

False
{'signup_date': ['Enter a valid date/time.']}

from filternaut.filters import ChoiceFilter

difficulties = [(4, 'Torment I'), (5, 'Torment II')]
filters = ChoiceFilter('difficulty', choices=difficulties)
filters.parse({'difficulty': 'foo'})

print(filters.valid)
print(filters.errors)

False
{'difficulty': ['Select a valid choice. foo is not ...']}

from filternaut.filters import CharFilter, EmailFilter
from rest_framework import generics

class UserListView(generics.ListAPIView):
    model = User

    def filter_queryset(self, queryset):
        filters = CharFilter('username') | EmailFilter('email')
        filters.parse(self.request.query_params)
        queryset = super(UserListView, self).filter_queryset(queryset)
        return queryset.filter(filters.Q)

from filternaut.drf import FilternautBackend
from filternaut.filters import CharFilter, EmailFilter
from rest_framework import views

class MyView(views.APIView):
    filter_backends = (FilternautBackend, )
    filternaut_filters = CharFilter('username') | EmailFilter('email')

from rest_framework import views

class MyView(views.APIView):
    filter_backends = (FilternautBackend, )

    def filternaut_filters(self, request):
        choices = ['guest', 'developer']
        if request.user.is_staff:
            choices.append('manager')
        return ChoiceFilter('account_type', choices=enumerate(choices))

API¶

class filternaut.FilterTree(negate=False, *args, **kwargs)¶

FilterTrees instances are the result of ORing or ANDing Filter instances, or other FilterTree instances, together.

FilterTree provides a simple API for dealing with a set of filters. They may also be iterated over to gain access to the Filter instances directly.

Q¶

A Django “Q” object, built by combining input data with the filter definitions. Cannot be read before parse() has been called.

errors¶

A dictionary of errors met while parsing. The errors are keyed by their field’s source value. Each key’s value is a list of errors.

errors cannot be read before parse() has been called.

parse(data)¶

Ask all filters to look through data and thereby configure themselves.

valid¶

A boolean indicating whether all filters parsed successfully. Cannot be read before parse() has been called.

class filternaut.Filter(dest, **kwargs)¶

A Filter instance builds a django.db.models.Q object by pulling a value from arbitrary native data, e.g. a set of query params.

It can be ORed or ANDed together with other Filter instances in the same way Q objects can.

Q¶

A Django “Q” object, built by combining input data with this filter’s definition. Cannot be read before parse() has been called.

clean(value)¶

Validate and normalise value for use in filtering. This implementation is a no-op; subclasses may do more work here.

default_dest_value_pair()¶

Construct a default dest/value pair to be used if no source data was found during parsing (and if this filter has default=True).

dest_value_pairs(sourcevalue_pairs)¶

Return two values:

• A list of two-tuples containing dests (ORM relation/field names) and their values.
• A dictionary of errors, keyed by the source which they originated from.

dict¶

A dictionary representation of this Filter’s filter configuration. Cannot be read before parse() has been called.

errors¶

A dictionary of errors (keyed by source) listing any problems encountered during parsing. Typical entries include validation errors and failures to provide values where required. Raises a ValueError if parse() has not been called.

get_source_value(key, data, many=False)¶

Pull key from data.

When many is True, a list of values is returned. Otherwise, a single value is returned.

parse(data)¶

Look through the provided dict-like data for keys which match this Filter’s source. This includes keys containg lookup affixes such as ‘contains’ or ‘lte’.

Once this method has been called, the errors, valid and Q attributes become usable.

source_dest_pairs()¶

For each lookup in self.lookups, such as ‘contains’ or ‘lte’, combine it with this field’s source and dest, returning e.g. (username__contains, account_name__contains)

If any lookup is None, that pair becomes (source, dest)

If there is only one lookup, two pairs are listed containing the source both with and without the lookup. This allows source data to omit the lookup from the key, e.g. providing ‘email’ to the filter Filter(‘email’, lookups=[‘iexact’]).

source_value_pairs(data)¶

Return a list of two-tuples containing valid sources for this filter – made by combining this filter’s source and the various lookups – and their values, as pulled from the data handed to parse.

Sources with no found value are excluded.

tree_class¶

Filters combine into FilterTree instances

alias of FilterTree

valid¶

A boolean indicating whether this Filter registered any errors during parsing. Raises a ValueError if parse() has not been called.

class filternaut.filters.FieldFilter(dest, field, **kwargs)¶

FieldFilters use a django.forms.Field to clean their input value when generating a Q object.

This class is designed to be extended by subclasses which provide their own form-field instances. However, you could use it in combination with a custom field like so:

filter = FieldFilter(SpecialField(), dest=’...’)

class filternaut.drf.FilternautBackend¶

FilternautBackend is a “custom generic filtering backend” for Django REST framework: http://www.django-rest-framework.org/api-guide/filtering/#custom-generic-filtering

It allows straightforward filtering of a view’s queryset using request parameters.

filter_attr = 'filternaut_filters'¶

The host view must define filters at this attribute.

filter_queryset(request, queryset, view)¶

Decide whether to apply the filters defined by view.filternaut_filters on the argued queryset. If the filters parse correctly, is_valid is called. If not, is_invalid is called

is_invalid(request, queryset, filters)¶

Raise a ParseError containing the filter errors. This results in a 400 Bad Request whose body details those errors. Provided for convenience when subclassing.

is_valid(request, queryset, filters)¶

Apply filters to queryset. Provided for convenience when subclassing.

Tests¶

First, install the extra dependencies:

$ pip install -r requirements/maintainer.txt

You can run the test suite in a specific environment via tox. In this example, against Python 2.7 and Django 1.4. (Hint: try tox -l for a full list).

$ tox -e py27-dj14

The full set of environments can be run by providing no arguments to tox. If it’s the first time, consider opening a beer.

$ tox

Finally, you can run the test suite without tox if you prefer. You will need to manually install additional dependencies if you choose to do this.

$ nosetests tests