New submission from Mitchell Model <mlm@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@bugs.python.org>
<http://bugs.python.org/issue5061>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
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@bugs.python.org>
<http://bugs.python.org/issue5061>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
