Skip to content

Commit 2395fb5

Browse files
tomchristietomchristie
authored
Deprecate DjangoFilter backend (encode#4593)
Deprecate the built-in `rest_framework.filters.DjangoFilterBackend` in favour of the third-party `django_filters.rest_framework.DjangoFilterBackend`.
1 parent 3f6004c commit 2395fb5

File tree

4 files changed

+83
-121
lines changed

4 files changed

+83
-121
lines changed

‎docs/api-guide/filtering.md

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -89,24 +89,24 @@ Generic filters can also present themselves as HTML controls in the browsable AP
8989

9090
## Setting filter backends
9191

92-
The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting. For example.
92+
The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting. For example.
9393

9494
REST_FRAMEWORK = {
95-
'DEFAULT_FILTER_BACKENDS': ('rest_framework.filters.DjangoFilterBackend',)
95+
'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
9696
}
9797

9898
You can also set the filter backends on a per-view, or per-viewset basis,
9999
using the `GenericAPIView` class-based views.
100100

101+
import django_filters
101102
from django.contrib.auth.models import User
102103
from myapp.serializers import UserSerializer
103-
from rest_framework import filters
104104
from rest_framework import generics
105105

106106
class UserListView(generics.ListAPIView):
107107
queryset = User.objects.all()
108108
serializer_class = UserSerializer
109-
filter_backends = (filters.DjangoFilterBackend,)
109+
filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)
110110

111111
## Filtering and object lookups
112112

@@ -139,12 +139,27 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering
139139

140140
## DjangoFilterBackend
141141

142-
The `DjangoFilterBackend` class supports highly customizable field filtering, using the [django-filter package][django-filter].
142+
The `django-filter` library includes a `DjangoFilterBackend` class which
143+
supports highly customizable field filtering for REST framework.
143144

144-
To use REST framework's `DjangoFilterBackend`, first install `django-filter`.
145+
To use `DjangoFilterBackend`, first install `django-filter`.
145146

146147
pip install django-filter
147148

149+
You should now either add the filter backend to your settings:
150+
151+
REST_FRAMEWORK = {
152+
'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
153+
}
154+
155+
Or add the filter backend to an individual View or ViewSet.
156+
157+
from django_filters.rest_framework import DjangoFilterBackend
158+
159+
class UserListView(generics.ListAPIView):
160+
...
161+
filter_backends = (DjangoFilterBackend,)
162+
148163
If you are using the browsable API or admin API you may also want to install `django-crispy-forms`, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML.
149164

150165
pip install django-crispy-forms
@@ -174,10 +189,9 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
174189
import django_filters
175190
from myapp.models import Product
176191
from myapp.serializers import ProductSerializer
177-
from rest_framework import filters
178192
from rest_framework import generics
179193

180-
class ProductFilter(filters.FilterSet):
194+
class ProductFilter(django_filters.rest_framework.FilterSet):
181195
min_price = django_filters.NumberFilter(name="price", lookup_expr='gte')
182196
max_price = django_filters.NumberFilter(name="price", lookup_expr='lte')
183197
class Meta:
@@ -187,7 +201,7 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
187201
class ProductList(generics.ListAPIView):
188202
queryset = Product.objects.all()
189203
serializer_class = ProductSerializer
190-
filter_backends = (filters.DjangoFilterBackend,)
204+
filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)
191205
filter_class = ProductFilter
192206

193207

@@ -199,12 +213,12 @@ You can also span relationships using `django-filter`, let's assume that each
199213
product has foreign key to `Manufacturer` model, so we create filter that
200214
filters using `Manufacturer` name. For example:
201215

216+
import django_filters
202217
from myapp.models import Product
203218
from myapp.serializers import ProductSerializer
204-
from rest_framework import filters
205219
from rest_framework import generics
206220

207-
class ProductFilter(filters.FilterSet):
221+
class ProductFilter(django_filters.rest_framework.FilterSet):
208222
class Meta:
209223
model = Product
210224
fields = ['category', 'in_stock', 'manufacturer__name']
@@ -218,10 +232,9 @@ This is nice, but it exposes the Django's double underscore convention as part o
218232
import django_filters
219233
from myapp.models import Product
220234
from myapp.serializers import ProductSerializer
221-
from rest_framework import filters
222235
from rest_framework import generics
223236

