gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst
#112757
Conversation
AlexWaygood
added
needs backport to 3.11
bedevere-app
bot
added
docs
| The :meth:`!__or__` method for type objects was added to support the syntax | ||
| ``X | Y``. If a metaclass implements :meth:`!__or__`, the Union may |
There was a problem hiding this comment.
I considered linking to https://docs.python.org/3/reference/datamodel.html#object.__or__, but the data model only discusses implementing __or__ in the context of emulating numeric types, and that's pretty distinct to the purpose of type.__or__
| @@ -383,7 +385,7 @@ Glossary | |||
|
|
|||
| file object | |||
| An object exposing a file-oriented API (with methods such as | |||
| :meth:`read()` or :meth:`write()`) to an underlying resource. Depending | |||
| :meth:`!read` or :meth:`!write`) to an underlying resource. Depending | |||
There was a problem hiding this comment.
It can refer to io.BaseIO.
There was a problem hiding this comment.
I'm not sure there's anything we could specifically link to for either method. io.IOBase does not have read() or write() as abstract methods, so neither IOBase.read nor IOBase.write is explicitly documented currently.
https://docs.python.org/3/library/io.html#io.IOBase
Here's all the IOBase docs say on read and write:
Even though IOBase does not declare read() or write() because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a ValueError (or UnsupportedOperation) when operations they do not support are called.
Specific subclasses of IOBase implement versions of read and write that either only work with raw binary streams or only work with text streams
There was a problem hiding this comment.
Well, and there is a reason to not declare them there. But there are many other references to read and write. It would be nice to have the general interface of them be documented somewhere. It is a different issue.
| @@ -383,7 +385,7 @@ Glossary | |||
|
|
|||
| file object | |||
| An object exposing a file-oriented API (with methods such as | |||
| :meth:`read()` or :meth:`write()`) to an underlying resource. Depending | |||
| :meth:`!read` or :meth:`!write`) to an underlying resource. Depending | |||
There was a problem hiding this comment.
Well, and there is a reason to not declare them there. But there are many other references to read and write. It would be nice to have the general interface of them be documented somewhere. It is a different issue.
|
Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
…es.rst` (pythonGH-112757) (cherry picked from commit e3f670e) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
|
GH-112789 is a backport of this pull request to the 3.12 branch. |
…es.rst` (pythonGH-112757) (cherry picked from commit e3f670e) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
|
GH-112790 is a backport of this pull request to the 3.11 branch. |
This doesn't get rid of all the Sphinx warnings in either file (there are some tricky ones in both that I'd rather defer for now), but it gets rid of most in both.
📚 Documentation preview 📚: https://cpython-previews--112757.org.readthedocs.build/