From fcde2199280145bcf3420dbba6a9efced6a7e9b8 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Mon, 4 Mar 2019 14:47:54 +0100 Subject: [PATCH] Deployed ac7b20cc with MkDocs version: 0.16.3 --- api-guide/filtering/index.html | 11 +-- mkdocs/search_index.json | 4 +- sitemap.xml | 128 ++++++++++++++++----------------- 3 files changed, 73 insertions(+), 70 deletions(-) diff --git a/api-guide/filtering/index.html b/api-guide/filtering/index.html index 971dcb6a7..ea557aed6 100644 --- a/api-guide/filtering/index.html +++ b/api-guide/filtering/index.html @@ -687,10 +687,13 @@ class UserListView(generics.ListAPIView):

By default, the search parameter is named 'search', but this may be overridden with the SEARCH_PARAM setting.

To dynamically change search fields based on request content, it's possible to subclass the SearchFilter and override the get_search_fields() function. For example, the following subclass will only search on title if the query parameter title_only is in the request:

-
class CustomSearchFilter(self, view, request):
-    if request.query_params.get('title_only'):
-        return ('title',)
-    return super(CustomSearchFilter, self).get_search_fields(view, request)
+
from rest_framework import filters
+
+class CustomSearchFilter(filters.SearchFilter):
+    def get_search_fields(self, view, request):
+        if request.query_params.get('title_only'):
+            return ('title',)
+        return super(CustomSearchFilter, self).get_search_fields(view, request)
 

 
For more details, see the Django documentation.

 

diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index fcc4a1cdc..257b4e1e8 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -2707,7 +2707,7 @@
         },
         {
             "location": "/api-guide/filtering/",
-            "text": "Filtering\n\n\n\n\nThe root QuerySet provided by the Manager describes all objects in the database table.  Usually, though, you'll need to select only a subset of the complete set of objects.\n\n\n\u2014 \nDjango documentation\n\n\n\n\nThe default behavior of REST framework's generic list views is to return the entire queryset for a model manager.  Often you will want your API to restrict the items that are returned by the queryset.\n\n\nThe simplest way to filter the queryset of any view that subclasses \nGenericAPIView\n is to override the \n.get_queryset()\n method.\n\n\nOverriding this method allows you to customize the queryset returned by the view in a number of different ways.\n\n\nFiltering against the current user\n\n\nYou might want to filter the queryset to ensure that only results relevant to the currently authenticated user making the request are returned.\n\n\nYou can do so by filtering based on the value of \nrequest.user\n.\n\n\nFor example:\n\n\nfrom myapp.models import Purchase\nfrom myapp.serializers import PurchaseSerializer\nfrom rest_framework import generics\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        This view should return a list of all the purchases\n        for the currently authenticated user.\n        \"\"\"\n        user = self.request.user\n        return Purchase.objects.filter(purchaser=user)\n\n\n\nFiltering against the URL\n\n\nAnother style of filtering might involve restricting the queryset based on some part of the URL.\n\n\nFor example if your URL config contained an entry like this:\n\n\nurl('^purchases/(?P.+)/$', PurchaseList.as_view()),\n\n\n\nYou could then write a view that returned a purchase queryset filtered by the username portion of the URL:\n\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        This view should return a list of all the purchases for\n        the user as determined by the username portion of the URL.\n        \"\"\"\n        username = self.kwargs['username']\n        return Purchase.objects.filter(purchaser__username=username)\n\n\n\nFiltering against query parameters\n\n\nA final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url.\n\n\nWe can override \n.get_queryset()\n to deal with URLs such as \nhttp://example.com/api/purchases?username=denvercoder9\n, and filter the queryset only if the \nusername\n parameter is included in the URL:\n\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        Optionally restricts the returned purchases to a given user,\n        by filtering against a `username` query parameter in the URL.\n        \"\"\"\n        queryset = Purchase.objects.all()\n        username = self.request.query_params.get('username', None)\n        if username is not None:\n            queryset = queryset.filter(purchaser__username=username)\n        return queryset\n\n\n\n\n\nGeneric Filtering\n\n\nAs well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.\n\n\nGeneric filters can also present themselves as HTML controls in the browsable API and admin API.\n\n\n\n\nSetting filter backends\n\n\nThe default filter backends may be set globally, using the \nDEFAULT_FILTER_BACKENDS\n setting. For example.\n\n\nREST_FRAMEWORK = {\n    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)\n}\n\n\n\nYou can also set the filter backends on a per-view, or per-viewset basis,\nusing the \nGenericAPIView\n class-based views.\n\n\nimport django_filters.rest_framework\nfrom django.contrib.auth.models import User\nfrom myapp.serializers import UserSerializer\nfrom rest_framework import generics\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)\n\n\n\nFiltering and object lookups\n\n\nNote that if a filter backend is configured for a view, then as well as being used to filter list views, it will also be used to filter the querysets used for returning a single object.\n\n\nFor instance, given the previous example, and a product with an id of \n4675\n, the following URL would either return the corresponding object, or return a 404 response, depending on if the filtering conditions were met by the given product instance:\n\n\nhttp://example.com/api/products/4675/?category=clothing&max_price=10.00\n\n\n\nOverriding the initial queryset\n\n\nNote that you can use both an overridden \n.get_queryset()\n and generic filtering together, and everything will work as expected.  For example, if \nProduct\n had a many-to-many relationship with \nUser\n, named \npurchase\n, you might want to write a view like this:\n\n\nclass PurchasedProductsList(generics.ListAPIView):\n    \"\"\"\n    Return a list of all the products that the authenticated\n    user has ever purchased, with optional filtering.\n    \"\"\"\n    model = Product\n    serializer_class = ProductSerializer\n    filterset_class = ProductFilter\n\n    def get_queryset(self):\n        user = self.request.user\n        return user.purchase_set.all()\n\n\n\n\n\nAPI Guide\n\n\nDjangoFilterBackend\n\n\nThe \ndjango-filter\n library includes a \nDjangoFilterBackend\n class which\nsupports highly customizable field filtering for REST framework.\n\n\nTo use \nDjangoFilterBackend\n, first install \ndjango-filter\n. Then add \ndjango_filters\n to Django's \nINSTALLED_APPS\n\n\npip install django-filter\n\n\n\nYou should now either add the filter backend to your settings:\n\n\nREST_FRAMEWORK = {\n    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)\n}\n\n\n\nOr add the filter backend to an individual View or ViewSet.\n\n\nfrom django_filters.rest_framework import DjangoFilterBackend\n\nclass UserListView(generics.ListAPIView):\n    ...\n    filter_backends = (DjangoFilterBackend,)\n\n\n\nIf all you need is simple equality-based filtering, you can set a \nfilterset_fields\n attribute on the view, or viewset, listing the set of fields you wish to filter against.\n\n\nclass ProductList(generics.ListAPIView):\n    queryset = Product.objects.all()\n    serializer_class = ProductSerializer\n    filter_backends = (DjangoFilterBackend,)\n    filterset_fields = ('category', 'in_stock')\n\n\n\nThis will automatically create a \nFilterSet\n class for the given fields, and will allow you to make requests such as:\n\n\nhttp://example.com/api/products?category=clothing&in_stock=True\n\n\n\nFor more advanced filtering requirements you can specify a \nFilterSet\n class that should be used by the view.\nYou can read more about \nFilterSet\ns in the \ndjango-filter documentation\n.\nIt's also recommended that you read the section on \nDRF integration\n.\n\n\nSearchFilter\n\n\nThe \nSearchFilter\n class supports simple single query parameter based searching, and is based on the \nDjango admin's search functionality\n.\n\n\nWhen in use, the browsable API will include a \nSearchFilter\n control:\n\n\n\n\nThe \nSearchFilter\n class will only be applied if the view has a \nsearch_fields\n attribute set.  The \nsearch_fields\n attribute should be a list of names of text type fields on the model, such as \nCharField\n or \nTextField\n.\n\n\nfrom rest_framework import filters\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.SearchFilter,)\n    search_fields = ('username', 'email')\n\n\n\nThis will allow the client to filter the items in the list by making queries such as:\n\n\nhttp://example.com/api/users?search=russell\n\n\n\nYou can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:\n\n\nsearch_fields = ('username', 'email', 'profile__profession')\n\n\n\nBy default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.\n\n\nThe search behavior may be restricted by prepending various characters to the \nsearch_fields\n.\n\n\n\n\n'^' Starts-with search.\n\n\n'=' Exact matches.\n\n\n'@' Full-text search.  (Currently only supported Django's MySQL backend.)\n\n\n'$' Regex search.\n\n\n\n\nFor example:\n\n\nsearch_fields = ('=username', '=email')\n\n\n\nBy default, the search parameter is named \n'search\n', but this may be overridden with the \nSEARCH_PARAM\n setting.\n\n\nTo dynamically change search fields based on request content, it's possible to subclass the \nSearchFilter\n and override the \nget_search_fields()\n function. For example, the following subclass will only search on \ntitle\n if the query parameter \ntitle_only\n is in the request:\n\n\nclass CustomSearchFilter(self, view, request):\n    if request.query_params.get('title_only'):\n        return ('title',)\n    return super(CustomSearchFilter, self).get_search_fields(view, request)\n\n\n\nFor more details, see the \nDjango documentation\n.\n\n\n\n\nOrderingFilter\n\n\nThe \nOrderingFilter\n class supports simple query parameter controlled ordering of results.\n\n\n\n\nBy default, the query parameter is named \n'ordering'\n, but this may by overridden with the \nORDERING_PARAM\n setting.\n\n\nFor example, to order users by username:\n\n\nhttp://example.com/api/users?ordering=username\n\n\n\nThe client may also specify reverse orderings by prefixing the field name with '-', like so:\n\n\nhttp://example.com/api/users?ordering=-username\n\n\n\nMultiple orderings may also be specified:\n\n\nhttp://example.com/api/users?ordering=account,username\n\n\n\nSpecifying which fields may be ordered against\n\n\nIt's recommended that you explicitly specify which fields the API should allowing in the ordering filter.  You can do this by setting an \nordering_fields\n attribute on the view, like so:\n\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = ('username', 'email')\n\n\n\nThis helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.\n\n\nIf you \ndon't\n specify an \nordering_fields\n attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the \nserializer_class\n attribute.\n\n\nIf you are confident that the queryset being used by the view doesn't contain any sensitive data, you can also explicitly specify that a view should allow ordering on \nany\n model field or queryset aggregate, by using the special value \n'__all__'\n.\n\n\nclass BookingsListView(generics.ListAPIView):\n    queryset = Booking.objects.all()\n    serializer_class = BookingSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = '__all__'\n\n\n\nSpecifying a default ordering\n\n\nIf an \nordering\n attribute is set on the view, this will be used as the default ordering.\n\n\nTypically you'd instead control this by setting \norder_by\n on the initial queryset, but using the \nordering\n parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template.  This makes it possible to automatically render column headers differently if they are being used to order the results.\n\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = ('username', 'email')\n    ordering = ('username',)\n\n\n\nThe \nordering\n attribute may be either a string or a list/tuple of strings.\n\n\n\n\nDjangoObjectPermissionsFilter\n\n\nThe \nDjangoObjectPermissionsFilter\n is intended to be used together with the \ndjango-guardian\n package, with custom \n'view'\n permissions added.  The filter will ensure that querysets only returns objects for which the user has the appropriate view permission.\n\n\n\n\nNote:\n This filter has been deprecated as of version 3.9 and moved to the 3rd-party \ndjangorestframework-guardian\n package\n.\n\n\n\n\nIf you're using \nDjangoObjectPermissionsFilter\n, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions.  The easiest way to do this is to subclass \nDjangoObjectPermissions\n and add \n'view'\n permissions to the \nperms_map\n attribute.\n\n\nA complete example using both \nDjangoObjectPermissionsFilter\n and \nDjangoObjectPermissions\n might look something like this.\n\n\npermissions.py\n:\n\n\nclass CustomObjectPermissions(permissions.DjangoObjectPermissions):\n    \"\"\"\n    Similar to `DjangoObjectPermissions`, but adding 'view' permissions.\n    \"\"\"\n    perms_map = {\n        'GET': ['%(app_label)s.view_%(model_name)s'],\n        'OPTIONS': ['%(app_label)s.view_%(model_name)s'],\n        'HEAD': ['%(app_label)s.view_%(model_name)s'],\n        'POST': ['%(app_label)s.add_%(model_name)s'],\n        'PUT': ['%(app_label)s.change_%(model_name)s'],\n        'PATCH': ['%(app_label)s.change_%(model_name)s'],\n        'DELETE': ['%(app_label)s.delete_%(model_name)s'],\n    }\n\n\n\nviews.py\n:\n\n\nclass EventViewSet(viewsets.ModelViewSet):\n    \"\"\"\n    Viewset that only lists events if user has 'view' permissions, and only\n    allows operations on individual events if user has appropriate 'view', 'add',\n    'change' or 'delete' permissions.\n    \"\"\"\n    queryset = Event.objects.all()\n    serializer_class = EventSerializer\n    filter_backends = (filters.DjangoObjectPermissionsFilter,)\n    permission_classes = (myapp.permissions.CustomObjectPermissions,)\n\n\n\nFor more information on adding \n'view'\n permissions for models, see the \nrelevant section\n of the \ndjango-guardian\n documentation, and \nthis blogpost\n.\n\n\n\n\nCustom generic filtering\n\n\nYou can also provide your own generic filtering backend, or write an installable app for other developers to use.\n\n\nTo do so override \nBaseFilterBackend\n, and override the \n.filter_queryset(self, request, queryset, view)\n method.  The method should return a new, filtered queryset.\n\n\nAs well as allowing clients to perform searches and filtering, generic filter backends can be useful for restricting which objects should be visible to any given request or user.\n\n\nExample\n\n\nFor example, you might need to restrict users to only being able to see objects they created.\n\n\nclass IsOwnerFilterBackend(filters.BaseFilterBackend):\n    \"\"\"\n    Filter that only allows users to see their own objects.\n    \"\"\"\n    def filter_queryset(self, request, queryset, view):\n        return queryset.filter(owner=request.user)\n\n\n\nWe could achieve the same behavior by overriding \nget_queryset()\n on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.\n\n\nCustomizing the interface\n\n\nGeneric filters may also present an interface in the browsable API. To do so you should implement a \nto_html()\n method which returns a rendered HTML representation of the filter. This method should have the following signature:\n\n\nto_html(self, request, queryset, view)\n\n\nThe method should return a rendered HTML string.\n\n\nPagination & schemas\n\n\nYou can also make the filter controls available to the schema autogeneration\nthat REST framework provides, by implementing a \nget_schema_fields()\n method. This method should have the following signature:\n\n\nget_schema_fields(self, view)\n\n\nThe method should return a list of \ncoreapi.Field\n instances.\n\n\nThird party packages\n\n\nThe following third party packages provide additional filter implementations.\n\n\nDjango REST framework filters package\n\n\nThe \ndjango-rest-framework-filters package\n works together with the \nDjangoFilterBackend\n class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.\n\n\nDjango REST framework full word search filter\n\n\nThe \ndjangorestframework-word-filter\n developed as alternative to \nfilters.SearchFilter\n which will search full word in text, or exact match.\n\n\nDjango URL Filter\n\n\ndjango-url-filter\n provides a safe way to filter data via human-friendly URLs. It works very similar to DRF serializers and fields in a sense that they can be nested except they are called filtersets and filters. That provides easy way to filter related data. Also this library is generic-purpose so it can be used to filter other sources of data and not only Django \nQuerySet\ns.\n\n\ndrf-url-filters\n\n\ndrf-url-filter\n is a simple Django app to apply filters on drf \nModelViewSet\n's \nQueryset\n in a clean, simple and configurable way. It also supports validations on incoming query params and their values. A beautiful python package \nVoluptuous\n is being used for validations on the incoming query parameters. The best part about voluptuous is you can define your own validations as per your query params requirements.",
+            "text": "Filtering\n\n\n\n\nThe root QuerySet provided by the Manager describes all objects in the database table.  Usually, though, you'll need to select only a subset of the complete set of objects.\n\n\n\u2014 \nDjango documentation\n\n\n\n\nThe default behavior of REST framework's generic list views is to return the entire queryset for a model manager.  Often you will want your API to restrict the items that are returned by the queryset.\n\n\nThe simplest way to filter the queryset of any view that subclasses \nGenericAPIView\n is to override the \n.get_queryset()\n method.\n\n\nOverriding this method allows you to customize the queryset returned by the view in a number of different ways.\n\n\nFiltering against the current user\n\n\nYou might want to filter the queryset to ensure that only results relevant to the currently authenticated user making the request are returned.\n\n\nYou can do so by filtering based on the value of \nrequest.user\n.\n\n\nFor example:\n\n\nfrom myapp.models import Purchase\nfrom myapp.serializers import PurchaseSerializer\nfrom rest_framework import generics\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        This view should return a list of all the purchases\n        for the currently authenticated user.\n        \"\"\"\n        user = self.request.user\n        return Purchase.objects.filter(purchaser=user)\n\n\n\nFiltering against the URL\n\n\nAnother style of filtering might involve restricting the queryset based on some part of the URL.\n\n\nFor example if your URL config contained an entry like this:\n\n\nurl('^purchases/(?P.+)/$', PurchaseList.as_view()),\n\n\n\nYou could then write a view that returned a purchase queryset filtered by the username portion of the URL:\n\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        This view should return a list of all the purchases for\n        the user as determined by the username portion of the URL.\n        \"\"\"\n        username = self.kwargs['username']\n        return Purchase.objects.filter(purchaser__username=username)\n\n\n\nFiltering against query parameters\n\n\nA final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url.\n\n\nWe can override \n.get_queryset()\n to deal with URLs such as \nhttp://example.com/api/purchases?username=denvercoder9\n, and filter the queryset only if the \nusername\n parameter is included in the URL:\n\n\nclass PurchaseList(generics.ListAPIView):\n    serializer_class = PurchaseSerializer\n\n    def get_queryset(self):\n        \"\"\"\n        Optionally restricts the returned purchases to a given user,\n        by filtering against a `username` query parameter in the URL.\n        \"\"\"\n        queryset = Purchase.objects.all()\n        username = self.request.query_params.get('username', None)\n        if username is not None:\n            queryset = queryset.filter(purchaser__username=username)\n        return queryset\n\n\n\n\n\nGeneric Filtering\n\n\nAs well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.\n\n\nGeneric filters can also present themselves as HTML controls in the browsable API and admin API.\n\n\n\n\nSetting filter backends\n\n\nThe default filter backends may be set globally, using the \nDEFAULT_FILTER_BACKENDS\n setting. For example.\n\n\nREST_FRAMEWORK = {\n    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)\n}\n\n\n\nYou can also set the filter backends on a per-view, or per-viewset basis,\nusing the \nGenericAPIView\n class-based views.\n\n\nimport django_filters.rest_framework\nfrom django.contrib.auth.models import User\nfrom myapp.serializers import UserSerializer\nfrom rest_framework import generics\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)\n\n\n\nFiltering and object lookups\n\n\nNote that if a filter backend is configured for a view, then as well as being used to filter list views, it will also be used to filter the querysets used for returning a single object.\n\n\nFor instance, given the previous example, and a product with an id of \n4675\n, the following URL would either return the corresponding object, or return a 404 response, depending on if the filtering conditions were met by the given product instance:\n\n\nhttp://example.com/api/products/4675/?category=clothing&max_price=10.00\n\n\n\nOverriding the initial queryset\n\n\nNote that you can use both an overridden \n.get_queryset()\n and generic filtering together, and everything will work as expected.  For example, if \nProduct\n had a many-to-many relationship with \nUser\n, named \npurchase\n, you might want to write a view like this:\n\n\nclass PurchasedProductsList(generics.ListAPIView):\n    \"\"\"\n    Return a list of all the products that the authenticated\n    user has ever purchased, with optional filtering.\n    \"\"\"\n    model = Product\n    serializer_class = ProductSerializer\n    filterset_class = ProductFilter\n\n    def get_queryset(self):\n        user = self.request.user\n        return user.purchase_set.all()\n\n\n\n\n\nAPI Guide\n\n\nDjangoFilterBackend\n\n\nThe \ndjango-filter\n library includes a \nDjangoFilterBackend\n class which\nsupports highly customizable field filtering for REST framework.\n\n\nTo use \nDjangoFilterBackend\n, first install \ndjango-filter\n. Then add \ndjango_filters\n to Django's \nINSTALLED_APPS\n\n\npip install django-filter\n\n\n\nYou should now either add the filter backend to your settings:\n\n\nREST_FRAMEWORK = {\n    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)\n}\n\n\n\nOr add the filter backend to an individual View or ViewSet.\n\n\nfrom django_filters.rest_framework import DjangoFilterBackend\n\nclass UserListView(generics.ListAPIView):\n    ...\n    filter_backends = (DjangoFilterBackend,)\n\n\n\nIf all you need is simple equality-based filtering, you can set a \nfilterset_fields\n attribute on the view, or viewset, listing the set of fields you wish to filter against.\n\n\nclass ProductList(generics.ListAPIView):\n    queryset = Product.objects.all()\n    serializer_class = ProductSerializer\n    filter_backends = (DjangoFilterBackend,)\n    filterset_fields = ('category', 'in_stock')\n\n\n\nThis will automatically create a \nFilterSet\n class for the given fields, and will allow you to make requests such as:\n\n\nhttp://example.com/api/products?category=clothing&in_stock=True\n\n\n\nFor more advanced filtering requirements you can specify a \nFilterSet\n class that should be used by the view.\nYou can read more about \nFilterSet\ns in the \ndjango-filter documentation\n.\nIt's also recommended that you read the section on \nDRF integration\n.\n\n\nSearchFilter\n\n\nThe \nSearchFilter\n class supports simple single query parameter based searching, and is based on the \nDjango admin's search functionality\n.\n\n\nWhen in use, the browsable API will include a \nSearchFilter\n control:\n\n\n\n\nThe \nSearchFilter\n class will only be applied if the view has a \nsearch_fields\n attribute set.  The \nsearch_fields\n attribute should be a list of names of text type fields on the model, such as \nCharField\n or \nTextField\n.\n\n\nfrom rest_framework import filters\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.SearchFilter,)\n    search_fields = ('username', 'email')\n\n\n\nThis will allow the client to filter the items in the list by making queries such as:\n\n\nhttp://example.com/api/users?search=russell\n\n\n\nYou can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:\n\n\nsearch_fields = ('username', 'email', 'profile__profession')\n\n\n\nBy default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.\n\n\nThe search behavior may be restricted by prepending various characters to the \nsearch_fields\n.\n\n\n\n\n'^' Starts-with search.\n\n\n'=' Exact matches.\n\n\n'@' Full-text search.  (Currently only supported Django's MySQL backend.)\n\n\n'$' Regex search.\n\n\n\n\nFor example:\n\n\nsearch_fields = ('=username', '=email')\n\n\n\nBy default, the search parameter is named \n'search\n', but this may be overridden with the \nSEARCH_PARAM\n setting.\n\n\nTo dynamically change search fields based on request content, it's possible to subclass the \nSearchFilter\n and override the \nget_search_fields()\n function. For example, the following subclass will only search on \ntitle\n if the query parameter \ntitle_only\n is in the request:\n\n\nfrom rest_framework import filters\n\nclass CustomSearchFilter(filters.SearchFilter):\n    def get_search_fields(self, view, request):\n        if request.query_params.get('title_only'):\n            return ('title',)\n        return super(CustomSearchFilter, self).get_search_fields(view, request)\n\n\n\nFor more details, see the \nDjango documentation\n.\n\n\n\n\nOrderingFilter\n\n\nThe \nOrderingFilter\n class supports simple query parameter controlled ordering of results.\n\n\n\n\nBy default, the query parameter is named \n'ordering'\n, but this may by overridden with the \nORDERING_PARAM\n setting.\n\n\nFor example, to order users by username:\n\n\nhttp://example.com/api/users?ordering=username\n\n\n\nThe client may also specify reverse orderings by prefixing the field name with '-', like so:\n\n\nhttp://example.com/api/users?ordering=-username\n\n\n\nMultiple orderings may also be specified:\n\n\nhttp://example.com/api/users?ordering=account,username\n\n\n\nSpecifying which fields may be ordered against\n\n\nIt's recommended that you explicitly specify which fields the API should allowing in the ordering filter.  You can do this by setting an \nordering_fields\n attribute on the view, like so:\n\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = ('username', 'email')\n\n\n\nThis helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.\n\n\nIf you \ndon't\n specify an \nordering_fields\n attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the \nserializer_class\n attribute.\n\n\nIf you are confident that the queryset being used by the view doesn't contain any sensitive data, you can also explicitly specify that a view should allow ordering on \nany\n model field or queryset aggregate, by using the special value \n'__all__'\n.\n\n\nclass BookingsListView(generics.ListAPIView):\n    queryset = Booking.objects.all()\n    serializer_class = BookingSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = '__all__'\n\n\n\nSpecifying a default ordering\n\n\nIf an \nordering\n attribute is set on the view, this will be used as the default ordering.\n\n\nTypically you'd instead control this by setting \norder_by\n on the initial queryset, but using the \nordering\n parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template.  This makes it possible to automatically render column headers differently if they are being used to order the results.\n\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.OrderingFilter,)\n    ordering_fields = ('username', 'email')\n    ordering = ('username',)\n\n\n\nThe \nordering\n attribute may be either a string or a list/tuple of strings.\n\n\n\n\nDjangoObjectPermissionsFilter\n\n\nThe \nDjangoObjectPermissionsFilter\n is intended to be used together with the \ndjango-guardian\n package, with custom \n'view'\n permissions added.  The filter will ensure that querysets only returns objects for which the user has the appropriate view permission.\n\n\n\n\nNote:\n This filter has been deprecated as of version 3.9 and moved to the 3rd-party \ndjangorestframework-guardian\n package\n.\n\n\n\n\nIf you're using \nDjangoObjectPermissionsFilter\n, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions.  The easiest way to do this is to subclass \nDjangoObjectPermissions\n and add \n'view'\n permissions to the \nperms_map\n attribute.\n\n\nA complete example using both \nDjangoObjectPermissionsFilter\n and \nDjangoObjectPermissions\n might look something like this.\n\n\npermissions.py\n:\n\n\nclass CustomObjectPermissions(permissions.DjangoObjectPermissions):\n    \"\"\"\n    Similar to `DjangoObjectPermissions`, but adding 'view' permissions.\n    \"\"\"\n    perms_map = {\n        'GET': ['%(app_label)s.view_%(model_name)s'],\n        'OPTIONS': ['%(app_label)s.view_%(model_name)s'],\n        'HEAD': ['%(app_label)s.view_%(model_name)s'],\n        'POST': ['%(app_label)s.add_%(model_name)s'],\n        'PUT': ['%(app_label)s.change_%(model_name)s'],\n        'PATCH': ['%(app_label)s.change_%(model_name)s'],\n        'DELETE': ['%(app_label)s.delete_%(model_name)s'],\n    }\n\n\n\nviews.py\n:\n\n\nclass EventViewSet(viewsets.ModelViewSet):\n    \"\"\"\n    Viewset that only lists events if user has 'view' permissions, and only\n    allows operations on individual events if user has appropriate 'view', 'add',\n    'change' or 'delete' permissions.\n    \"\"\"\n    queryset = Event.objects.all()\n    serializer_class = EventSerializer\n    filter_backends = (filters.DjangoObjectPermissionsFilter,)\n    permission_classes = (myapp.permissions.CustomObjectPermissions,)\n\n\n\nFor more information on adding \n'view'\n permissions for models, see the \nrelevant section\n of the \ndjango-guardian\n documentation, and \nthis blogpost\n.\n\n\n\n\nCustom generic filtering\n\n\nYou can also provide your own generic filtering backend, or write an installable app for other developers to use.\n\n\nTo do so override \nBaseFilterBackend\n, and override the \n.filter_queryset(self, request, queryset, view)\n method.  The method should return a new, filtered queryset.\n\n\nAs well as allowing clients to perform searches and filtering, generic filter backends can be useful for restricting which objects should be visible to any given request or user.\n\n\nExample\n\n\nFor example, you might need to restrict users to only being able to see objects they created.\n\n\nclass IsOwnerFilterBackend(filters.BaseFilterBackend):\n    \"\"\"\n    Filter that only allows users to see their own objects.\n    \"\"\"\n    def filter_queryset(self, request, queryset, view):\n        return queryset.filter(owner=request.user)\n\n\n\nWe could achieve the same behavior by overriding \nget_queryset()\n on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.\n\n\nCustomizing the interface\n\n\nGeneric filters may also present an interface in the browsable API. To do so you should implement a \nto_html()\n method which returns a rendered HTML representation of the filter. This method should have the following signature:\n\n\nto_html(self, request, queryset, view)\n\n\nThe method should return a rendered HTML string.\n\n\nPagination & schemas\n\n\nYou can also make the filter controls available to the schema autogeneration\nthat REST framework provides, by implementing a \nget_schema_fields()\n method. This method should have the following signature:\n\n\nget_schema_fields(self, view)\n\n\nThe method should return a list of \ncoreapi.Field\n instances.\n\n\nThird party packages\n\n\nThe following third party packages provide additional filter implementations.\n\n\nDjango REST framework filters package\n\n\nThe \ndjango-rest-framework-filters package\n works together with the \nDjangoFilterBackend\n class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.\n\n\nDjango REST framework full word search filter\n\n\nThe \ndjangorestframework-word-filter\n developed as alternative to \nfilters.SearchFilter\n which will search full word in text, or exact match.\n\n\nDjango URL Filter\n\n\ndjango-url-filter\n provides a safe way to filter data via human-friendly URLs. It works very similar to DRF serializers and fields in a sense that they can be nested except they are called filtersets and filters. That provides easy way to filter related data. Also this library is generic-purpose so it can be used to filter other sources of data and not only Django \nQuerySet\ns.\n\n\ndrf-url-filters\n\n\ndrf-url-filter\n is a simple Django app to apply filters on drf \nModelViewSet\n's \nQueryset\n in a clean, simple and configurable way. It also supports validations on incoming query params and their values. A beautiful python package \nVoluptuous\n is being used for validations on the incoming query parameters. The best part about voluptuous is you can define your own validations as per your query params requirements.",
             "title": "Filtering"
         },
         {
@@ -2762,7 +2762,7 @@
         },
         {
             "location": "/api-guide/filtering/#searchfilter",
-            "text": "The  SearchFilter  class supports simple single query parameter based searching, and is based on the  Django admin's search functionality .  When in use, the browsable API will include a  SearchFilter  control:   The  SearchFilter  class will only be applied if the view has a  search_fields  attribute set.  The  search_fields  attribute should be a list of names of text type fields on the model, such as  CharField  or  TextField .  from rest_framework import filters\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.SearchFilter,)\n    search_fields = ('username', 'email')  This will allow the client to filter the items in the list by making queries such as:  http://example.com/api/users?search=russell  You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:  search_fields = ('username', 'email', 'profile__profession')  By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.  The search behavior may be restricted by prepending various characters to the  search_fields .   '^' Starts-with search.  '=' Exact matches.  '@' Full-text search.  (Currently only supported Django's MySQL backend.)  '$' Regex search.   For example:  search_fields = ('=username', '=email')  By default, the search parameter is named  'search ', but this may be overridden with the  SEARCH_PARAM  setting.  To dynamically change search fields based on request content, it's possible to subclass the  SearchFilter  and override the  get_search_fields()  function. For example, the following subclass will only search on  title  if the query parameter  title_only  is in the request:  class CustomSearchFilter(self, view, request):\n    if request.query_params.get('title_only'):\n        return ('title',)\n    return super(CustomSearchFilter, self).get_search_fields(view, request)  For more details, see the  Django documentation .",
+            "text": "The  SearchFilter  class supports simple single query parameter based searching, and is based on the  Django admin's search functionality .  When in use, the browsable API will include a  SearchFilter  control:   The  SearchFilter  class will only be applied if the view has a  search_fields  attribute set.  The  search_fields  attribute should be a list of names of text type fields on the model, such as  CharField  or  TextField .  from rest_framework import filters\n\nclass UserListView(generics.ListAPIView):\n    queryset = User.objects.all()\n    serializer_class = UserSerializer\n    filter_backends = (filters.SearchFilter,)\n    search_fields = ('username', 'email')  This will allow the client to filter the items in the list by making queries such as:  http://example.com/api/users?search=russell  You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:  search_fields = ('username', 'email', 'profile__profession')  By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.  The search behavior may be restricted by prepending various characters to the  search_fields .   '^' Starts-with search.  '=' Exact matches.  '@' Full-text search.  (Currently only supported Django's MySQL backend.)  '$' Regex search.   For example:  search_fields = ('=username', '=email')  By default, the search parameter is named  'search ', but this may be overridden with the  SEARCH_PARAM  setting.  To dynamically change search fields based on request content, it's possible to subclass the  SearchFilter  and override the  get_search_fields()  function. For example, the following subclass will only search on  title  if the query parameter  title_only  is in the request:  from rest_framework import filters\n\nclass CustomSearchFilter(filters.SearchFilter):\n    def get_search_fields(self, view, request):\n        if request.query_params.get('title_only'):\n            return ('title',)\n        return super(CustomSearchFilter, self).get_search_fields(view, request)  For more details, see the  Django documentation .",
             "title": "SearchFilter"
         },
         {
diff --git a/sitemap.xml b/sitemap.xml
index 724b77c84..654bd1f9b 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -4,7 +4,7 @@
     
     
      https://www.django-rest-framework.org//
-     2019-03-03
+     2019-03-04
      daily
     
     
@@ -13,49 +13,49 @@
         
     
      https://www.django-rest-framework.org//tutorial/quickstart/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/1-serialization/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/2-requests-and-responses/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/3-class-based-views/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/4-authentication-and-permissions/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/5-relationships-and-hyperlinked-apis/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/6-viewsets-and-routers/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//tutorial/7-schemas-and-client-libraries/
-     2019-03-03
+     2019-03-04
      daily
     
         
@@ -65,169 +65,169 @@
         
     
      https://www.django-rest-framework.org//api-guide/requests/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/responses/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/views/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/generic-views/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/viewsets/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/routers/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/parsers/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/renderers/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/serializers/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/fields/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/relations/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/validators/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/authentication/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/permissions/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/caching/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/throttling/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/filtering/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/pagination/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/versioning/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/content-negotiation/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/metadata/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/schemas/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/format-suffixes/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/reverse/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/exceptions/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/status-codes/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/testing/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//api-guide/settings/
-     2019-03-03
+     2019-03-04
      daily
     
         
@@ -237,49 +237,49 @@
         
     
      https://www.django-rest-framework.org//topics/documenting-your-api/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/api-clients/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/internationalization/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/ajax-csrf-cors/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/html-and-forms/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/browser-enhancements/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/browsable-api/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//topics/rest-hypermedia-hateoas/
-     2019-03-03
+     2019-03-04
      daily
     
         
@@ -289,115 +289,115 @@
         
     
      https://www.django-rest-framework.org//community/tutorials-and-resources/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/third-party-packages/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/contributing/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/project-management/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/release-notes/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.9-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.8-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.7-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.6-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.5-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.4-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.3-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.2-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.1-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/3.0-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/kickstarter-announcement/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/mozilla-grant/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/funding/
-     2019-03-03
+     2019-03-04
      daily
     
         
     
      https://www.django-rest-framework.org//community/jobs/
-     2019-03-03
+     2019-03-04
      daily