[Python-Dev] Fuzziness in io module specs

[Pascal Chambon]

Hello everyone

I'm currently working on a reimplementation of io.FileIO, which would 
allow cross-platform file range locking and all kinds of other safety 
features ; however I'm slightly stuck due to some specification 
fuzziness in the IO docs.
CF     http://bugs.python.org/issue6939

The main points that annoy me at the moment :
- it is unclear what truncate() methods do with the file pointer, and 
even if the current implementation simply moves it to the truncation 
point, it's very contrary to the standard way of doing under unix, where 
the file pointer is normally left unchanged. Shouldn't we specify that 
the file pointer remains unmoved, and fix the _fileio module accordingly ?
- exceptions are not always specified, and even if most of them are 
IOErrors, weirdly, in some cases, an OSError is raised instead (ie, if 
we try to wrap a wrong file descriptor when instanciating a new FileIO). 
This might lead to bad program crashes if some people don't "refuse the 
temptation to guess" and only get prepared to catch IOErrors
- the doc sometimes says that when we receive an empty string from a 
read() operation, without exceptions, it means the file is empty. 
However, with the current implementation, if we call file.read(0), we 
simply receive "", even though it doesn't mean that we're at EOF. 
Shouldn't we avoid this (rare, I admit) ambiguity on the return value, 
by preventing read(0) ? Or at least, note in the doc that (we receive an 
empty string) <-> (the file is at EOF OR we called read with 0 as 
parameter) ?

Are there some arguments that I don't know, which lead to this or that 
particular implementation choice ?
I'd strongly advocate very detailled specifications, letting no room for 
cross-platform subtilities (that's also a strong goal of my 
reimplemntation), since that new IO system (which saved me a lot of 
coding time, by the way) should become the base of many programs.

So wouldn't it be a godo idea to write some kind of mini-pep, just to 
fix the corner cases of the current IO documentation ? I might handle 
it, if no more-knowledgeable people feels like it.

Regards,
Pascal