enable sorting of offers

2 files changed, 30 insertions, 4 deletions

diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index a9ea93e60..4c6c8b70b 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -255,12 +255,12 @@ Pre-defined Phases
 
 :const:`pyramid.config.PHASE1_CONFIG`
 
-- :meth:`pyramid.config.Configurator.add_accept_view_option`
+- :meth:`pyramid.config.Configurator.add_accept_view_order`
 - :meth:`pyramid.config.Configurator.add_renderer`
 - :meth:`pyramid.config.Configurator.add_route_predicate`
 - :meth:`pyramid.config.Configurator.add_subscriber_predicate`
-- :meth:`pyramid.config.Configurator.add_view_predicate`
 - :meth:`pyramid.config.Configurator.add_view_deriver`
+- :meth:`pyramid.config.Configurator.add_view_predicate`
 - :meth:`pyramid.config.Configurator.override_asset`
 - :meth:`pyramid.config.Configurator.set_authorization_policy`
 - :meth:`pyramid.config.Configurator.set_default_csrf_options`
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 2060393bb..cd49d6e94 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -1027,7 +1027,8 @@ See :ref:`environment_chapter` for more information about how, and where to set
 these values.
 
 .. index::
-   single: HTTP caching
+   single: Accept
+   single: Accept content negotation
 
 .. _accept_content_negotation:
 
@@ -1059,10 +1060,11 @@ Similarly, if the client specifies a media type that no view is registered to ha
 There are a few cases in which the client may specify ambiguous constraints:
 
 - ``Accept: */*``.
+- More than one acceptable media type with the same quality.
 - A missing ``Accept`` header.
 - An invalid ``Accept`` header.
 
-In these cases the preferred view is not clearly defined (see :rfc:`7231#section-5.3.2`) and :app:`Pyramid` will select one randomly.
+In these cases the preferred view is not clearly defined (see :rfc:`7231#section-5.3.2`) and :app:`Pyramid` will select one semi-randomly.
 This can be controlled by telling :app:`Pyramid` what the preferred relative ordering is between various media types by using :meth:`pyramid.config.Configurator.add_accept_view_order`.
 For example:
 
@@ -1082,9 +1084,30 @@ For example:
 
 In this case, the ``application/json`` view should always be selected in cases where it is otherwise ambiguous.
 
+.. _default_accept_ordering:
+
 Default Accept Ordering
 +++++++++++++++++++++++
 
+:app:`Pyramid` will always sort multiple views with the same ``(name, context, route_name)`` first by the specificity of the ``accept`` offer.
+This means that ``text/plain`` will always be offered before ``text/*``.
+Similarly ``text/plain;charset=utf8`` will always be offered before ``text/plain``.
+The following order is always preserved between the following offers (more preferred to less preferred):
+
+- ``type/subtype;params``
+- ``type/subtype``
+- ``type/*``
+- ``*/*``
+
+Within each of these levels of specificity, the ordering is ambiguous and may be controlled using :meth:`pyramid.config.Configurator.add_accept_view_order`. For example, to sort ``text/plain`` higher than ``text/html`` and to prefer a ``charset=utf8`` versus a ``charset=latin-1`` within the ``text/plain`` media type:
+
+.. code-block:: python
+
+    config.add_accept_view_order('text/plain', weighs_more_than='text/html')
+    config.add_accept_view_order('text/plain;charset=utf8', weighs_more_than='text/plain;charset=latin-1')
+
+It is an error to try and sort accept headers across levels of specificity. You can only sort a ``type/subtype`` against another ``type/subtype``, not against a ``type/*``. That ordering is a hard requirement.
+
 By default, :app:`Pyramid` defines a very simple priority ordering for views that prefers human-readable responses over JSON:
 
 - ``text/html``
@@ -1099,6 +1122,9 @@ Therefore, the motivation for this ordering is to optimize for readability.
 Media types that are not listed above are ordered randomly during :term:`view lookup` between otherwise-similar views.
 The defaults can be overridden using :meth:`pyramid.config.Configurator.add_accept_view_order` as described above.
 
+.. index::
+   single: HTTP caching
+
 .. _influencing_http_caching:
 
 Influencing HTTP Caching