gh-151950: Fix Sphinx reference warnings in wsgiref docs by sach98 · Pull Request #154498 · python/cpython

sach98 · 2026-07-22T17:39:59Z

Fixes the 18 nit-picky Sphinx reference warnings in Doc/library/wsgiref.rst and removes the file from Doc/tools/.nitignore.

Where a correct target already exists, the reference is qualified so it resolves:

The filelike object's read and close become :meth:`~io.BufferedIOBase.read``` and :meth:~io.IOBase.close```. This matches the existing ``:meth:~io.BufferedIOBase.write``` reference further down the same file.
shift_path_info and guess_scheme are documented in wsgiref.util but were referenced from a different module context, so they are now qualified.
serve_forever and handle_request point at socketserver.BaseServer, which is where WSGIServer actually inherits them from.

The remaining names have no documented target anywhere: Headers.keys, Headers.values, Headers.items, WSGIServer.base_environ, BaseHandler.environ and SimpleHandler.stdin / stdout / stderr are described only in prose, and paste.lint is third party. Those use the ! prefix, which keeps the semantic markup and drops the link.

I kept this to reference fixes so the diff stays limited to removing the warnings. If you would prefer the undocumented Headers methods and handler attributes to become proper .. method:: and .. attribute:: entries instead (as was done for the lzma constants in gh-151949), I am happy to do that here or in a follow-up.

Verified with a fresh nit-picky build: warnings for this file go from 18 to 0, total build warnings go from 1352 to 1334, no new warnings elsewhere, and Doc/tools/check-warnings.py --fail-if-regression --fail-if-improved exits 0.

Issue: Fix Sphinx reference warnings in various Doc/library/ files #151950

python-cla-bot · 2026-07-22T17:40:04Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-07-22T17:44:10Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33759260 | 📁 Comparing fa51e57 against main (3479e45)

🔍 Preview build

11 files changed · ± 11 modified

± Modified

picnixz · 2026-07-24T10:44:26Z

The purpose was to document those attributes, not suppress them. Please do so.

picnixz

Please document the header objects properly.

bedevere-app · 2026-07-24T10:45:01Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes, you will be put in the comfy chair!

Replace the "!"-suppressed references with real targets: .. method:: directives for Headers.keys(), Headers.values() and Headers.items(), and .. attribute:: directives for WSGIServer.base_environ, BaseHandler.environ and SimpleHandler's stdin, stdout and stderr. Correct the SimpleHandler paragraph while documenting it: the constructor stores the supplied environment in base_env, not environ, and add_cgi_vars() merges it into BaseHandler.environ during setup_environ(). paste.lint (a third-party module) and FileWrapper.close (bound conditionally from the wrapped object, never defined on the class) keep the "!" prefix, since neither can have a real target.

sach98 · 2026-07-25T20:51:13Z

Thanks, that's fair. I've replaced the suppressions with real targets:

Headers.keys(), Headers.values() and Headers.items() are now documented with .. method:: directives alongside get_all() and add_header(), and the paragraph above them no longer repeats what they say.
WSGIServer.base_environ is now an .. attribute::.
BaseHandler.environ is now an .. attribute::, which is what the add_cgi_vars(), get_scheme() and setup_environ() references resolve to.
SimpleHandler.stdin, stdout and stderr are now documented attributes.

One thing I ran into while doing that: the SimpleHandler paragraph was inaccurate. It said the supplied environment is stored in an environ attribute, but __init__ stores it in base_env, and add_cgi_vars() merges that into BaseHandler.environ during setup_environ(). Rather than document a SimpleHandler.environ that does not hold what the sentence claimed, I reworded the sentence to match the code. Happy to split that into its own PR if you would rather keep this one purely markup.

Two references are still suppressed, and I believe that is correct in both cases:

