diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api-guide/filtering.md | 69 | ||||
| -rw-r--r-- | docs/index.md | 2 |
2 files changed, 62 insertions, 9 deletions
diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index ca901b03..e49ea420 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -30,7 +30,7 @@ For example: for the currently authenticated user. """ user = self.request.user - return Purchase.objects.filter(purchaser=user) + return Purchase.objects.filter(purchaser=user) ## Filtering against the URL @@ -96,27 +96,76 @@ You must also set the filter backend to `DjangoFilterBackend` in your settings: **Note**: The currently supported version of `django-filter` is the `master` branch. A PyPI release is expected to be coming soon. +## Specifying filter fields + +If all you need is simple equality-based filtering, you can set a `filter_fields` attribute on the view, listing the set of fields you wish to filter against. + + class ProductList(generics.ListAPIView): + model = Product + serializer_class = ProductSerializer + filter_fields = ('category', 'in_stock') + +This will automatically create a `FilterSet` class for the given fields, and will allow you to make requests such as: + + http://example.com/api/products?category=clothing&in_stock=True + ## Specifying a FilterSet -**TODO**: Document setting `.filter_class` on the view. +For more advanced filtering requirements you can specify a `FilterSet` class that should be used by the view. For example: -**TODO**: Note support for `lookup_type`, double underscore relationship spanning, and ordering. + class ProductFilter(django_filters.FilterSet): + min_price = django_filters.NumberFilter(lookup_type='gte') + max_price = django_filters.NumberFilter(lookup_type='lte') + class Meta: + model = Product + fields = ['category', 'in_stock', 'min_price', 'max_price'] -## Specifying filter fields + class ProductList(generics.ListAPIView): + model = Product + serializer_class = ProductSerializer + filter_class = ProductFilter -**TODO**: Document setting `.filter_fields` on the view. +Which will allow you to make requests such as: -**TODO**: Note that overiding `get_queryset()` can be used together with generic filtering + http://example.com/api/products?category=clothing&max_price=10.00 +For more details on using filter sets see the [django-filter documentation][django-filter-docs]. + +--- + +**Hints & Tips** + +* By default filtering is not enabled. If you want to use `DjangoFilterBackend` remember to make sure it is installed by using the `'FILTER_BACKEND'` setting. +* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`. (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].) +* `django-filter` supports filtering across relationships, using Django's double-underscore syntax. + +--- + +## Overriding the intial queryset + +Note that you can use both an overridden `.get_queryset()` and generic filtering together, and everything will work as expected. For example, if `Product` had a many-to-many relationship with `User`, named `purchase`, you might want to write a view like this: + + class PurchasedProductsList(generics.ListAPIView): + """ + Return a list of all the products that the authenticated + user has ever purchased, with optional filtering. + """ + model = Product + serializer_class = ProductSerializer + filter_class = ProductFilter + + def get_queryset(self): + user = self.request.user + return user.purchase_set.all() --- # Custom generic filtering You can also provide your own generic filtering backend, or write an installable app for other developers to use. -To do so overide `BaseFilterBackend`, and override the `.filter_queryset(self, request, queryset, view)` method. +To do so override `BaseFilterBackend`, and override the `.filter_queryset(self, request, queryset, view)` method. -To install the filter, set the `'FILTER_BACKEND'` key in your `'REST_FRAMEWORK'` setting, using the dotted import path of the filter backend class. +To install the filter backend, set the `'FILTER_BACKEND'` key in your `'REST_FRAMEWORK'` setting, using the dotted import path of the filter backend class. For example: @@ -125,4 +174,6 @@ For example: } [cite]: https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-specific-objects-with-filters -[django-filter]: https://github.com/alex/django-filter
\ No newline at end of file +[django-filter]: https://github.com/alex/django-filter +[django-filter-docs]: https://django-filter.readthedocs.org/en/latest/index.html +[nullbooleanselect]: https://github.com/django/django/blob/master/django/forms/widgets.py
\ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 52ea2b75..1874ec00 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,6 +34,7 @@ The following packages are optional: * [Markdown][markdown] (2.1.0+) - Markdown support for the self describing API. * [PyYAML][yaml] (3.10+) - YAML content-type support. +* [django-filter][django-filter] (master) - Filtering support. ## Installation @@ -163,6 +164,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ [yaml]: http://pypi.python.org/pypi/PyYAML +[django-filter]: https://github.com/alex/django-filter [0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X [image]: img/quickstart.png [sandbox]: http://restframework.herokuapp.com/ |