Tutorial links to file object methods are broken.

[JonathanRoach]

BPO	29175
Nosy	@birkenfeld, @ezio-melotti, @merwok, @bitdancer, @JonathanRoach

^{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 = None
closed_at = None
created_at = <Date 2017-01-06.09:58:43.773>
labels = ['type-bug', '3.7', 'docs']
title = 'Tutorial links to file object methods are broken.'
updated_at = <Date 2017-01-06.20:47:31.474>
user = 'https://github.com/JonathanRoach'

bugs.python.org fields:

activity = <Date 2017-01-06.20:47:31.474>
actor = 'jonroach@icloud.com'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-01-06.09:58:43.773>
creator = 'jonroach@icloud.com'
dependencies = []
files = []
hgrepos = []
issue_num = 29175
keywords = []
message_count = 3.0
messages = ['284806', '284825', '284848']
nosy_count = 6.0
nosy_names = ['georg.brandl', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'docs@python', 'jonroach@icloud.com']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue29175'
versions = ['Python 3.6', 'Python 3.7']

Linked PRs

• gh-73361: add hyperlinks to methods of file objects #138863

[JonathanRoach]

The file documentation (as seen in python.org) went missing in 3.3. In 2.7.13 it can be found in 'The Python Standard Library' as section '5.9 File Objects', between '5.8 Mapping Types' and '5.10 memory view type'. In 3.3 and onwards this section is no longer present, and, as far as I can tell, is not present elsewhere in the documentation.
[related: in 'The Python Tutorial' section '7.2.1 Methods of File Objects' the inline references to the file object methods are shown as references, but without a target]

[bitdancer]

The tutorial links are definitely bugs, and the section may need some tweaking. The 'file object' documentation is replaced by the io module, which completely defines the file object API. There is a link from the 'file object' glossary entry to the IO module indicating this.

Only 3.6 and 3.7 docs get documentation updates at this point, so I've removed the others from versions (we use versions to say where things will get fixed). (Well, 3.5 docs can still get updates at the moment, but that won't last long, final is soon.)

[JonathanRoach]

OK, I understand that the older versions aren't going to be revised - that makes sense.

I think part of the reason I submitted this is the reader's path from the open() documentation to the most relevant part of the io documentation (the interface) is long and narrow: open()->file object(in the Glossary)->io(see note)..and then scroll several pages down.
Note: the link to io from the 'file object' glossary entry is visually tiny, and in last paragraph - effectively making it almost invisible. This also seems to be the only place in the chain of links from open() which gets you to the io documentation.
When trying to find the interface documentation I tried the visually bigger, earlier links and ended up like I was being given the run-around through the various glossary entries.
As a documentation user I'd ideally like a direct link (which is a bit visually bigger than 'io') from open() to the relevant, interface section of the io documentation. However, upstanding you have a better feel for the tone of the documentation, I can see you might take a different route.

[dehnert]

Relatedly, the tail end of https://docs.python.org/3/tutorial/inputoutput.html#methods-of-file-objects says "File objects have some additional methods, such as isatty() and truncate() which are less frequently used; consult the Library Reference for a complete guide to file objects." -- this would be more useful if it were an actual hyperlink. I actually went to the Library Reference TOC and searched for file -- while there's thirty-odd occurrences of the string, io doesn't show up -- it's under "Generic Operating System Services", with description "io — Core tools for working with streams". If the cross reference here is just going to be textual, rather than a link, it should at least be text that's easy to search for.

[StanFromIreland]

This should be fixed by #138465

I think we can close as duplicate, cc @AA-Turner