djangorestframework-filters 0.3.1

Chaining filtering through relations

To enable chained filtering through relations:

from rest_framework import viewsets
import rest_framework_filters as filters

class UserFilter(filters.FilterSet):
    username = filters.CharFilter(name='username')
    ...

class PageFilter(filters.FilterSet):
    title = filters.CharFilter(name='title')
    author = filters.RelatedFilter(UserFilter, name='author')
    ...

# Then just use the PageFilter as you would any other FilterSet:

class PageView(viewsets.ModelViewSet):
    ...
    filter_class = PageFilter

then we can automatically chain our filters through the author relation, as so:

/api/page/?author__username=philipn

Allowing any lookup type on a field

We can use the AllLookupsFilter to allow all possible lookup types on a particular field. While we could otherwise specify these by hand, e.g.:

class ProductFilter(filters.FilterSet):
    min_price = filters.NumberFilter(name="price", lookup_type='gte')
    ...

to allow the price__gte lookup. But this gets cumbersome, and we sometimes want to allow any possible lookups on particular fields. We do this by using AllLookupsFilter:

from rest_framework import viewsets
import rest_framework_filters as filters

class PageFilter(filters.FilterSet):
    title = filters.AllLookupsFilter(name='title')
    ...

then we can use any possible lookup on the title field, e.g.:

/api/page/?title__icontains=park

or

/api/page/?title__startswith=The

and also filter on the default lookup (exact), as usual:

/api/page/?title=The%20Park

Combining RelatedFilter and AllLookupsFilter

We can combine RelatedFilter and AllLookupsFilter:

from rest_framework import viewsets
import rest_framework_filters as filters

class PageFilter(filters.FilterSet):
    title = filters.CharFilter(name='title')
    author = filters.RelatedFilter(UserFilter, name='author')

class UserFilter(filters.FilterSet):
    username = AllLookupsFilter(name='username')
    ...

then we can filter like so:

/api/page/?author__username__icontains=john

DjangoFilterBackend

We implement our own subclass of DjangoFilterBackend, which you should probably use instead of the default DjangoFilterBackend. Our DjangoFilterBackend caches repeated filter set generation — a particularly important optimization when using RelatedFilter and AllLookupsFilter.

To use our FilterBackend, in your settings.py`, simply use:

REST_FRAMEWORK = {
    ...
    'DEFAULT_FILTER_BACKENDS': (
        'rest_framework_filters.backends.DjangoFilterBackend', ...
    ),

instead of the default rest_framework.filters.DjangoFilterBackend.

What warts are fixed?

Even if you’re not using RelatedFilter or AllLookupsFilter, you will probably want to use django-rest-framework-filters. For instance, if you simply use django-filter it is very difficult to filter on a DateTimeFilter in the date format emitted by the default serializer (ISO 8601), which makes working with your API difficult.

Can I mix and match django-filter and django-rest-framework-filters?

Yes you can. django-rest-framework-filters extends django-filter, and you can mix and match them as you please. For a given class, you should use only one of django-filter or django-rest-framework-filters, but you can use RelatedFilter to link to a filter relation defined elsewhere that uses vanilla django-filter.

More information on RelatedFilter

Recursive relations are supported. You will need to specify the full module path in the RelatedFilter definition in some cases, e.g.:

class PersonFilter(filters.FilterSet):
    name = filters.AllLookupsFilter(name='name')
    best_friend = filters.RelatedFilter('people.views.PersonFilter', name='best_friend')

    class Meta:
        model = Person