gh-101100: Fix sphinx warnings in library/email.parser.rst
#136475
Conversation
|
Thanks. |
|
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 <108666168+LamentXU123@users.noreply.github.com>
…ythonGH-136475) (cherry picked from commit 515b3d1) Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
|
GH-136532 is a backport of this pull request to the 3.14 branch. |
|
GH-136533 is a backport of this pull request to the 3.13 branch. |
| @@ -155,11 +155,11 @@ message body, instead setting the payload to the raw body. | |||
|
|
|||
| 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` | |||
There was a problem hiding this comment.
This is a binary file-like object. io.TextIOBase.read is incorrect reference.
There was a problem hiding this comment.
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(?)
There was a problem hiding this comment.
Now, lets subpress this link. It is incorrect.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| @@ -48,8 +48,8 @@ methods. | |||
| FeedParser API | |||
| ^^^^^^^^^^^^^^ | |||
|
|
|||
| 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` | |||
There was a problem hiding this comment.
The name of the module is email.feedparser. email.parser.FeedParser is not a module.
There was a problem hiding this comment.
Oups, sry for this overlook
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
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. |
before:
This PR fix them all. The changes:
email.feedparseris actually referring to email.parser.FeedParser. It is changed toemail.parser.FeedParser. See also other places of referrence toemail.parser.feedparserto check.email.policy.Policy.utf8is actually referring to email.policy.EmailPolicy.utf8. It is changed toemail.policy.EmailPolicy.utf8io.IOBase.readis actually referring to io.TextIOBase.read. See also other places of referrence toio.TextIOBase.readto check. I'm not pretty sure about this.📚 Documentation preview 📚: https://cpython-previews--136475.org.readthedocs.build/