From 665de3a649821d0ea431af6e5f7fee11d18f44fb Mon Sep 17 00:00:00 2001 From: sach98 <70027274+sach98@users.noreply.github.com> Date: Wed, 22 Jul 2026 23:07:58 +0530 Subject: [PATCH 1/2] gh-151950: Fix Sphinx reference warnings in wsgiref docs --- Doc/library/wsgiref.rst | 50 ++++++++++++++++++++++------------------- Doc/tools/.nitignore | 1 - 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index 2af54dc2a7e632..537f2dea5f398e 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -163,12 +163,13 @@ also provides these miscellaneous utilities: The resulting objects are :term:`iterable`\ s. As the object is iterated over, the optional *blksize* parameter will be repeatedly passed to the *filelike* - object's :meth:`read` method to obtain bytestrings to yield. When :meth:`read` - returns an empty bytestring, iteration is ended and is not resumable. + object's :meth:`~io.BufferedIOBase.read` method to obtain bytestrings to + yield. When :meth:`~io.BufferedIOBase.read` returns an empty bytestring, + iteration is ended and is not resumable. - If *filelike* has a :meth:`close` method, the returned object will also have a - :meth:`close` method, and it will invoke the *filelike* object's :meth:`close` - method when called. + If *filelike* has a :meth:`~io.IOBase.close` method, the returned object will + also have a :meth:`!close` method, and it will invoke the *filelike* object's + :meth:`~io.IOBase.close` method when called. Example usage:: @@ -218,12 +219,13 @@ 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. In fact, the :meth:`!items` method just returns a copy + of the wrapped header list. Calling ``bytes()`` on a :class:`Headers` object returns a formatted bytestring suitable for transmission as HTTP response headers. Each header is placed on a @@ -282,7 +284,7 @@ that serves WSGI applications. Each server instance serves a single WSGI application on a given host and port. If you want to serve multiple applications on a single host and port, you should create a WSGI application that parses ``PATH_INFO`` to select which application to invoke for each -request. (E.g., using the :func:`shift_path_info` function from +request. (E.g., using the :func:`~wsgiref.util.shift_path_info` function from :mod:`wsgiref.util`.) @@ -329,8 +331,9 @@ request. (E.g., using the :func:`shift_path_info` function from function can handle all the details for you. :class:`WSGIServer` is a subclass of :class:`http.server.HTTPServer`, so all - of its methods (such as :meth:`serve_forever` and :meth:`handle_request`) are - available. :class:`WSGIServer` also provides these WSGI-specific methods: + of its methods (such as :meth:`~socketserver.BaseServer.serve_forever` and + :meth:`~socketserver.BaseServer.handle_request`) are available. + :class:`WSGIServer` also provides these WSGI-specific methods: .. method:: WSGIServer.set_app(application) @@ -365,7 +368,7 @@ request. (E.g., using the :func:`shift_path_info` function from 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 + :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`. @@ -403,7 +406,7 @@ absence of errors from this module does not necessarily mean that errors do not exist. However, if this module does produce an error, then it is virtually certain that either the server or application is not 100% compliant. -This module is based on the :mod:`paste.lint` module from Ian Bicking's "Python +This module is based on the :mod:`!paste.lint` module from Ian Bicking's "Python Paste" library. @@ -531,8 +534,8 @@ input, output, and error streams. :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. + streams are stored in the :attr:`!stdin`, :attr:`!stdout`, :attr:`!stderr`, + and :attr:`!environ` attributes. The :meth:`~io.BufferedIOBase.write` method of *stdout* should write each chunk in full, like :class:`io.BufferedIOBase`. @@ -588,7 +591,8 @@ 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 @@ -645,14 +649,14 @@ input, output, and error streams. .. method:: BaseHandler.get_scheme() Return the URL scheme being used for the current request. The default - implementation uses the :func:`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. + 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. .. 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 diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index ab592cfa5a1bbb..181f74464710d5 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -24,7 +24,6 @@ Doc/library/termios.rst Doc/library/test.rst Doc/library/urllib.parse.rst Doc/library/urllib.request.rst -Doc/library/wsgiref.rst Doc/library/xml.dom.minidom.rst Doc/library/xml.dom.pulldom.rst Doc/library/xml.dom.rst From fa51e57b7d31560d8d102764afbf95c3907a92f5 Mon Sep 17 00:00:00 2001 From: sach98 <70027274+sach98@users.noreply.github.com> Date: Sun, 26 Jul 2026 02:16:41 +0530 Subject: [PATCH 2/2] 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. --- Doc/library/wsgiref.rst | 84 ++++++++++++++++++++++++++++++----------- 1 file changed, 63 insertions(+), 21 deletions(-) diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index 537f2dea5f398e..af49c0a9cc6640 100644 --- a/Doc/library/wsgiref.rst +++ b/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: