From f5a8cd2840dc6b0fea4fd7642950b5c731445776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 7 May 2020 23:52:19 -0400 Subject: better wording --- docs/narr/viewconfig.rst | 39 +++++++++++++++++++-------------------- src/pyramid/config/routes.py | 16 ++++++++-------- src/pyramid/config/views.py | 12 ++++++------ 3 files changed, 33 insertions(+), 34 deletions(-) diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index c40f1181a..b43ebb93e 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -391,7 +391,7 @@ configured view. the ``REQUEST_METHOD`` of the :term:`WSGI` environment. ``request_param`` - This value can be any string or a sequence of strings. A view declaration + This argument can be any string or a sequence of strings. A view declaration with this argument ensures that the view will only be called when the :term:`request` has a key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied @@ -406,7 +406,7 @@ configured view. consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - This param may be either a single string of the format "key=value" or a tuple + This argument may be either a single string of the format "key=value" or a tuple containing one or more of these strings. This argument ensures that the view will only be called when the @@ -448,24 +448,23 @@ configured view. associated view callable. ``header`` - This value matches one or more HTTP header names or header name/value pairs. - - If ``header`` is specified, it must be a string or a sequence of strings, - each being a header name or a ``headername:headervalue`` pair. - - If ``header`` is specified without a value (a bare header name only, e.g., - ``If-Modified-Since``), the view will only be invoked if the HTTP header - exists with any value in the request. - - If ``header`` is specified, and possesses a name/value pair (e.g., - ``User-Agent:Mozilla/.*``), the view will only be invoked if the HTTP header - exists *and* the HTTP header matches the value requested. When the - ``headervalue`` contains a ``:`` (colon), it will be considered a name/value - pair (e.g., ``User-Agent:Mozilla/.*`` or ``Host:localhost``). The value - portion should be a regular expression. - - Whether or not the value represents a header name or a header name/value - pair, the case of the header name is not significant. + This param matches one or more HTTP header names or header name/value pairs. + If specified, this param must be a string or a sequence of strings, + each string being a header name or a ``headername:headervalue`` pair. + + - Each string specified as a bare header name without a value (for example + ``If-Modified-Since``) will match a request if it contains an HTTP header + with that same name. The case of the name is not significant, and the + header may have any value in the request. + + - Each string specified as a name/value pair (that is, if it contains a ``:`` + (colon), like ``User-Agent:Mozilla/.*``) will match a request only if it + contains an HTTP header with the requested name (ignoring case, so + ``User-Agent`` or ``user-agent`` would both match), *and* the value of the + HTTP header matches the value requested (``Mozilla/.*`` in our example). + The value portion is interpreted as a regular expression. + + The view will only be invoked if all strings are matching. If ``header`` is not specified, the composition, presence, or absence of HTTP headers is not taken into consideration when deciding whether or not to diff --git a/src/pyramid/config/routes.py b/src/pyramid/config/routes.py index 4896ce0ea..a12e18fa8 100644 --- a/src/pyramid/config/routes.py +++ b/src/pyramid/config/routes.py @@ -211,29 +211,29 @@ class RoutesConfiguratorMixin: dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied value. If the value supplied as the argument has a ``=`` sign in it, - e.g. ``request_param="foo=123"``, then the key - (``foo``) must both exist in the ``request.params`` dictionary, and + e.g. ``request_param="foo=123"``, then both the key + (``foo``) must exist in the ``request.params`` dictionary, and the value must match the right hand side of the expression (``123``) for the route to "match" the current request. If this predicate returns ``False``, route matching continues. header - This value can be a string or an iterable of strings for HTTP - header names. The header names are determined as follow: + This argument can be a string or an iterable of strings for HTTP + headers. The matching is determined as follow: - If a string does not contain a ``:`` (colon), it will be - considered to be the header name (e.g. ``If-Modified-Since``). + considered to be the header name (example ``If-Modified-Since``). In this case, the header specified by the name must be present in the request for this string to match. Case is not significant. - If a string contains a colon, it will be considered a - name/value pair (e.g. ``User-Agent:Mozilla/.*`` or + name/value pair (for example ``User-Agent:Mozilla/.*`` or ``Host:localhost``), where the value part is a regular expression. The header specified by the name must be present in the request *and* the regular expression specified as the - value must match the header value. Case is not significant for - the header name, but it is for the value. + value part must match the value of the request header. Case is + not significant for the header name, but it is for the value. All strings must be matched for this predicate to return ``True``. If this predicate returns ``False``, route matching continues. diff --git a/src/pyramid/config/views.py b/src/pyramid/config/views.py index 170f8a028..a064ebd05 100644 --- a/src/pyramid/config/views.py +++ b/src/pyramid/config/views.py @@ -670,21 +670,21 @@ class ViewsConfiguratorMixin: header - This value can be a string or an iterable of strings for HTTP - header names. The header names are determined as follow: + This argument can be a string or an iterable of strings for HTTP + headers. The matching is determined as follow: - If a string does not contain a ``:`` (colon), it will be - considered to be the header name (e.g. ``If-Modified-Since``). + considered to be a header name (example ``If-Modified-Since``). In this case, the header specified by the name must be present in the request for this string to match. Case is not significant. - If a string contains a colon, it will be considered a - name/value pair (e.g. ``User-Agent:Mozilla/.*`` or + name/value pair (for example ``User-Agent:Mozilla/.*`` or ``Host:localhost``), where the value part is a regular expression. The header specified by the name must be present in the request *and* the regular expression specified as the - value must match the header value. Case is not significant for - the header name, but it is for the value. + value part must match the value of the request header. Case is + not significant for the header name, but it is for the value. All strings must be matched for this predicate to return ``True``. If this predicate returns ``False``, view matching continues. -- cgit v1.2.3