Wrong documentation for GzipFile.peek

[abacabadabacaba]

BPO	28445
Nosy	@vadmium, @zhangyangyu, @180909
PRs	gh-72631: Fix wrong documentation for GzipFile.peek #29820

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-10-14.16:53:42.369>
labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'docs']
title = 'Wrong documentation for GzipFile.peek'
updated_at = <Date 2021-11-28.10:14:51.573>
user = 'https://bugs.python.org/abacabadabacaba'

bugs.python.org fields:

activity = <Date 2021-11-28.10:14:51.573>
actor = 'wangjiahua'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-10-14.16:53:42.369>
creator = 'abacabadabacaba'
dependencies = []
files = []
hgrepos = []
issue_num = 28445
keywords = ['patch', 'easy', 'newcomer friendly']
message_count = 3.0
messages = ['278656', '278660', '278671']
nosy_count = 5.0
nosy_names = ['abacabadabacaba', 'docs@python', 'martin.panter', 'xiang.zhang', 'wangjiahua']
pr_nums = ['29820']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue28445'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• [3.13] gh-72631: Fix wrong documentation for GzipFile.peek (GH-29820) #132353

[abacabadabacaba]

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().

[zhangyangyu]

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.

[vadmium]

The peek() method was originally added by bpo-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 bpo-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.