gh-90533: Implement BytesIO.peek() by marcelm · Pull Request #150917 · python/cpython · GitHub

Replaces #30808

Issue: io.BytesIO does not have peek() #90533

This allows peek() to use the same optimization that read_bytes() has of returning a reference to the buffer when possible (without copying).

Semantic change: The default argument for peek is now size=1.

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Co-authored-by: Victor Stinner <vstinner@python.org>

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

CI all green! :)

The size=0 case is not well documented. It's unclear to me when I read the doc if peek() or peek(0) return an empty string or something else.

I’ve updated the documentation. I also changed the wording to make it clearer that a copy is returned, which I think is good to point out because a copy could potentially be costly.

At least, the Python implementation limits the returned string to io.DEFAULT_BUFFER_SIZE bytes.

I have removed the limit even in the Python implementation.

I think it would still be good to default limit. That way if there's a 1GB BytesIO and you .peek() you don't copy all that data... more just document more precisely.

I misremembered what was said earlier. I will fix it next week.

Should maybe the the signature be changed to peek(size=DEFAULT_BUFFER_SIZE)?

I still prefer 0 as a default, differentiating between "unspecified" and "exactly this size".

Hum, I see multiple discussions about BytesIO.peek(0) limit. Should it return the whole buffer? Or limit to io.DEFAULT_BUFFER_SIZE (128 kiB currently)?

io.BufferedReader.peek(0) is limited to io.BufferedReader.buffer_size which is io.DEFAULT_BUFFER_SIZE by default.

If the BytesIO size if 1 GiB, returning 1 GiB in peek(0) may not be the expected behavior. Calling peek(0) after read(1) has to copy 1 GiB (minus 1 byte) which can be slow.

IMO limiting BytesIO.peek(0) to io.DEFAULT_BUFFER_SIZE would avoid bad surprises. If the caller wants more, they can pass a size of peek(size).

I have updated the behavior such that at most DEFAULT_BUFFER_SIZE bytes are returned if size is less than one or omitted.

Maybe for size=-1, the behavior could be that the full remainder of the buffer is returned, but I don’t mind either way.

Co-authored-by: Victor Stinner <vstinner@python.org>

LGTM! Thanks for the updates.

@cmaloney: Would you mind to double check the change?

Maybe for size=-1, the behavior could be that the full remainder of the buffer is returned, but I don’t mind either way.

If you know that the file is smaller than available memory, you can pass sys.maxsize :-)

Maybe for size=-1, the behavior could be that the full remainder of the buffer is returned, but I don’t mind either way.

Ideally this would use PEP-661 so we could distinguish the cases "not provided" and "all" easily but the .peek() API predates that. I do think it may make sense to modify behavior across all them with new sentinels but that raises some breaking change possibility. I really want a reliable .peek(10) returning 10 bytes on regular blocking files... would make a lot of code simpler.

Co-authored-by: Cody Maloney <cmaloney@users.noreply.github.com>

@marcelm: Can you please update your PR and solve the merge conflict on Doc/whatsnew/3.16.rst?

Updated (The lzma whatsnew entry moved to be alphabetical / after logging)

Congrats @marcelm! Finally, I merged your PR! Sorry for all the back and forth, but it was really hard to decide on the exact API, especially for peek() and peek(0). I like the final API :-)

Oh, nice, happy to see this go in just before going on vacation! 😄

I think what was a bit difficult was that it was hard to tell who gets to decide, that is, whose requests I should implement if there was a disagreement (between core devs). This was also the reason for the long delay between Nov. 2023 and then April this year.

I’m glad it worked out now, even if it took ~180 comments and 54 commits for a ~200 line change. Thanks everyone for your help, I learned a lot along the way!

~180 comments and 54 commits for a ~200 line change

That's a very long history. Thanks for your tenacity :-D

Thanks for all the work @marcelm!

Noted on the decision and debate parts. Really appreciate working through it and think we ended up with a really nice new feature :)

marcelm and others added 30 commits April 10, 2026 20:37

Implement BytesIO.peek()

b833b83

📜🤖 Added by blurb_it.

50a2cfb

Document BytesIO.peek()

eaa7672

Implement with the help of read_bytes()

00457ae

This allows peek() to use the same optimization that read_bytes() has of returning a reference to the buffer when possible (without copying).

Add to What’s New

882579d

versionadded: 3.12 -> 3.13

c1eed72

Remove unused variable

afc200c

Test tell() after peek()

79ab9a4

Update docs, factor out peek_bytes, semantics

b493914

Semantic change: The default argument for peek is now size=1.

Update Misc/NEWS.d/next/Library/2022-04-10-20-10-59.bpo-46375 .8j1ogZ.rst

