This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: In documentation contents erroneously links to built-in property
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: ethan.furman Nosy List: AlexWaygood, Dutcho, JelleZijlstra, docs@python, eric.araujo, ethan.furman, mdk, meersuri, python-dev, zach.ware
Priority: normal Keywords: easy, patch

Created on 2022-01-30 15:12 by Dutcho, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 31216 merged python-dev, 2022-02-08 15:30
PR 31429 open meersuri, 2022-02-19 06:42
Messages (21)
msg412156 - (view) Author: (Dutcho) Date: 2022-01-30 15:12 contains:
Allows Enum members to have attributes without conflicting with member names.

In above, property() is links to:
instead of to the proper:
msg412523 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-02-04 18:34
Changing the markup to this should fix the link without changing the text:


Would you like to turn this into a pull request?
msg412543 - (view) Author: Alex Waygood (AlexWaygood) * (Python triager) Date: 2022-02-04 21:55
`` is new in Python 3.11, so this isn't an issue for 3.9 or 3.10.
msg412545 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2022-02-04 22:17
What does the tilde (~) do?
msg412551 - (view) Author: Alex Waygood (AlexWaygood) * (Python triager) Date: 2022-02-05 00:10
:func:`` means that the visible text on the webpage will be "property", but the link will be to rather than
msg412552 - (view) Author: Alex Waygood (AlexWaygood) * (Python triager) Date: 2022-02-05 00:12
The ~ always only uses the final part of the name for the display text, e.g.  `` would have "Iterator" as the visible text on the website.
msg412644 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-06 15:56
(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
msg412789 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-02-07 19:57
Using a substitution is necessary when we need code markup and a link.

For this bug, the simple ~ markup will be enough.
msg412875 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-02-08 22:51
The same problem exists for any attribute that has the same name as a builtin, see for example
msg412903 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-09 13:38
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?
msg412909 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-02-09 14:34
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 is only for 3.11, the backport PRs can be a little different), or tracked in a separate ticket if that seems more convenient.
msg413007 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-10 14:45
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?
msg413008 - (view) Author: Jelle Zijlstra (JelleZijlstra) * (Python committer) Date: 2022-02-10 15:17
> 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 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).
msg413009 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-10 15:20
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?
msg413010 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2022-02-10 15:34
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)
msg413011 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-02-10 15:48
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`.
msg413115 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2022-02-12 04:21
New changeset 9d9cfd61ec3cbe84dbc25c74f664877f3d02b8ef by Meer Suri in branch 'main':
bpo-46586: Fix documentation links (GH-31216)
msg413181 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-13 14:05
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 - 

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, whereas the second instance points to Seems like a true positive to me, what do you think?
msg413183 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-13 14:28
Also this one?-

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
msg413185 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-13 14:47
Looks like another one -

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
msg413228 - (view) Author: Meer Suri (meersuri) * Date: 2022-02-14 15:49 -

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

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 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:`` or even :func:`open`
Date User Action Args
2022-04-11 14:59:55adminsetgithub: 90744
2022-02-19 06:42:30meersurisetpull_requests: + pull_request29564
2022-02-14 15:49:15meersurisetmessages: + msg413228
2022-02-13 14:47:37meersurisetmessages: + msg413185
2022-02-13 14:28:14meersurisetmessages: + msg413183
2022-02-13 14:05:48meersurisetmessages: + msg413181
2022-02-12 04:21:41ethan.furmansetmessages: + msg413115
2022-02-10 15:48:14eric.araujosetmessages: + msg413011
2022-02-10 15:34:09zach.waresetnosy: + mdk, zach.ware
messages: + msg413010
2022-02-10 15:20:56meersurisetmessages: + msg413009
2022-02-10 15:17:12JelleZijlstrasetnosy: + JelleZijlstra
messages: + msg413008
2022-02-10 14:45:41meersurisetmessages: + msg413007
2022-02-09 14:34:31eric.araujosetmessages: + msg412909
2022-02-09 13:38:54meersurisetmessages: + msg412903
2022-02-08 22:51:53eric.araujosetmessages: + msg412875
2022-02-08 15:30:53python-devsetkeywords: + patch
nosy: + python-dev

pull_requests: + pull_request29386
stage: needs patch -> patch review
2022-02-07 19:57:49eric.araujosetmessages: + msg412789
2022-02-06 15:56:30meersurisetnosy: + meersuri
messages: + msg412644
2022-02-06 14:02:58ethan.furmansetmessages: - msg412634
2022-02-06 14:02:49ethan.furmansetmessages: + msg412634
2022-02-05 00:12:22AlexWaygoodsetmessages: + msg412552
2022-02-05 00:10:27AlexWaygoodsetmessages: + msg412551
2022-02-04 22:17:25ethan.furmansetmessages: + msg412545
2022-02-04 21:55:21AlexWaygoodsetnosy: + AlexWaygood

messages: + msg412543
versions: - Python 3.9, Python 3.10
2022-02-04 18:34:39eric.araujosetversions: + Python 3.9, Python 3.10
nosy: + eric.araujo

messages: + msg412523

keywords: + easy
2022-01-30 15:46:39AlexWaygoodsetassignee: docs@python -> ethan.furman

type: behavior
nosy: + ethan.furman
stage: needs patch
2022-01-30 15:12:05Dutchocreate