224-
class ProductFilter(filters.FilterSet):
237+
class ProductFilter(django_filters.rest_framework.FilterSet):
225238
manufacturer = django_filters.CharFilter(name="manufacturer__name")
226239

227240
class Meta:
@@ -454,4 +467,3 @@ The [djangorestframework-word-filter][django-rest-framework-word-search-filter]
454467
[django-rest-framework-word-search-filter]: https://github.com/trollknurr/django-rest-framework-word-search-filter
455468
[django-url-filter]: https://github.com/miki725/django-url-filter
456469
[drf-url-filter]: https://github.com/manjitkumar/drf-url-filters
457-

‎requirements/requirements-optionals.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Optional packages which may be used with REST framework.
22
markdown==2.6.4
33
django-guardian==1.4.6
4-
django-filter==0.14.0
4+
django-filter==0.15.3
55
coreapi==2.0.8

‎rest_framework/filters.py

Lines changed: 22 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
from __future__ import unicode_literals
66

77
import operator
8+
import warnings
89
from functools import reduce
910

10-
from django.conf import settings
1111
from django.core.exceptions import ImproperlyConfigured
1212
from django.db import models
1313
from django.db.models.constants import LOOKUP_SEP
@@ -16,50 +16,10 @@
1616
from django.utils.translation import ugettext_lazy as _
1717

1818
from rest_framework.compat import (
19-
coreapi, crispy_forms, distinct, django_filters, guardian, template_render
19+
coreapi, distinct, django_filters, guardian, template_render
2020
)
2121
from rest_framework.settings import api_settings
2222

23-
if 'crispy_forms' in settings.INSTALLED_APPS and crispy_forms and django_filters:
24-
# If django-crispy-forms is installed, use it to get a bootstrap3 rendering
25-
# of the DjangoFilterBackend controls when displayed as HTML.
26-
from crispy_forms.helper import FormHelper
27-
from crispy_forms.layout import Layout, Submit
28-
29-
class FilterSet(django_filters.FilterSet):
30-
def __init__(self, *args, **kwargs):
31-
super(FilterSet, self).__init__(*args, **kwargs)
32-
for field in self.form.fields.values():
33-
field.help_text = None
34-
35-
layout_components = list(self.form.fields.keys()) + [
36-
Submit('', _('Submit'), css_class='btn-default'),
37-
]
38-
39-
helper = FormHelper()
40-
helper.form_method = 'GET'
41-
helper.template_pack = 'bootstrap3'
42-
helper.layout = Layout(*layout_components)
43-
44-
self.form.helper = helper
45-
46-
filter_template = 'rest_framework/filters/django_filter_crispyforms.html'
47-
48-
elif django_filters:
49-
# If django-crispy-forms is not installed, use the standard
50-
# 'form.as_p' rendering when DjangoFilterBackend is displayed as HTML.
51-
class FilterSet(django_filters.FilterSet):
52-
def __init__(self, *args, **kwargs):
53-
super(FilterSet, self).__init__(*args, **kwargs)
54-
for field in self.form.fields.values():
55-
field.help_text = None
56-
57-
filter_template = 'rest_framework/filters/django_filter.html'
58-
59-
else:
60-
FilterSet = None
61-
filter_template = None
62-
6323