2a1c85c

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update Modules/_io/bytesio.c

d398717

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update Modules/_io/bytesio.c

26d1e81

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Use SemBr

9a19ff9

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update Doc/whatsnew/3.13.rst

9300ade

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Apply suggestions from code review

d214089

Co-authored-by: Victor Stinner <vstinner@python.org>

Use a context manager around memio in test_peek

d6691b8

Add more tests for tell() after peek()

3e51adb

Document why size < 0 can happen

3661b65

Update Modules/_io/bytesio.c

cd40d77

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Do not update pos if peek_bytes failed

04372bd

Size can be negative after truncate or seek

6b9ae8c

Test with size<0 and size>len(buf)

f7406f6

Test peek() after write()

d9528e2

Document BufferedReader.peek and BytesIO.peek similarly

bc8134b

Comment

b6ffca8

Make it more explicit that size is ignored

5fe5645

Return an empty bytes object for size=0

4126a64

Simplify

1ea40c2

Test peek(3) and peek(5)

77e04d6

Run clinic.py

4d2f2dd

vstinner reviewed Jun 9, 2026

View reviewed changes

Clarify what peek(0) does

e2d3929

vstinner reviewed Jun 11, 2026

View reviewed changes

marcelm added 3 commits June 11, 2026 16:42

Do not cap at DEFAULT_BUFFER_SIZE even in Python implementation

5f07faa

Test buffer size greater than DEFAULT_BUFFER_SIZE

bb5f648

Test buffer content

8a96f88

Return at most DEFAULT_BUFFER_SIZE bytes if size is 0/-1/unspecified

5105c55

vstinner reviewed Jun 18, 2026

View reviewed changes

Comment thread Doc/library/io.rst Outdated

Comment thread Doc/library/io.rst Outdated

Comment thread Lib/test/test_io/test_memoryio.py Outdated

Comment thread Doc/whatsnew/3.16.rst Outdated

Comment thread Misc/NEWS.d/next/Library/2022-04-10-20-10-59.bpo-46375.8j1ogZ.rst Outdated

Apply suggestions from code review

11e65fe

Co-authored-by: Victor Stinner <vstinner@python.org>

vstinner approved these changes Jun 18, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Jun 18, 2026

cmaloney approved these changes Jun 18, 2026

View reviewed changes

Comment thread Modules/_io/bytesio.c Outdated

Comment thread Lib/test/test_io/test_memoryio.py

Apply suggestions from code review

514d102

Co-authored-by: Cody Maloney <cmaloney@users.noreply.github.com>

Merge branch 'main' into fix-issue-46375

bead21a

vstinner merged commit 72cad14 into python:main Jun 26, 2026
54 checks passed

bedevere-app Bot removed the awaiting merge label Jun 26, 2026

marcelm deleted the fix-issue-46375 branch June 26, 2026 12:00

This was referenced Aug 8, 2026

_pyio.BytesIO.peek() returns bytearray instead of bytes #155389

Closed

gh-155389: Return bytes from _pyio.BytesIO.peek() #155390

Merged

+                 .. method:: peek(size=0, /)
+                    Return bytes from the current position onwards without advancing the position.
+                    At least one byte of data is returned if not at EOF.


		Return a copy of the buffer from the current position onwards without advancing the position.

		If size is zero or omitted, the returned :class:`bytes` object extends to EOF.

gh-90533: Implement BytesIO.peek() by marcelm · Pull Request #150917 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-90533: Implement BytesIO.peek() - #150917

gh-90533: Implement BytesIO.peek()#150917vstinner merged 54 commits intopython:mainpython/cpython:mainfrom marcelm:fix-issue-46375marcelm/cpython:fix-issue-46375Copy head branch name to clipboard

Conversation

marcelm commented Jun 4, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cmaloney commented Jun 9, 2026

Uh oh!

vstinner Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

marcelm Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

vstinner Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

marcelm Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmaloney Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

marcelm Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

cmaloney Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vstinner commented Jun 12, 2026

Uh oh!

marcelm commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

cmaloney commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

vstinner commented Jun 24, 2026

Uh oh!

cmaloney commented Jun 24, 2026

Uh oh!

Uh oh!

vstinner commented Jun 26, 2026

Uh oh!

marcelm commented Jun 26, 2026

Uh oh!

vstinner commented Jun 26, 2026

Uh oh!

cmaloney commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gh-90533: Implement BytesIO.peek()#150917
vstinner merged 54 commits into
python:mainfrom
marcelm:fix-issue-46375

marcelm commented Jun 4, 2026 •
edited by bedevere-app Bot
Loading

marcelm Jun 11, 2026 •
edited
Loading