[issue5061] Inadequate documentation of the built-in function open

[Mitchell Model]

New submission from Mitchell Model <mlm at acm.org>:

Documentation of the mode parameter of the built-in function open is 
insufficient with respect to what values are acceptable.

(1) Right after the mode table, it states "For binary random access, the 
mode 'w+b' opens and truncates the file to 0 bytes, while 'r+b' opens 
the file without truncation." This is true of text random access too -- 
w+ or r+. Furthermore, the possibility of a+, while meaningful, is not 
mentioned.

(2) The documentation does not, but should, say that while w/r/a with or 
without the plus can appear without a 'b' or 't', a plain 'b' as the 
mode valuable raises an error that r/w/a wasn't specified.

(3) The documentation does not, but should, say that + cannot stand on 
its own -- the mode must also include an r, w, or a. The table listing 
the meanings of each value just says + means "open a disk file for 
updating (reading and writing)". Suggested rewording is to put the 
phrase "in conjunction with 'r', 'w', or 'a', open a disk file...". 
Alternatively, add a note to that table entry and explain below that the 
plus must accompany a r/w/a.

----------
assignee: georg.brandl
components: Documentation
messages: 80549
nosy: MLModel, georg.brandl
severity: normal
status: open
title: Inadequate documentation of the built-in function open
versions: Python 2.5, Python 2.6, Python 2.7, Python 3.0, Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue5061>
_______________________________________