6424
class BaseFilterBackend(object):
6525
"""
@@ -77,78 +37,34 @@ def get_schema_fields(self, view):
7737
return []
7838

7939

40+
class FilterSet(object):
41+
def __new__(cls, *args, **kwargs):
42+
warnings.warn(
43+
"The built in 'rest_framework.filters.FilterSet' is pending deprecation. "
44+
"You should use 'django_filters.rest_framework.FilterSet' instead.",
45+
PendingDeprecationWarning
46+
)
47+
from django_filters.rest_framework import FilterSet
48+
return FilterSet(*args, **kwargs)
49+
50+
8051
class DjangoFilterBackend(BaseFilterBackend):
8152
"""
8253
A filter backend that uses django-filter.
8354
"""
84-
default_filter_set = FilterSet
85-
template = filter_template
86-
87-
def __init__(self):
55+
def __new__(cls, *args, **kwargs):
8856
assert django_filters, 'Using DjangoFilterBackend, but django-filter is not installed'
57+
assert django_filters.VERSION >= (0, 15, 3), 'django-filter 0.15.3 and above is required'
8958

90-
def get_filter_class(self, view, queryset=None):
91-
"""
92-
Return the django-filters `FilterSet` used to filter the queryset.
93-
"""
94-
filter_class = getattr(view, 'filter_class', None)
95-
filter_fields = getattr(view, 'filter_fields', None)
96-
97-
if filter_class:
98-
filter_model = filter_class.Meta.model
99-
100-
assert issubclass(queryset.model, filter_model), \
101-
'FilterSet model %s does not match queryset model %s' % \
102-
(filter_model, queryset.model)
103-
104-
return filter_class
105-
106-
if filter_fields:
107-
class AutoFilterSet(self.default_filter_set):
108-
class Meta:
109-
model = queryset.model
110-
fields = filter_fields
59+
warnings.warn(
60+
"The built in 'rest_framework.filters.DjangoFilterBackend' is pending deprecation. "
61+
"You should use 'django_filters.rest_framework.DjangoFilterBackend' instead.",
62+
PendingDeprecationWarning
63+
)
11164

112-
return AutoFilterSet
65+
from django_filters.rest_framework import DjangoFilterBackend
11366

114-
return None
115-
116-
def filter_queryset(self, request, queryset, view):
117-
filter_class = self.get_filter_class(view, queryset)
118-
119-
if filter_class:
120-
return filter_class(request.query_params, queryset=queryset).qs
121-
122-
return queryset
123-
124-
def to_html(self, request, queryset, view):
125-
filter_class = self.get_filter_class(view, queryset)
126-
if not filter_class:
127-
return None
128-
filter_instance = filter_class(request.query_params, queryset=queryset)
129-
context = {
130-
'filter': filter_instance
131-
}
132-
template = loader.get_template(self.template)
133-
return template_render(template, context)
134-
135-
def get_schema_fields(self, view):
136-
assert coreapi is not None, 'coreapi must be installed to use `get_schema_fields()`'
137-
filter_class = getattr(view, 'filter_class', None)
138-
if filter_class:
139-
return [
140-
coreapi.Field(name=field_name, required=False, location='query')
141-
for field_name in filter_class().filters.keys()
142-
]
143-
144-
filter_fields = getattr(view, 'filter_fields', None)
145-
if filter_fields:
146-
return [
147-
coreapi.Field(name=field_name, required=False, location='query')
148-
for field_name in filter_fields
149-
]
150-
151-
return []
67+
return DjangoFilterBackend(*args, **kwargs)
15268

15369

15470
class SearchFilter(BaseFilterBackend):

‎tests/test_filters.py

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import datetime
44
import unittest
5+
import warnings
56
from decimal import Decimal
67

78
from django.conf.urls import url
@@ -134,6 +135,39 @@ class IntegrationTestFiltering(CommonFilteringTestCase):
134135
Integration tests for filtered list views.
135136
"""
136137

138+
@unittest.skipUnless(django_filters, 'django-filter not installed')
139+
def test_backend_deprecation(self):
140+
with warnings.catch_warnings(record=True) as w:
141+
warnings.simplefilter("always")
142+
143+
view = FilterFieldsRootView.as_view()
144+
request = factory.get('/')
145+
response = view(request).render()
146+
147+
self.assertEqual(response.status_code, status.HTTP_200_OK)
148+
self.assertEqual(response.data, self.data)
149+
150+
self.assertTrue(issubclass(w[-1].category, PendingDeprecationWarning))
151+
self.assertIn("'rest_framework.filters.DjangoFilterBackend' is pending deprecation.", str(w[-1].message))
152+
153+
@unittest.skipUnless(django_filters, 'django-filter not installed')
154+
def test_no_df_deprecation(self):
155+
with warnings.catch_warnings(record=True) as w:
156+
warnings.simplefilter("always")
157+
158+
import django_filters.rest_framework
159+
160+
class DFFilterFieldsRootView(FilterFieldsRootView):
161+
filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)
162+
163+
view = DFFilterFieldsRootView.as_view()
164+
request = factory.get('/')
165+
response = view(request).render()
166+
167+
self.assertEqual(response.status_code, status.HTTP_200_OK)
168+
self.assertEqual(response.data, self.data)
169+
self.assertEqual(len(w), 0)
170+
137171
@unittest.skipUnless(django_filters, 'django-filter not installed')
138172
def test_get_filtered_fields_root_view(self):
139173
"""

0 commit comments

Comments
 (0)