homepage

Two pieces of the documentation for io.IOBase seem to contradict each other:
At http://docs.python.org/library/io.html#io.IOBase:
"Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise IOError in this case."
At http://docs.python.org/library/io.html#io.IOBase.close:
"Once the file is closed, any operation on the file (e.g. reading or writing) will raise a ValueError."
Perhaps the confusion arises in part because it is not clear when a requirement for all IOBase implementations is documented and when the docs merely describe the default behavior of IOBase that implementations are free to override.
Those passages are inconsistent on two points:
1) IOError and ValueError are not subclasses one of another. So what should we expect an IOBase implementation to raise?
2) Undefined behavior means literally anything can happen. Technically, that means calling read() or readable() on a closed file (or other kind of stream) could wreak havoc in a totally unrelated part of the system or segfault the Python interpreter. That is definitely a thing to carefully avoid in any production systems.
On the other hand, raising an exception, even if we don't know in advance whether it will be ValueError or IOError, is pretty much defined behavior. An exception is easy to deal with and to contain inside a module.
So please clarify how dangerous it actually is to access an IOBase stream after it has been closed.

> 1) IOError and ValueError are not subclasses one of another. So what
> should we expect an IOBase implementation to raise?
Ideally, ValueError should be raised, but I suspect some methods raise IOError instead.
> Undefined behavior means literally anything can happen.
In practice, it will either raise an error, or be ignored. For example, calling close() a second time would be ignored. Calling readable() may return the original value (before the file was closed), etc.
Any non-trivial behaviour should be reported as a bug, though. Especially, reading or writing methods (read(), write(), readline() etc.) should *never* succeed on a closed file.

Actually, I would suggest we standardize the docs on raising ValueError as the official behaviour, and fix non-compliant behaviours as bugs.

Related: issue15841 and issue15842.

I agree that standardize behavior here would be useful. But it sounds like a candidate for 3.4. Unifying/changing it for existing releases appears rather hairy to me?

Agree with you, Hynek. It should be fixed in 3.4 only (and change should be well documented).

Changed documentation to state that ValueError should be raised if any operation (excluding close()) is called on a closed stream.
This appears to be what is done in iobase.c; and some investigation of inheriting types (rawiobase, fileio, bufferedio, etc.) indicates that there is nowhere where an IOError is being raised instead.
Sphinx documentation appears to already be update to date.
Is there any known place where operations on a closed stream raise IOError? I am currently assuming no.

New changeset 0c7cf0e598e7 by Andrew Kuchling in branch '2.7':
#15840: make docs consistent by saying operations on closed files raise ValueError.
http://hg.python.org/cpython/rev/0c7cf0e598e7 

New changeset 7a27039e4a42 by Andrew Kuchling in branch '3.4':
#15840: make docs consistent by saying operations on closed files raise ValueError.
http://hg.python.org/cpython/rev/7a27039e4a42 

Committed to 2.7, 3.4, and default. Thanks for your patch!