[issue28445] Wrong documentation for GzipFile.peek

[jiahua wang]

Change by jiahua wang :


--
keywords: +patch
nosy: +180909
nosy_count: 4.0 -> 5.0
pull_requests: +28052
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/29820

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28445] Wrong documentation for GzipFile.peek

[Irit Katriel]

Change by Irit Katriel :


--
keywords: +easy, newcomer friendly
type:  -> behavior
versions: +Python 3.10, Python 3.11, Python 3.9 -Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28445] Wrong documentation for GzipFile.peek

[Martin Panter]

Martin Panter added the comment:

The peek() method was originally added by Issue 9962, where Antoine was trying 
to imitate the BufferedReader.peek() API. However because “the number of bytes 
returned may be more or less than requested”, I never understood what this 
methods were good for; see also Issue 5811.

I think we could at least remove the claim about “at most one single read”. 
That is just describing an internal detail.

The documentation for bzip and LZMA is slightly more useful IMO because it says 
“at least one byte of data will be returned, unless EOF has been reached”. This 
guarantee is actually missing from the underlying BufferedReader.peek() 
documentation, though I think both io and _pyio implement it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28445] Wrong documentation for GzipFile.peek

[Xiang Zhang]

Xiang Zhang added the comment:

The "compressed stream" is not the underlying file object but _GzipReader. And 
actually the "at most one single reader" is the characteristic of 
io.BufferedReader.peek, you can see it in the doc. Maybe it needs multiple 
reads on the file object in a single peek, but they are all encapsulated in the 
_GzipReader.read. So at the point of GzipFile.peek, it's still a single read.

--
nosy: +xiang.zhang

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28445] Wrong documentation for GzipFile.peek

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28445] Wrong documentation for GzipFile.peek

[Evgeny Kapun]

New submission from Evgeny Kapun:

>From the documentation for GzipFile.peek():

At most one single read on the compressed stream is done to satisfy the 
call.

If "compressed stream" means the underlying file object, then this is not true. 
The method tries to return at least one byte, unless the stream is at EOF. It 
is possible to create arbitrarily long compressed stream that would decompress 
to nothing, and the implementation would read the entire stream in this case. 
Because the length of the stream is not known in advance, several reads may be 
required for this.

Perhaps the documentation for GzipFile.peek() should be made the same as that 
for BZ2File.peek() and LZMAFile.peek().

--
assignee: docs@python
components: Documentation
messages: 278656
nosy: abacabadabacaba, docs@python
priority: normal
severity: normal
status: open
title: Wrong documentation for GzipFile.peek
versions: Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com