[Python-Dev] io.BufferedReader.peek() Behaviour in python3.1

[Nick Coghlan]

Frederick Reeve wrote:
> The other point still stands though.  I would like to see peek
> changed.  I am willing to write and submit changes but don't want to
> unless others agree this is a good idea.  So I put forth the
> implementation at the bottom of this email.  If its bad or you don't
> see the point I may try to clarify but if nobody things its good,
> please just tell me I'm waisting your time, and I will go away.  I
> also apologize my last email was so long.
> 
> peek(n): If n is less than 0, None, or not set; return buffer
> contents with out advancing stream position. If the buffer is empty
> read a full chunk and return the buffer.  Otherwise return exactly n
> bytes up to _chunk size_(not contents) with out advancing the stream
> position.  If the buffer contents is less than n, buffer an
> additional chunk from the "raw" stream before hand.  If EOF is
> encountered during any raw read then return as much as we can up to
> n. (maybe I should write that in code form??)

I would phrase this suggestion as users having a reasonable expectation
that the following invariant should hold for a buffered stream:

  f.peek(n) == f.read(n)

Since the latter method will perform as many reads of the underlying
stream as necessary to reach the requested number of bytes (or EOF),
then so should the former.

However, the default value for n for peek() should remain at 1 to remain
consistent with the current documented behaviour.

If this invariant was implemented, I would also suggest adding a "peek1"
method to parallel "read1".

Note that the current behaviour I get from Python 3.1 is for it to
return the *entire* buffer, no matter what number I pass to it:

(current Py3k head)

>>> f = open('setup.py', 'rb')
>>> len(f.peek(10))
4096
>>> len(f.peek(1))
4096
>>> len(f.peek(4095))
4096
>>> len(f.peek(10095))
4096

That's an outright bug - I've promoted an existing issue about this [1]
to a release blocker and sent it to Benjamin to have another look at.

Cheers,
Nick.

[1] http://bugs.python.org/issue5811

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------