homepage

The documentation says io.TextIOWrapper wraps io.BufferedIOBase raw 
stream. In the code, io.TextIOWrapper.read(), 
io.TextIOWrapper._read_chunk() calls buffer.read1() which seems 
expecting buffer to be an instance of io.BufferedReader. I'm not sure 
which is correct right now.

Indeed, read1() is not documented as a standard method of either IOBase,
RawIOBase or BufferedIOBase. I suggest that it becomes a standard method
of IOBase, with a default implementation simply calling read(n).
It also means unbuffered stdio as it was recently committed doesn't work
for stdin:
$ ./python -u
Python 3.1a0 (py3k:68756, Jan 19 2009, 01:17:26) 
[GCC 4.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.stdin.read(1)
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "/home/antoine/py3k/__svn__/Lib/io.py", line 1739, in read
 eof = not self._read_chunk()
 File "/home/antoine/py3k/__svn__/Lib/io.py", line 1565, in _read_chunk
 input_chunk = self.buffer.read1(self._CHUNK_SIZE)
AttributeError: 'FileIO' object has no attribute 'read1'
>>> 
I had been misguided by the fact that the interpreter prompt did work,
but it doesn't seem to use sys.stdin...

IOBase doesn't even define read(), though! I think we should make it
part of BufferIOBase.

Usage of read1():
 * _BytesIO.read1(n) (_bytesio.c): calls bytesio_read(n)
 * _BytesIO.read1(n) (io.py): return self.read(n)
 * BufferedReader._read_unlocked(n=None): 
 - if n is None or n==-1, call self.raw.read() in a "while 
True: ..." until EOF
 - else, call self.raw.read() until we get enough bytes
 * BufferedReader.read1(n): calls self._read_unlocked(...) but make 
sure that we don't call self.raw.read() more than once
 * BufferedRWPair.read1(n): return self.reader.read1(n)
 * BufferedRandom.read1(n): self.flush(); return BufferedReader.read1
(self, n)
 * TextIOWrapper._read_chunk() calls self.buffer.read1
(self._CHUNK_SIZE)
IOBase, RawIOBase, FileIO, BufferedIOBase, TextIOBase, TextIOWrapper, 
StringIO have no read1() method.

Short example to reproduce the problem:
---
import io, os
fd = os.open("/etc/issue", os.O_RDONLY)
raw = open(fd, "rb", buffering=0)
text = io.TextIOWrapper(raw, line_buffering=False)
print(text.read(1))
---
Traceback (most recent call last):
 File "x.py", line 6, in <module>
 print(text.read(1))
 File "/home/SHARE/SVN/py3k/Lib/io.py", line 1739, in read
 eof = not self._read_chunk()
 File "/home/SHARE/SVN/py3k/Lib/io.py", line 1565, in _read_chunk
 input_chunk = self.buffer.read1(self._CHUNK_SIZE)
AttributeError: 'FileIO' object has no attribute 'read1'

On Mon, Jan 19, 2009 at 11:59 AM, STINNER Victor <report@bugs.python.org> wrote:
>
> STINNER Victor <victor.stinner@haypocalc.com> added the comment:
>
> Short example to reproduce the problem:
> ---
> import io, os
> fd = os.open("/etc/issue", os.O_RDONLY)
> raw = open(fd, "rb", buffering=0)
> text = io.TextIOWrapper(raw, line_buffering=False)
> print(text.read(1))
You can only use TextIOWrapper over a buffered stream, so this example
is invalid anyway.

I don't understand the motivation of having two different methods 
for "raw" streams: read1() and read(). I would prefer to have only a 
method read() (because "read" is the most common name, whereas read1() 
is only used on Python3), but read() will have to follow the read1() 
rule: at most one syscall. If someone requires a read() method with 
the "one syscall" rule, he can use a raw stream. If you don't care, 
use high level classes (TextIOWrapper, BufferedReader, etc.).
_fileio._FileIO.read() and _socket.socket.recv_into() already respect 
the syscall rule.
Since BytesIO and StringIO don't use kernel object, the syscall rule 
is meaningles.
Note: socket.SocketIO() implements RawIOBase but it has no read() nor 
write() methods ;-) That's maybe why IOBase has no read()/write() 
method.

In the io-c branch, read1() is now a member of BufferedIOBase.

This has been fixed in io-c branch merge. (r70152)

> This has been fixed in io-c branch merge. r70152
Amazing, io-c is faster but also fixes many bugs!