Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add BytesIO alias to fix missing references in docs #7737

Closed
wants to merge 1 commit into from

Conversation

nulano
Copy link
Contributor

@nulano nulano commented Jan 20, 2024

A warning has started appearing in the Docs build in main due to type hints added in #7727 and #7728.

/opt/hostedtoolcache/Python/3.12.1/x64/lib/python3.12/site-packages/PIL/GdImageFile.py:docstring of PIL.GdImageFile.open:1: WARNING: py:class reference target not found: _io.BytesIO
/opt/hostedtoolcache/Python/3.12.1/x64/lib/python3.12/site-packages/PIL/MpegImagePlugin.py:docstring of PIL.MpegImagePlugin.BitStream:1: WARNING: py:class reference target not found: _io.BytesIO

This PR fixes it using autodoc_type_aliases.

@hugovk
Copy link
Member

hugovk commented Jan 20, 2024

io.BytesIO is incorrectly converted to _io.BytesIO

Do you know where this is coming from?

@nulano
Copy link
Contributor Author

nulano commented Jan 20, 2024

io imports BytesIO from the _io module where it is defined using the full name _io.BytesIO: https://github.com/python/cpython/blob/e6495159f6f2ca4fe3b5143c62fc2ad5873ef54f/Lib/io.py#L55-L56
https://github.com/python/cpython/blob/e6495159f6f2ca4fe3b5143c62fc2ad5873ef54f/Modules/_io/bytesio.c#L1057

This name can be observed from the console:

Python 3.11.4 (tags/v3.11.4:d2340ef, Jun  7 2023, 05:45:37) [MSC v.1934 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import io
>>> io.BytesIO
<class '_io.BytesIO'>

However, it is listed under io.BytesIO in the documentation (note the url):
https://docs.python.org/3/library/io.html#io.BytesIO

I'm not sure if this would qualify as a CPython bug, a docs.python.org bug, or a sphinx autodoc bug.

@hugovk
Copy link
Member

hugovk commented Jan 20, 2024

I wonder what's changed for it to start happening now? The last Python releases were in December, and Sphinx was in September. The direct docs dependencies also haven't recently changed. It feels like something that should be fixed upstream, somewhere, if possible...

@nulano
Copy link
Contributor Author

nulano commented Jan 20, 2024

I wonder what's changed for it to start happening now?

These references are in type hints added in #7727 and #7728.

@@ -40,6 +40,11 @@

intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

# io.BytesIO is incorrectly converted to _io.BytesIO, this alias prevents that
autodoc_type_aliases = {
"BytesIO": "~io.BytesIO",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"BytesIO": "~io.BytesIO",
"BytesIO": "io.BytesIO",

I find that the tilde isn't necessary? radarhere@f698cb9 / https://github.com/radarhere/Pillow/actions/runs/7599204419/job/20695972684

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tilde is for consistency with other types.
With the tilde:
image

Without the tilde:
image

Compare with e.g. typing.BinaryIO:
image

@radarhere
Copy link
Member

Closing, in favour of #7750

@radarhere radarhere closed this Feb 8, 2024
@nulano nulano deleted the bytesio branch February 20, 2024 20:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants