gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sach98 wants to merge 2 commits into
base:main
Choose a base branch
from
+70 −25
Open

gh-151950: Fix Sphinx reference warnings in wsgiref docs #154498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
665de3a
gh-151950: Fix Sphinx reference warnings in wsgiref docs
sach98 Jul 22, 2026
fa51e57
Document the wsgiref attributes instead of suppressing the references
sach98 Jul 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 70 additions & 24 deletions Doc/library/wsgiref.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
: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.
:meth:`items`, which is the same as the length of the wrapped header list.

@picnixzpicnixzJul 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped



.. method:: Headers.keys()

@picnixzpicnixzJul 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.


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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
:meth:`get_app` exists mainly for the benefit of request handler instances.


.. attribute:: WSGIServer.base_environ

@picnixzpicnixzJul 26, 2026•
edited by hugovk
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here


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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
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

@picnixzpicnixzJul 26, 2026•
edited by hugovk
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section


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:


Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
gh-151950: Fix Sphinx reference warnings in wsgiref docs#154498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

sach98
wants to merge
2
commits into

base:main
Choose a base branch

from


+70

−25

 Open


gh-151950: Fix Sphinx reference warnings in wsgiref docs
#154498
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
665de3a

gh-151950: Fix Sphinx reference warnings in wsgiref docs


sach98 Jul 22, 2026
fa51e57

Document the wsgiref attributes instead of suppressing the references


sach98 Jul 25, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


94 changes: 70 additions & 24 deletions
Doc/library/wsgiref.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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::

Expand DownExpand Up@@ -222,8 +223,26 @@ manipulation of WSGI response headers using a mapping-like interface.
 :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.
 :meth:`items`, which is the same as the length of the wrapped header list.
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "in fact" got dropped


 .. method:: Headers.keys()
@picnixzpicnixzJul 26, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above we say that Headers implement dict.get. So we could maybe reference dict.keys() instead. I do not remember whether it is implemented specifically or not. If .keys() etc are explicit methods on the Header class, you can keep this.

 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
Expand DownExpand Up@@ -282,7 +301,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`.)


Expand DownExpand Up@@ -329,8 +348,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)
Expand All@@ -348,6 +368,16 @@ request. (E.g., using the :func:`shift_path_info` function from
 :meth:`get_app` exists mainly for the benefit of request handler instances.


 .. attribute:: WSGIServer.base_environ
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check if this page documents attributes before methods or vice-versa first. I believe attributes are put first. Then move that one accordingly. It is weird to have this attribute documentation here

 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*
Expand All@@ -362,13 +392,12 @@ request. (E.g., using the :func:`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()
Expand DownExpand Up@@ -403,7 +432,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.


Expand DownExpand Up@@ -530,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
Expand DownExpand Up@@ -645,9 +684,9 @@ 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()
Expand All@@ -659,6 +698,13 @@ input, output, and error streams.
 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
@picnixzpicnixzJul 26, 2026•

edited by hugovk

Loading

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this in the attributes section

 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:


Expand Down

1 change: 0 additions & 1 deletion
Doc/tools/.nitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
Loading