GeezerVison is showing github.com — In documentation same-named attributes erroneously link to built-in names · Issue #90744 · python/cpython

In documentation same-named attributes erroneously link to built-in names #90744

New issue

Copy link

New issue

Copy link

Closed

In documentation same-named attributes erroneously link to built-in names#90744

Copy link

Labels

3.11only security fixesonly security fixesdocsDocumentation in the Doc dirDocumentation in the Doc direasytype-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

Description

Dutcho

mannequin

opened

on Jan 30, 2022

Issue body actions

BPO	46586
Nosy	@merwok, @ethanfurman, @zware, @JelleZijlstra, @JulienPalard, @Dutcho, @AlexWaygood, @meersuri
PRs	bpo-46586: Fix documentation links #31216 bpo-46586: Fix more erroneous doc links to builtins #31429

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ethanfurman'
closed_at = None
created_at = <Date 2022-01-30.15:12:05.843>
labels = ['easy', '3.11', 'type-bug', 'docs']
title = 'In documentation contents enum.property erroneously links to built-in property'
updated_at = <Date 2022-02-19.06:42:30.886>
user = 'https://github.com/Dutcho'

bugs.python.org fields:

activity = <Date 2022-02-19.06:42:30.886>
actor = 'meersuri'
assignee = 'ethan.furman'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2022-01-30.15:12:05.843>
creator = 'Dutcho'
dependencies = []
files = []
hgrepos = []
issue_num = 46586
keywords = ['patch', 'easy']
message_count = 21.0
messages = ['412156', '412523', '412543', '412545', '412551', '412552', '412644', '412789', '412875', '412903', '412909', '413007', '413008', '413009', '413010', '413011', '413115', '413181', '413183', '413185', '413228']
nosy_count = 10.0
nosy_names = ['eric.araujo', 'docs@python', 'ethan.furman', 'python-dev', 'zach.ware', 'JelleZijlstra', 'mdk', 'Dutcho', 'AlexWaygood', 'meersuri']
pr_nums = ['31216', '31429']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46586'
versions = ['Python 3.11']

Linked PRs

Activity

Dutcho commented on Jan 30, 2022
Dutchomannequin
on Jan 30, 2022
MannequinAuthor
More actions
https://docs.python.org/3.11/library/enum.html#module-contents contains:
property()
Allows Enum members to have attributes without conflicting with member names.

In above, property() is links to:
https://docs.python.org/3.11/library/functions.html#property
instead of to the proper:
https://docs.python.org/3.11/library/enum.html#enum.property
Dutcho
assigned
docspython
on Jan 30, 2022
Dutcho
added
3.11only security fixesonly security fixes

docsDocumentation in the Doc dirDocumentation in the Doc dir
on Jan 30, 2022
Dutcho
assigned
docspython
on Jan 30, 2022
Dutcho
added
3.11only security fixesonly security fixes

docsDocumentation in the Doc dirDocumentation in the Doc dir
on Jan 30, 2022
AlexWaygood
assigned
ethanfurman
and unassigned
docspython
on Jan 30, 2022
AlexWaygood
added
type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error
on Jan 30, 2022
AlexWaygood
assigned
ethanfurman
and unassigned
docspython
on Jan 30, 2022
AlexWaygood
added
type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error
on Jan 30, 2022
merwok commented on Feb 4, 2022
merwok
on Feb 4, 2022
Member
More actions
Changing the markup to this should fix the link without changing the text:

:func:`~enum.property`

Would you like to turn this into a pull request?
merwok
added
easy
on Feb 4, 2022
24 remaining items
meersuri commented on Feb 13, 2022
meersurimannequin
on Feb 13, 2022
Mannequin
More actions
Thanks Jelle for the cool idea of the script to look for more instances of this problem. I've been working on this script and am still refining it, but one of the candidates that my program returned is in zipfile.rst - https://docs.python.org/3.11/library/zipfile.html?highlight=zipfile#zipfile.ZipFile.open

Changed in version 3.6: open() can now be used to write files into the archive with the mode='w' option.
Changed in version 3.6: Calling open() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

Here the first instance of open() points to the builtins function rather than ZipFile.open(), whereas the second instance points to ZipFile.open(). Seems like a true positive to me, what do you think?
meersuri commented on Feb 13, 2022
meersurimannequin
on Feb 13, 2022
Mannequin
More actions
Also this one?-

https://docs.python.org/3.11/library/urllib.request.html?highlight=urllib%20request#urllib.request.OpenerDirector.open

Arguments, return values and exceptions raised are the same as those of urlopen() (which simply calls the open() method on the currently installed global OpenerDirector).

open() points to the builtins function but the markup used is :meth:`open` and the logic of the sentence suggests the link was meant to be to OpenerDirector.open()
meersuri commented on Feb 13, 2022
meersurimannequin
on Feb 13, 2022
Mannequin
More actions
Looks like another one -
https://docs.python.org/3.11/library/fileinput.html#fileinput.hook_encoded

Deprecated since version 3.10: This function is deprecated since input() and FileInput now have encoding and errors parameters.

The input() here points to builtins which doesnt have the mentioned parameters
meersuri commented on Feb 14, 2022
meersurimannequin
on Feb 14, 2022
Mannequin
More actions
https://docs.python.org/3.11/library/io.html?highlight=io#text-i-o -

The easiest way to create a text stream is with open(), optionally specifying an encoding:

https://docs.python.org/3.11/library/io.html?highlight=io#binary-i-o -

The easiest way to create a binary stream is with open() with 'b' in the mode string:

For both of these cases, the markup for the open() is :meth:`open()` but it links to the builtins open(), which I see is an alias of io.open() so maybe it doesn't matter?
Another question is why do only these two instances use :meth: while the other instances in the file use :func: (some refer directly to builtins open() so its understandable, but not all instances)
I'm wondering if the above two should be left alone or changed to :meth:`~io.open` or even :func:`open`
ezio-melotti
transferred this issue from on Apr 10, 2022
ethanfurman
changed the title ~~[-]In documentation contents enum.property erroneously links to built-in property[/-]~~ [+]In documentation same-named attributes erroneously link to built-in names[/+] on Jun 23, 2022
ethanfurman
removed their assignment
on Jun 23, 2022
furkanonder commented on Feb 13, 2023
furkanonder
on Feb 13, 2023
Contributor
More actions
The PR is ready for review.
hugovk
added 3 commits that reference this issue on Feb 28, 2023
GH-90744: Fix erroneous doc links in the sys module (#101319)
85b1fc1
pythonGH-90744: Fix erroneous doc links in the sys module (python#101319
5199c40
pythonGH-90744: Fix erroneous doc links in the sys module (python#101319
a0fb9b3
carljm
added a commit that references this issue on Feb 28, 2023
Merge branch 'main' into inlinecomp2
73dc0ed
hugovk
added 2 commits that reference this issue on Mar 2, 2023
[3.11] gh-90744: Fix erroneous doc links in the sys module (GH-101319) (
9a5f2e8
[3.10] gh-90744: Fix erroneous doc links in the sys module (GH-101319) (
a8f9a82
hugovk
closed this as completed on Mar 2, 2023