[issue29175] Documentation for File objects missing
New submission from Jonathan Roach: 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] ---------- assignee: docs@python components: Documentation messages: 284806 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, jonroach@icloud.com priority: normal severity: normal status: open title: Documentation for File objects missing type: behavior versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29175> _______________________________________
R. David Murray added the comment: 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.) ---------- nosy: +r.david.murray title: Documentation for File objects missing -> Tutorial links to file object methods are broken. versions: -Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29175> _______________________________________
Jonathan Roach added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29175> _______________________________________
participants (2)
-
Jonathan Roach -
R. David Murray