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

[Dutcho]

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

• GH-90744: Fix erroneous doc links in the sys module #101319
• [3.11] gh-90744: Fix erroneous doc links in the sys module (GH-101319) #102321
• [3.10] gh-90744: Fix erroneous doc links in the sys module (GH-101319) #102322

[Dutcho]

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

[merwok]

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?

[AlexWaygood]

enum.property is new in Python 3.11, so this isn't an issue for 3.9 or 3.10.

[ethanfurman]

What does the tilde (~) do?

[AlexWaygood]

:func:`~enum.property` means that the visible text on the webpage will be "property", but the link will be to enum.property rather than builtins.property.

[AlexWaygood]

The ~ always only uses the final part of the name for the display text, e.g. ~collections.abc.Iterator would have "Iterator" as the visible text on the website.

[meersuri]

(First time contributor here seeking guidance) I see that this problem of automatically linking to the unintended page has occurred in other parts of the docs and has been handled in another way - In Doc/library/functions.rst, local targets are used with replacement texts-

unintended linking code- :func:`dict`
local target code- |func-dict|_
and this substitution is added- .. |func-dict| replace:: ``dict()``

Would this be the preferred way of solving this? I tried this change and it achieves the correct linking for me

[merwok]

Using a substitution is necessary when we need code markup and a link.

For this bug, the simple ~ markup will be enough.

[merwok]

The same problem exists for any attribute that has the same name as a builtin, see for example https://docs.python.org/3/library/sys.html#sys.float_info

[meersuri]

I looked through the sys.float_info docs and I guess that you are referring to the max and min attributes of sys.float_info that are linking to the built-in max() and min() functions?

In that case as there is no documentation for the max and min attributes of sys.float_info, should they not link to anything?

[merwok]

Yes, I was referring to these two attributes.
They should not link to anything: the place I linked *is* the documentation for them.
Other instances of this problem could be listed in this ticket and fixed by the same PR (doesn’t matter than enum.property is only for 3.11, the backport PRs can be a little different), or tracked in a separate ticket if that seems more convenient.

[meersuri]

It took me some time to figure out how to prevent the creation of a reference/hyperlink using the ! prefix. I've made the change to remove the references to the max and min attributes of sys.float_info and pushed.

How do I find other instances of this problem? Is there a systematic way to look for such references?

[JelleZijlstra]

How do I find other instances of this problem? Is there a systematic way to look for such references?

You could write a script that goes something like this, iterating over all the docs RST files:

• Find all definitions in the file (e.g. .. decorator:: property)
• Filter to those that have names that also appear in builtins
• Find any links using those names within the same file

That would catch the enum.property case, but not the float_info one Éric noticed, because sys.rst doesn't define `max` at all. To catch that one, you could look at the link role: sys.rst links to it with :const:`max`, but functions.rst defines it as `.. function:: max`. Mismatches like that could be another clue that something is wrong (but there are some legitimate reasons why the roles won't match perfectly, like "decorator" in the definition vs. "func" in the link).

[meersuri]

Can someone guide me on why I'm getting a no-new-line at end of file error for the NEWS entry when I didnt change this file in the last commit and it passed the Azure checks earlier

Error: [1] ../Misc/NEWS.d/next/Documentation/2022-02-08-15-38-16.bpo-46586.6qVFVL.rst:0: No newline at end of file (no-newline-at-end-of-file). Do I need to manually add the new line?

[zware]

An updated reST linting check was added between the time you created the PR and your last update. As Jelle noted on the PR, there doesn't need to be a NEWS entry for this anyway.

We might have an issue there if sphinx-lint is going to have an issue with no trailing newline and blurb-it isn't going to add a trailing newline, though. (+mdk)

[merwok]

Thinking about it again: The issue is that these tables (for sys.float_info and other named tuples / structseqs) use the const role, which is not meant to identify attributes but to link to them (similar to func, mod, data, etc). In other words we are fixing an issue that a wrong target is used, but we should not be linking for a target at all, this is the target. So if we can’t use the equivalent of directives function, module, etc (that define the targets of func, mod, etc), then maybe they should be just ``name``, not :role:`name`.

[ethanfurman]

New changeset 9d9cfd6 by Meer Suri in branch 'main':
bpo-46586: Fix documentation links (GH-31216)
9d9cfd6

[meersuri]

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]

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]

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]

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`

[furkanonder]

The PR is ready for review.