gh-151950: Fix Sphinx reference warnings in wsgiref docs

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.

[sach98]

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]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

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

🔍 Preview build

11 files changed · ± 11 modified

±Modified

• license.html
• library/asyncio-eventloop.html
• library/ctypes.html
• library/difflib.html
• library/exceptions.html
• library/logging.handlers.html
• library/msvcrt.html
• library/stdtypes.html
• library/wsgiref.html
• whatsnew/3.16.html
• and 1 more...

[picnixz]

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

[picnixz]

Please document the header objects properly.

[bedevere-app]

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!

[sach98]

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]

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]

The "in fact" got dropped

[picnixz]

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]

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]

Move this in the attributes section

[bedevere-app]

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.