Honor Accept header q-values during renderer selection

docs/api-guide/content-negotiation.md

@@ -15,8 +15,10 @@ Content negotiation is the process of selecting one of multiple possible represe
 
 REST framework uses a simple style of content negotiation to determine which media type should be returned to a client, based on the available renderers, the priorities of each of those renderers, and the client's `Accept:` header.  The style used is partly client-driven, and partly server-driven.
 
-1. More specific media types are given preference to less specific media types.
-2. If multiple media types have the same specificity, then preference is given to based on the ordering of the renderers configured for the given view.
+1. Media ranges with `q=0` are treated as unacceptable.
+2. Higher `q` values are given preference to lower `q` values.
+3. If multiple media types have the same `q` value, more specific media types are given preference to less specific media types.
+4. If multiple media types have the same `q` value and specificity, then preference is based on the ordering of the renderers configured for the given view.
 
 For example, given the following `Accept` header:
 
@@ -33,11 +35,6 @@ If the requested view was only configured with renderers for `YAML` and `HTML`,
 For more information on the `HTTP Accept` header, see [RFC 2616][accept-header]
 
 
-!!! note
-    "q" values are not taken into account by REST framework when determining preference.  The use of "q" values negatively impacts caching, and in the author's opinion they are an unnecessary and overcomplicated approach to content negotiation.
-
-    This is a valid approach as the HTTP spec deliberately underspecifies how a server should weight server-based preferences against client-based preferences.
-
 ## Custom content negotiation
 
 It's unlikely that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed.  To implement a custom content negotiation scheme override `BaseContentNegotiation`.

rest_framework/negotiation.py

@@ -45,6 +45,10 @@ def select_renderer(self, request, renderers, format_suffix=None):
             renderers = self.filter_renderers(renderers, format)
 
         accepts = self.get_accept_list(request)
+        unacceptable_media_types = [
+            media_type for media_type in accepts
+            if _MediaType(media_type).quality <= 0
+        ]
 
         # Check the acceptable media types against each renderer,
         # attempting more specific media types first
@@ -54,6 +58,10 @@ def select_renderer(self, request, renderers, format_suffix=None):
             for renderer in renderers:
                 for media_type in media_type_set:
                     if media_type_matches(renderer.media_type, media_type):
+                        if self.is_renderer_unacceptable(
+                            renderer, media_type, unacceptable_media_types
+                        ):
+                            continue
                         # Return the most specific media type as accepted.
                         media_type_wrapper = _MediaType(media_type)
                         if (
@@ -77,6 +85,14 @@ def select_renderer(self, request, renderers, format_suffix=None):
 
         raise exceptions.NotAcceptable(available_renderers=renderers)
 
+    def is_renderer_unacceptable(self, renderer, media_type, unacceptable_media_types):
+        media_type_precedence = _MediaType(media_type).precedence
+        return any(
+            media_type_matches(renderer.media_type, unacceptable_media_type) and
+            _MediaType(unacceptable_media_type).precedence >= media_type_precedence
+            for unacceptable_media_type in unacceptable_media_types
+        )
+
     def filter_renderers(self, renderers, format):
         """
         If there is a '.json' style format suffix, filter the renderers

rest_framework/utils/mediatypes.py

@@ -26,19 +26,29 @@ def media_type_matches(lhs, rhs):
 
 def order_by_precedence(media_type_lst):
     """
-    Returns a list of sets of media type strings, ordered by precedence.
+    Returns a list of sets of media type strings, ordered by quality and
+    precedence. Quality is determined by the q parameter and defaults to 1.
     Precedence is determined by how specific a media type is:
 
     3. 'type/subtype; param=val'
     2. 'type/subtype'
     1. 'type/*'
     0. '*/*'
     """
-    ret = [set(), set(), set(), set()]
+    ret = {}
     for media_type in media_type_lst:
-        precedence = _MediaType(media_type).precedence
-        ret[3 - precedence].add(media_type)
-    return [media_types for media_types in ret if media_types]
+        media_type = _MediaType(media_type)
+        if media_type.quality <= 0:
+            continue
+        precedence = media_type.precedence
+        ret.setdefault(media_type.quality, [set(), set(), set(), set()])
+        ret[media_type.quality][3 - precedence].add(media_type.orig)
+    return [
+        media_types
+        for quality in sorted(ret, reverse=True)
+        for media_types in ret[quality]
+        if media_types
+    ]
 
 
 class _MediaType:
@@ -79,3 +89,13 @@ def __str__(self):
         for key, val in self.params.items():
             ret += "; %s=%s" % (key, val)
         return ret
+
+    @property
+    def quality(self):
+        try:
+            quality = float(self.params.get('q', 1))
+        except ValueError:
+            return 1
+        if not 0 <= quality <= 1:
+            return 1
+        return quality

tests/test_negotiation.py

@@ -59,6 +59,56 @@ def test_client_specifies_parameter(self):
         assert accepted_media_type == 'application/openapi+json;version=2.0'
         assert accepted_renderer.format == 'swagger'
 
+    def test_client_excludes_zero_quality_media_type(self):
+        request = Request(factory.get('/', HTTP_ACCEPT='text/html;q=0, */*;q=1'))
+        renderers = [MockHTMLRenderer(), MockJSONRenderer()]
+        accepted_renderer, accepted_media_type = self.negotiator.select_renderer(
+            request, renderers
+        )
+        assert accepted_renderer.media_type == 'application/json'
+        assert accepted_media_type.startswith('application/json')
+
+    def test_client_prefers_nonzero_quality_media_type(self):
+        request = Request(
+            factory.get('/', HTTP_ACCEPT='application/json;q=0, text/html;q=1')
+        )
+        accepted_renderer, accepted_media_type = self.select_renderer(request)
+        assert accepted_renderer.media_type == 'text/html'
+        assert accepted_media_type.startswith('text/html')
+
+    def test_client_prefers_higher_quality_media_type(self):
+        request = Request(
+            factory.get('/', HTTP_ACCEPT='application/json;q=0.5, text/*;q=1')
+        )
+        accepted_renderer, accepted_media_type = self.select_renderer(request)
+        assert accepted_renderer.media_type == 'text/html'
+        assert accepted_media_type.startswith('text/html')
+
+    def test_client_without_quality_keeps_renderer_order(self):
+        request = Request(factory.get('/', HTTP_ACCEPT='text/html, application/json'))
+        accepted_renderer, accepted_media_type = self.select_renderer(request)
+        assert accepted_renderer.media_type == 'application/json'
+        assert accepted_media_type == 'application/json'
+
+    def test_client_with_equal_quality_uses_specificity(self):
+        request = Request(
+            factory.get('/', HTTP_ACCEPT='text/*;q=0.5, application/json;q=0.5')
+        )
+        renderers = [MockHTMLRenderer(), MockJSONRenderer()]
+        accepted_renderer, accepted_media_type = self.negotiator.select_renderer(
+            request, renderers
+        )
+        assert accepted_renderer.media_type == 'application/json'
+        assert accepted_media_type.startswith('application/json')
+
+    def test_client_with_invalid_quality_uses_default_quality(self):
+        request = Request(
+            factory.get('/', HTTP_ACCEPT='application/json;q=NaN, text/html;q=0.5')
+        )
+        accepted_renderer, accepted_media_type = self.select_renderer(request)
+        assert accepted_renderer.media_type == 'application/json'
+        assert accepted_media_type.startswith('application/json')
+
     def test_match_is_false_if_main_types_not_match(self):
         mediatype = _MediaType('test_1')
         another_mediatype = _MediaType('test_2')