classification
Title: Inadequate documentation of the built-in function open
Type: Stage:
Components: Documentation Versions: Python 3.0, Python 3.1, Python 2.7, Python 2.6, Python 2.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: LambertDW, MLModel, georg.brandl
Priority: normal Keywords:

Created on 2009-01-25 23:41 by MLModel, last changed 2009-04-27 06:14 by georg.brandl. This issue is now closed.

Messages (6)
msg80549 - (view) Author: Mitchell Model (MLModel) Date: 2009-01-25 23:41
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.
msg80550 - (view) Author: Mitchell Model (MLModel) Date: 2009-01-25 23:47
In point (2) I should have written "a plain 'b' or 't'" and "value" not 
"valuable". Neither 't' nor 'b' can appear without a r/w/a.
msg80555 - (view) Author: David W. Lambert (LambertDW) Date: 2009-01-26 01:15
I disagree.  You propose to examine the trees but ignore the forest.  
The perspective programmer needs to understand what is a file.
msg80563 - (view) Author: Mitchell Model (MLModel) Date: 2009-01-26 04:35
>David W. Lambert <lambertdw@corning.com> added the comment:
>
>I disagree.  You propose to examine the trees but ignore the forest.
>The perspective programmer needs to understand what is a file.
>

Could you be more specific about what parts of my comments you 
disagree with? The current documentation leaves open the possibility 
of someone thinking that random access doesn't apply to text files, 
getting errors when entering the apparently legal, but in reality 
not, 'b', and that '+', 't+', and 'b+' are legal whereas they require 
a r, w, or a.

I know this bit of documentation has been stable for years, but in 
doing some writing I got tripped up by trying to write an example 
using just '+', despite being very knowledgeable about Python. At 
that pointI experimented with the various combinations and compared 
the reality against the documentation. What I ended up doing is 
splitting the table in two and listing the + combinations explicitly:
Text or Binary:
t	text
b	binary

Read, Write, or Append:
r	beginning, read
w	beginning, write
a	end, write
r+	beginning, read/write
w+	beginning, read/write
a+	end, read/write

-- 

         --- Mitchell
msg80585 - (view) Author: David W. Lambert (LambertDW) Date: 2009-01-26 18:53
(prospective, not perspective programmer)

Spelling out the possibilities as suggested in Message80563 makes better
sense to me than writing in words the logic handling the mode argument
of the io.open function.  (Perhaps there is a clearer implementation
using a dictionary with frozenset keys, but the io module for py3k is
being recast in c, per my understanding.)
msg86646 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-04-27 06:14
I've now split the mode table in two tables, one describing base modes,
and one the possible modifiers.  See r72000.
History
Date User Action Args
2009-04-27 06:14:20georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg86646
2009-04-27 06:00:30georg.brandlsetfiles: - unnamed
2009-01-26 18:53:49LambertDWsetmessages: + msg80585
2009-01-26 04:35:05MLModelsetfiles: + unnamed
messages: + msg80563
2009-01-26 01:15:24LambertDWsetnosy: + LambertDW
messages: + msg80555
2009-01-25 23:47:40MLModelsetmessages: + msg80550
2009-01-25 23:41:36MLModelcreate