bring request lookup order related documentation in line with the act…

…ual code (#629); minor refactorization/cleanup of `HTTPRequest.get`

CHANGES.rst

@@ -30,6 +30,11 @@ Fixes
 - Fixed logic error in exceptions handling during publishing. This error would
   prevent correct Unauthorized handling when exceptions debug mode was set.
 
+- Bring request lookup order related documentation in line with the
+  actual implementation
+  (`#629 <https://github.com/zopefoundation/Zope/issues/629>`_).
+  Minor cleanup of ``HTTPRequest.get``.
+
 
 4.0 (2019-05-10)
 ----------------

docs/zopebook/AdvDTML.rst

@@ -260,23 +260,25 @@ of places for variables, so too the request looks up variables
 in a number of places. When the request looks for a variable it
 consults these sources in order:
 
-1. The CGI environment. The `Common Gateway Interface
+1. Variables explicitly set on the request.
+
+2. Special variables. The REQUEST namespace provides you
+   with special information, such as the URL of
+   the current object and all of its parents.
+
+3. The CGI environment. The `Common Gateway Interface
    <http://www.w3.org/CGI/>`_, or CGI interface defines
    a standard set of environment variables to be used by
    dynamic web scripts.  These variables are provided by Zope
    in the REQUEST namespace.
 
-2. Form data. If the current request is a form action, then
+4. Form data. If the current request is a form action, then
    any form input data that was submitted with the request can
    be found in the REQUEST object.
 
-3. Cookies. If the client of the current request has any cookies
+5. Cookies. If the client of the current request has any cookies
    these can be found in the current REQUEST object.
 
-4. Additional variables. The REQUEST namespace provides you
-   with lots of other useful information, such as the URL of
-   the current object and all of its parents.
-
 The request namespace is very useful in Zope since it is the
 primary way that clients (in this case, web browsers)
 communicate with Zope by providing form data, cookies and other

src/ZPublisher/HTTPRequest.py

@@ -1277,15 +1277,29 @@ def get(self, key, default=None, returnTaints=0,
             ):
         """Get a variable value
 
-        Return a value for the required variable name.
-        The value will be looked up from one of the request data
-        categories. The search order is environment variables,
-        other variables, form data, and then cookies.
+        Return a value for the variable key, or default if not found.
+
+        If key is "REQUEST", return the request.
+        Otherwise, the value will be looked up from one of the request data
+        categories. The search order is:
+        other (the target for explicitly set variables),
+        the special URL and BASE variables,
+        environment variables,
+        common variables (defined by the request class),
+        lazy variables (set with set_lazy),
+        form data and cookies.
+
+        If returnTaints has a true value, then the access to
+        form and cookie variables returns values with special
+        protection against embedded HTML fragments to counter
+        some cross site scripting attacks.
         """
+
+        if key == 'REQUEST':
+            return self
+
         other = self.other
         if key in other:
-            if key == 'REQUEST':
-                return self
             return other[key]
 
         if key[:1] == 'U':
@@ -1313,9 +1327,6 @@ def get(self, key, default=None, returnTaints=0,
                 return environ[key]
             return ''
 
-        if key == 'REQUEST':
-            return self
-
         if key[:1] == 'B':
             match = BASEmatch(key)
             if match is not None: