gh-101100: Fix sphinx warnings in `library/email.parser.rst` #136475

LamentXU123 · 2025-07-09T16:11:32Z

before:

C:\Users\admin\Downloads\cpython-main\Doc\library\email.parser.rst:51: WARNING: py:mod reference target not found: email.feedparser [ref.mod]
C:\Users\admin\Downloads\cpython-main\Doc\library\email.parser.rst:116: WARNING: py:attr reference target not found: email.policy.Policy.utf8 [ref.attr]
C:\Users\admin\Downloads\cpython-main\Doc\library\email.parser.rst:156: WARNING: py:meth reference target not found: io.IOBase.read [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\email.parser.rst:161: WARNING: py:attr reference target not found: email.policy.Policy.utf8 [ref.attr]

This PR fix them all. The changes:

email.feedparser is actually referring to email.parser.FeedParser. It is changed to email.parser.FeedParser. See also other places of referrence to email.parser.feedparser to check.
email.policy.Policy.utf8 is actually referring to email.policy.EmailPolicy.utf8. It is changed to email.policy.EmailPolicy.utf8
io.IOBase.read is actually referring to io.TextIOBase.read. See also other places of referrence to io.TextIOBase.read to check. I'm not pretty sure about this.

Issue: Fix all Sphinx reference warnings in the documentation #101100

📚 Documentation preview 📚: https://cpython-previews--136475.org.readthedocs.build/

hugovk · 2025-07-11T09:37:05Z

Thanks.

miss-islington-app · 2025-07-11T09:37:05Z

Thanks @LamentXU123 for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…ythonGH-136475) (cherry picked from commit 515b3d1) Co-authored-by: Weilin Du <[email protected]>

bedevere-app · 2025-07-11T09:37:15Z

GH-136532 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2025-07-11T09:37:20Z

GH-136533 is a backport of this pull request to the 3.13 branch.

…H-136475) (#136532) Co-authored-by: Weilin Du <[email protected]>

…H-136475) (#136533) Co-authored-by: Weilin Du <[email protected]>

…ython#136475)

serhiy-storchaka · 2025-07-11T17:12:10Z

Doc/library/email.parser.rst

      Read all the data from the binary file-like object *fp*, parse the
      resulting bytes, and return the message object.  *fp* must support
-      both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+      both the :meth:`~io.IOBase.readline` and the :meth:`~io.TextIOBase.read`


This is a binary file-like object. io.TextIOBase.read is incorrect reference.

Yes I'm not quite sure about this change. There is indeed no doc to ~io.IOBase.read, I suggest to add one here maybe in the future issues(?)

Now, lets subpress this link. It is incorrect.

It is better to add the documentation or the anchor for io.IOBase.read, but this is a separate issue. We will need to find also all silenced references to it.

For now, just restore the old code. Without silencing unresolved references.

IOBase doesn't declare read on purpose because:

Even though IOBase does not declare read, readinto, or write because
their signatures will vary, implementations and clients should
consider those methods part of the interface.

Currently, in io.rst, we also suppress the read method for IOBase. So, we should consider read as a "protocol" that follows "some" signature whose defaults have "some" meanings (again it depends on the object itself).

I suggest that we revert this entirely and keep the warning to know in the future which read() protocol it should follow.

Please see PR #136629 to revert.

serhiy-storchaka · 2025-07-11T17:14:23Z

Doc/library/email.parser.rst


-The :class:`BytesFeedParser`, imported from the :mod:`email.feedparser` module,
-provides an API that is conducive to incremental parsing of email messages,
+The :class:`BytesFeedParser`, imported from the :mod:`email.parser.FeedParser`


The name of the module is email.feedparser. email.parser.FeedParser is not a module.

Oups, sry for this overlook

Same for this. It seems like we don't get a doc for email.feedparser. We can add it later. Now I suggest to subpress the link.

I suggest we don't suppress links but keep the warnings so to know which objects need to be documented. Suppressing the links is not a good idea here.

LamentXU123 · 2025-07-11T17:36:11Z

Hi @hugovk, the two changes are indeed incorrect. Please revert it. Sry for the overlook.

Just subpress the two links mentioned before is OK. sry again.

…ython#136475)

….rst` (python#136475)" This reverts commit 515b3d1.

…rser.rst` (#136475)" (#136629)

…ail.parser.rst` (pythonGH-136475)" (pythonGH-136629) (cherry picked from commit 5bbf30e) Co-authored-by: Hugo van Kemenade <[email protected]>

…mail.parser.rst` (GH-136475)" (GH-136629) (#136646) Co-authored-by: Hugo van Kemenade <[email protected]>

…mail.parser.rst` (GH-136475)" (GH-136629) (#136647) Co-authored-by: Hugo van Kemenade <[email protected]>

…ython#136475)

…ail.parser.rst` (python#136475)" (python#136629)

…ython#136475)

…ail.parser.rst` (python#136475)" (python#136629)

…rst` (pythonGH-136475) (python#136532) Co-authored-by: Weilin Du <[email protected]>

…rary/email.parser.rst` (pythonGH-136475)" (pythonGH-136629) (python#136646) Co-authored-by: Hugo van Kemenade <[email protected]>

LamentXU123 added 2 commits July 10, 2025 00:02

Update email.parser.rst

c3e13aa

Update .nitignore

a4bb5b8

LamentXU123 requested review from a team, AA-Turner and hugovk as code owners July 9, 2025 16:11

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Jul 9, 2025

bedevere-app bot mentioned this pull request Jul 9, 2025

Fix all Sphinx reference warnings in the documentation #101100

Open

github-project-automation bot added this to Docs PRs Jul 9, 2025

github-project-automation bot moved this to Todo in Docs PRs Jul 9, 2025

hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 11, 2025

hugovk merged commit 515b3d1 into python:main Jul 11, 2025
36 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Jul 11, 2025

bedevere-app bot removed the awaiting review label Jul 11, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 11, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

0111ec9

…ythonGH-136475) (cherry picked from commit 515b3d1) Co-authored-by: Weilin Du <[email protected]>

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 11, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

2db5f03

…ythonGH-136475) (cherry picked from commit 515b3d1) Co-authored-by: Weilin Du <[email protected]>

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 11, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jul 11, 2025

hugovk pushed a commit that referenced this pull request Jul 11, 2025

[3.14] gh-101100: Fix sphinx warnings in library/email.parser.rst (G…

ec15251

…H-136475) (#136532) Co-authored-by: Weilin Du <[email protected]>

hugovk pushed a commit that referenced this pull request Jul 11, 2025

[3.13] gh-101100: Fix sphinx warnings in library/email.parser.rst (G…

aa4bb1c

…H-136475) (#136533) Co-authored-by: Weilin Du <[email protected]>

AndPuQing pushed a commit to AndPuQing/cpython that referenced this pull request Jul 11, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

52ff16e

…ython#136475)

serhiy-storchaka reviewed Jul 11, 2025

View reviewed changes

Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

777d039

…ython#136475)

picnixz pushed a commit to picnixz/cpython that referenced this pull request Jul 13, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

44ae03b

…ython#136475)

hugovk added a commit to hugovk/cpython that referenced this pull request Jul 13, 2025

Revert "pythongh-101100: Fix sphinx warnings in `library/email.parser…

63f9435

….rst` (python#136475)" This reverts commit 515b3d1.

hugovk mentioned this pull request Jul 13, 2025

Partially revert "gh-101100: Fix sphinx warnings in library/email.parser.rst (#136475)" #136629

Merged

hugovk added a commit that referenced this pull request Jul 14, 2025

Partially revert "gh-101100: Fix sphinx warnings in `library/email.pa…

5bbf30e

…rser.rst` (#136475)" (#136629)

hugovk added a commit that referenced this pull request Jul 14, 2025

[3.14] Partially revert "gh-101100: Fix sphinx warnings in `library/e…

bbbbb2e

…mail.parser.rst` (GH-136475)" (GH-136629) (#136646) Co-authored-by: Hugo van Kemenade <[email protected]>

hugovk added a commit that referenced this pull request Jul 14, 2025

[3.13] Partially revert "gh-101100: Fix sphinx warnings in `library/e…

2115e71

…mail.parser.rst` (GH-136475)" (GH-136629) (#136647) Co-authored-by: Hugo van Kemenade <[email protected]>

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

e5caafa

…ython#136475)

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025

Partially revert "pythongh-101100: Fix sphinx warnings in `library/em…

58a5fdc

…ail.parser.rst` (python#136475)" (python#136629)

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025

pythongh-101100: Fix sphinx warnings in library/email.parser.rst (p…

92f7311

…ython#136475)

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025

Partially revert "pythongh-101100: Fix sphinx warnings in `library/em…

8f7d5a3

…ail.parser.rst` (python#136475)" (python#136629)

kumaraditya303 pushed a commit to miss-islington/cpython that referenced this pull request Sep 9, 2025

[3.14] pythongh-101100: Fix sphinx warnings in `library/email.parser.…

d4927fa

…rst` (pythonGH-136475) (python#136532) Co-authored-by: Weilin Du <[email protected]>

Uh oh!

gh-101100: Fix sphinx warnings in library/email.parser.rst #136475

gh-101100: Fix sphinx warnings in library/email.parser.rst #136475

Uh oh!

Conversation

LamentXU123 commented Jul 9, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

hugovk commented Jul 11, 2025

Uh oh!

miss-islington-app bot commented Jul 11, 2025

Uh oh!

bedevere-app bot commented Jul 11, 2025

Uh oh!

bedevere-app bot commented Jul 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gh-101100: Fix sphinx warnings in `library/email.parser.rst` #136475

gh-101100: Fix sphinx warnings in `library/email.parser.rst` #136475

LamentXU123 commented Jul 9, 2025 •

edited by github-actions bot

Loading

LamentXU123 Jul 11, 2025 •

edited

Loading

LamentXU123 commented Jul 11, 2025 •

edited

Loading