:mod:`!paste.lint`: a third-party module (Ian Bicking's Paste). No target exists in CPython's docs or in any intersphinx inventory.
:meth:`!close` on FileWrapper: FileWrapper never defines close(). __init__ does if hasattr(filelike, 'close'): self.close = filelike.close, so the attribute exists only for some wrapped objects, and it is the wrapped object's own bound method. A .. method:: FileWrapper.close() directive would assert that it is always present, which is not true, and the surrounding prose already states the conditional behaviour. Happy to document it anyway, with the condition spelled out in the body, if you prefer.

One more that I left alone deliberately, so tell me if you want it in scope: the class description still points get and setdefault at dict.get and dict.setdefault, but Headers defines its own, with case-insensitive lookup and multi-valued-header semantics that the dict methods do not have. That text predates this PR so I did not touch it, but it is the same kind of fix if you want it here.

I have made the requested changes; please review again

bedevere-app · 2026-07-25T20:51:18Z

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

picnixz

If possible add versionadded/versionchanged directives to methods/atters that were not present at the beginning (i.e. if they were added later).

And also, if you using an agent, make sure that you review its output. Agents are quite bad at placement in my experience.

picnixz · 2026-07-26T07:35:45Z

   ``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.


The "in fact" got dropped

picnixz · 2026-07-26T07:40:19Z

+   :meth:`items`, which is the same as the length of the wrapped header list.
+
+
+   .. method:: Headers.keys()


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.

picnixz · 2026-07-26T07:41:49Z

   :meth:`get_app` exists mainly for the benefit of request handler instances.


+   .. attribute:: WSGIServer.base_environ


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

picnixz · 2026-07-26T07:43:49Z

      and the :attr:`server_software` attribute is set.

+
+   .. attribute:: BaseHandler.environ


Move this in the attributes section

bedevere-app · 2026-07-26T07:45:18Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

pythongh-151950: Fix Sphinx reference warnings in wsgiref docs

665de3a

sach98 requested review from AA-Turner, StanFromIreland and hugovk as code owners July 22, 2026 17:40

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Jul 22, 2026

github-project-automation Bot added this to Docs PRs Jul 22, 2026

github-project-automation Bot moved this to Todo in Docs PRs Jul 22, 2026

bedevere-app Bot mentioned this pull request Jul 22, 2026

Fix Sphinx reference warnings in various Doc/library/ files #151950

Open

bedevere-app Bot added the awaiting review label Jul 22, 2026

picnixz requested changes Jul 24, 2026

View reviewed changes

bedevere-app Bot added awaiting changes and removed awaiting review labels Jul 24, 2026

bedevere-app Bot added awaiting change review and removed awaiting changes labels Jul 25, 2026

bedevere-app Bot requested a review from picnixz July 25, 2026 20:51

picnixz requested changes Jul 26, 2026

View reviewed changes

bedevere-app Bot added awaiting changes and removed awaiting change review labels Jul 26, 2026

		:meth:`items`, which is the same as the length of the wrapped header list.


		.. method:: Headers.keys()

		:meth:`get_app` exists mainly for the benefit of request handler instances.


		.. attribute:: WSGIServer.base_environ

		and the :attr:`server_software` attribute is set.


		.. attribute:: BaseHandler.environ

Uh oh!

Uh oh!

Conversation

sach98 commented Jul 22, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

picnixz commented Jul 24, 2026

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-app Bot commented Jul 24, 2026

Uh oh!

sach98 commented Jul 25, 2026

Uh oh!

bedevere-app Bot commented Jul 25, 2026

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

picnixz Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

picnixz Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

picnixz Jul 26, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz Jul 26, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app Bot commented Jul 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sach98 commented Jul 22, 2026 •

edited by bedevere-app Bot

Loading

python-cla-bot Bot commented Jul 22, 2026 •

edited

Loading

read-the-docs-community Bot commented Jul 22, 2026 •

edited

Loading

picnixz Jul 26, 2026 •

edited by hugovk

Loading

picnixz Jul 26, 2026 •

edited by hugovk

Loading