Document the wsgiref attributes instead of suppressing the references

Replace the "!"-suppressed references with real targets: .. method::
directives for Headers.keys(), Headers.values() and Headers.items(), and
.. attribute:: directives for WSGIServer.base_environ,
BaseHandler.environ and SimpleHandler's stdin, stdout and stderr.

Correct the SimpleHandler paragraph while documenting it: the constructor
stores the supplied environment in base_env, not environ, and
add_cgi_vars() merges it into BaseHandler.environ during setup_environ().

paste.lint (a third-party module) and FileWrapper.close (bound
conditionally from the wrapped object, never defined on the class) keep
the "!" prefix, since neither can have a real target.

Author: sach98

Doc/library/wsgiref.rst

@@ -219,13 +219,30 @@ manipulation of WSGI response headers using a mapping-like interface.
    nonexistent header just returns ``None``, and deleting a nonexistent header does
    nothing.
 
-   :class:`Headers` objects also support :meth:`!keys`, :meth:`!values`, and
-   :meth:`!items` methods.  The lists returned by :meth:`!keys` and
-   :meth:`!items` can include the same key more than once if there is a
-   multi-valued header.  The ``len()`` of a :class:`Headers` object is the same
-   as the length of its :meth:`!items`, which is the same as the length of the
-   wrapped header list.  In fact, the :meth:`!items` method just returns a copy
-   of the wrapped header list.
+   :class:`Headers` objects also support :meth:`keys`, :meth:`values`, and
+   :meth:`items` methods.  The lists returned by :meth:`keys` and :meth:`items` can
+   include the same key more than once if there is a multi-valued header.  The
+   ``len()`` of a :class:`Headers` object is the same as the length of its
+   :meth:`items`, which is the same as the length of the wrapped header list.
+
+
+   .. method:: Headers.keys()
+
+      Return a list of all the header field names, in the order the fields
+      appeared in the original header list or were added to this instance.  Any
+      fields deleted and re-inserted are always appended to the header list.
+
+
+   .. method:: Headers.values()
+
+      Return a list of all the header values, in the same order as :meth:`keys`.
+
+
+   .. method:: Headers.items()
+
+      Return a copy of the wrapped header list, as a list of ``(name, value)``
+      pairs in the same order as :meth:`keys`.
+
 
    Calling ``bytes()`` on a :class:`Headers` object returns a formatted bytestring
    suitable for transmission as HTTP response headers.  Each header is placed on a
@@ -351,6 +368,16 @@ request.  (E.g., using the :func:`~wsgiref.util.shift_path_info` function from
    :meth:`get_app` exists mainly for the benefit of request handler instances.
 
 
+   .. attribute:: WSGIServer.base_environ
+
+      The base set of CGI environment variables the server supplies to every
+      request, such as ``SERVER_NAME``, ``SERVER_PORT`` and
+      ``GATEWAY_INTERFACE``.  It is populated when the server is bound to its
+      address, and :meth:`WSGIRequestHandler.get_environ` copies it to build the
+      environment for each individual request, adding and overriding entries
+      that are specific to that request.
+
+
 .. class:: WSGIRequestHandler(request, client_address, server)
 
    Create an HTTP handler for the given *request* (i.e. a socket), *client_address*
@@ -365,13 +392,12 @@ request.  (E.g., using the :func:`~wsgiref.util.shift_path_info` function from
 
    .. method:: WSGIRequestHandler.get_environ()
 
-      Return a :data:`~wsgiref.types.WSGIEnvironment` dictionary for a
-      request.  The default
-      implementation copies the contents of the :class:`WSGIServer` object's
-      :attr:`!base_environ` dictionary attribute and then adds various headers derived
-      from the HTTP request.  Each call to this method should return a new dictionary
-      containing all of the relevant CGI environment variables as specified in
-      :pep:`3333`.
+      Return a :data:`~wsgiref.types.WSGIEnvironment` dictionary for a request.
+      The default implementation copies the contents of the :class:`WSGIServer`
+      object's :attr:`~WSGIServer.base_environ` dictionary attribute and then
+      adds various headers derived from the HTTP request.  Each call to this
+      method should return a new dictionary containing all of the relevant CGI
+      environment variables as specified in :pep:`3333`.
 
 
    .. method:: WSGIRequestHandler.get_stderr()
@@ -533,14 +559,24 @@ input, output, and error streams.
    :meth:`~BaseHandler.get_stderr`, :meth:`~BaseHandler.add_cgi_vars`,
    :meth:`~BaseHandler._write`, and :meth:`~BaseHandler._flush` methods to
    support explicitly setting the
-   environment and streams via the constructor.  The supplied environment and
-   streams are stored in the :attr:`!stdin`, :attr:`!stdout`, :attr:`!stderr`,
-   and :attr:`!environ` attributes.
+   environment and streams via the constructor.  The supplied streams are stored
+   in the :attr:`stdin`, :attr:`stdout`, and :attr:`stderr` attributes, and the
+   supplied environment is merged into :attr:`~BaseHandler.environ` when the
+   environment for the request is set up.
 
    The :meth:`~io.BufferedIOBase.write` method of *stdout* should write
    each chunk in full, like :class:`io.BufferedIOBase`.
 
 
+   .. attribute:: SimpleHandler.stdin
+                  SimpleHandler.stdout
+                  SimpleHandler.stderr
+
+      The streams supplied to the constructor.  *stdin* is used as the
+      ``wsgi.input`` stream, *stdout* receives the response, and *stderr* is
+      used as the ``wsgi.errors`` stream.
+
+
 .. class:: BaseHandler()
 
    This is an abstract base class for running WSGI applications.  Each instance
@@ -591,8 +627,7 @@ input, output, and error streams.
 
    .. method:: BaseHandler.add_cgi_vars()
 
-      Insert CGI variables for the current request into the :attr:`!environ`
-      attribute.
+      Insert CGI variables for the current request into the :attr:`environ` attribute.
 
    Here are some other methods and attributes you may wish to override. This list
    is only a summary, however, and does not include every method that can be
@@ -651,18 +686,25 @@ input, output, and error streams.
       Return the URL scheme being used for the current request.  The default
       implementation uses the :func:`~wsgiref.util.guess_scheme` function from
       :mod:`wsgiref.util` to guess whether the scheme should be "http" or
-      "https", based on the current request's :attr:`!environ` variables.
+      "https", based on the current request's :attr:`environ` variables.
 
 
    .. method:: BaseHandler.setup_environ()
 
-      Set the :attr:`!environ` attribute to a fully populated WSGI environment.  The
+      Set the :attr:`environ` attribute to a fully populated WSGI environment.  The
       default implementation uses all of the above methods and attributes, plus the
       :meth:`get_stdin`, :meth:`get_stderr`, and :meth:`add_cgi_vars` methods and the
       :attr:`wsgi_file_wrapper` attribute.  It also inserts a ``SERVER_SOFTWARE`` key
       if not present, as long as the :attr:`origin_server` attribute is a true value
       and the :attr:`server_software` attribute is set.
 
+
+   .. attribute:: BaseHandler.environ
+
+      The :data:`~wsgiref.types.WSGIEnvironment` dictionary for the request
+      currently being processed.  It is created by :meth:`setup_environ` and
+      passed to the application by :meth:`run`.
+
    Methods and attributes for customizing exception handling: