gh-80050: Update BufferedReader.read docs around non-blocking #130653

cmaloney · 2025-02-27T20:17:25Z

Synchronize io.BufferedReader and io.BufferedIOBase documentation with the current implementation. Focused on behavior around non-blocking streams.

Issue: io.BufferReader.read() returns None #80050

📚 Documentation preview 📚: https://cpython-previews--130653.org.readthedocs.build/

Synchronize `io.BufferedReader` and `io.BufferedIOBase` documentation with the current implementation. Focused on behavior around non-blocking streams.

Doc/library/io.rst

BufferedReader at least just forwards `None` from the underlying stream. 1. `BufferedReader.read(size=10)` `raw.read(size=10)` returns None 2. `BufferedReader.read()` without size, raw implements `readall()` which returns None 3. `BufferedReader.read()` without size, raw doesn't have readall so uses a loop that calls `raw.read()` which returns None.

Doc/library/io.rst

cmaloney · 2025-05-19T17:49:16Z

cc: @gpshead

Doc/library/io.rst

cmaloney · 2025-05-19T22:05:10Z

Doc/library/io.rst

@@ -826,8 +823,8 @@ than raw I/O does.

      Write the :term:`bytes-like object`, *b*, and return the
      number of bytes written.  When in non-blocking mode, a
-      :exc:`BlockingIOError` is raised if the buffer needs to be written out but
-      the raw stream blocks.
+      :exc:`BlockingIOError` with :attr:`BlockingIOError.characters_written` set


characters_written is fairly well tested in this case

cpython/Lib/test/test_io.py

Lines 1918 to 1943 in a7f317d

def test_write_non_blocking(self):

raw = self.MockNonBlockWriterIO()

bufio = self.tp(raw, 8)

self.assertEqual(bufio.write(b"abcd"), 4)

self.assertEqual(bufio.write(b"efghi"), 5)

# 1 byte will be written, the rest will be buffered

raw.block_on(b"k")

self.assertEqual(bufio.write(b"jklmn"), 5)

# 8 bytes will be written, 8 will be buffered and the rest will be lost

raw.block_on(b"0")

try:

bufio.write(b"opqrwxyz0123456789")

except self.BlockingIOError as e:

written = e.characters_written

else:

self.fail("BlockingIOError should have been raised")

self.assertEqual(written, 16)

self.assertEqual(raw.pop_written(),

b"abcdefghijklmnopqrwxyz")

self.assertEqual(bufio.write(b"ABCDEFGHI"), 9)

s = raw.pop_written()

# Previously buffered bytes were flushed

self.assertTrue(s.startswith(b"01234567A"), s)

miss-islington-app · 2025-05-21T16:06:45Z

Thanks @cmaloney for the PR, and @gpshead for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…ythonGH-130653) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

miss-islington-app · 2025-05-21T16:06:52Z

Sorry, @cmaloney and @gpshead, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker e1f891414b2329414a6160ed246f5f869a218bfd 3.13

bedevere-app · 2025-05-21T16:06:57Z

GH-134444 is a backport of this pull request to the 3.14 branch.

…H-130653) (#134444) gh-80050: Update BufferedReader.read docs around non-blocking (GH-130653) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

…cking (pythonGH-130653) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

bedevere-app · 2025-05-21T17:01:08Z

GH-134445 is a backport of this pull request to the 3.13 branch.

…H-130653) (#134445) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

…ythonGH-130653)

pythongh-80050: Update BufferedReader.read around non-blocking

4ed4237

Synchronize `io.BufferedReader` and `io.BufferedIOBase` documentation with the current implementation. Focused on behavior around non-blocking streams.

bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Feb 27, 2025

github-project-automation bot added this to Docs PRs Feb 27, 2025

github-project-automation bot moved this to Todo in Docs PRs Feb 27, 2025

bedevere-app bot mentioned this pull request Feb 27, 2025

io.BufferReader.read() returns None #80050

Open

cmaloney changed the title ~~gh-80050: Update BufferedReader.read around non-blocking~~ gh-80050: Update BufferedReader.read docs around non-blocking Feb 27, 2025

cmaloney added 5 commits February 27, 2025 12:30

Tweaks around raw.readall

b87870b

tweak readall, hopefully passes

2119f78

tweaks

ec7f023

clss -> class

11b754d

grammatical tweaking

b6d319b

cmaloney mentioned this pull request Mar 1, 2025

gh-129011: Update comments in FileIO to match current code #129012

Merged

cmaloney commented Mar 7, 2025

View reviewed changes

Doc/library/io.rst Outdated Show resolved Hide resolved

cmaloney added 5 commits March 11, 2025 16:37

tweak

fbbc382

Tweak read and read1 None and BlockingIOError comments

dea91ab

in read1 refer to EINTR retrying

7c4ef7e

fix doc lint around raw.readinto

c637402

cmaloney commented May 9, 2025

View reviewed changes

Doc/library/io.rst Outdated Show resolved Hide resolved

personal review fixes

22bc9aa

gpshead reviewed May 19, 2025

View reviewed changes

Doc/library/io.rst Show resolved Hide resolved

gpshead added the sprint label May 19, 2025

github-project-automation bot added this to Sprint 2024 May 19, 2025

github-project-automation bot moved this to Todo in Sprint 2024 May 19, 2025

cmaloney added 2 commits May 19, 2025 17:57

Update BufferedIOBase class doc for non-blocking

1c4a09c

Include characters_written in BlockingReader

8ea45f3

cmaloney commented May 19, 2025

View reviewed changes

Fewer rather than Less

45bb912

gpshead approved these changes May 21, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels May 21, 2025

github-project-automation bot moved this from Todo to In Progress in Sprint 2024 May 21, 2025

gpshead added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 21, 2025

gpshead enabled auto-merge (squash) May 21, 2025 16:02

gpshead merged commit e1f8914 into python:main May 21, 2025
31 of 32 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs May 21, 2025

github-project-automation bot moved this from In Progress to Done in Sprint 2024 May 21, 2025

bedevere-app bot removed the awaiting merge label May 21, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 21, 2025

pythongh-80050: Update BufferedReader.read docs around non-blocking (p…

54a7841

…ythonGH-130653) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

miss-islington-app bot assigned gpshead May 21, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label May 21, 2025

cmaloney deleted the docs_buffferedreader branch May 21, 2025 16:07

cmaloney mentioned this pull request May 21, 2025

The io module doesn't support non-blocking files #57531

Open

gpshead pushed a commit to gpshead/cpython that referenced this pull request May 21, 2025

[3.13] pythongh-80050: Update BufferedReader.read docs around non-blo…

6f42565

…cking (pythonGH-130653) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label May 21, 2025

gpshead added a commit that referenced this pull request May 21, 2025

[3.13] gh-80050: Update BufferedReader.read docs around non-blocking (G…

5ecc39e

…H-130653) (#134445) (cherry picked from commit e1f8914) Co-authored-by: Cody Maloney <[email protected]>

lkollar pushed a commit to lkollar/cpython that referenced this pull request May 26, 2025

pythongh-80050: Update BufferedReader.read docs around non-blocking (p…

dbd0da3

…ythonGH-130653)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

gh-80050: Update BufferedReader.read docs around non-blocking #130653

gh-80050: Update BufferedReader.read docs around non-blocking #130653

Uh oh!

cmaloney commented Feb 27, 2025 •

edited by github-actions bot

Loading

Uh oh!

Uh oh!

Uh oh!

cmaloney commented May 19, 2025

Uh oh!

Uh oh!

cmaloney May 19, 2025 •

edited

Loading

Uh oh!

Uh oh!

miss-islington-app bot commented May 21, 2025

Uh oh!

miss-islington-app bot commented May 21, 2025

Uh oh!

bedevere-app bot commented May 21, 2025

Uh oh!

bedevere-app bot commented May 21, 2025

Uh oh!

Uh oh!

	def test_write_non_blocking(self):
	raw = self.MockNonBlockWriterIO()
	bufio = self.tp(raw, 8)

	self.assertEqual(bufio.write(b"abcd"), 4)
	self.assertEqual(bufio.write(b"efghi"), 5)
	# 1 byte will be written, the rest will be buffered
	raw.block_on(b"k")
	self.assertEqual(bufio.write(b"jklmn"), 5)

	# 8 bytes will be written, 8 will be buffered and the rest will be lost
	raw.block_on(b"0")
	try:
	bufio.write(b"opqrwxyz0123456789")
	except self.BlockingIOError as e:
	written = e.characters_written
	else:
	self.fail("BlockingIOError should have been raised")
	self.assertEqual(written, 16)
	self.assertEqual(raw.pop_written(),
	b"abcdefghijklmnopqrwxyz")

	self.assertEqual(bufio.write(b"ABCDEFGHI"), 9)
	s = raw.pop_written()
	# Previously buffered bytes were flushed
	self.assertTrue(s.startswith(b"01234567A"), s)

Uh oh!

gh-80050: Update BufferedReader.read docs around non-blocking #130653

gh-80050: Update BufferedReader.read docs around non-blocking #130653

Uh oh!

Conversation

cmaloney commented Feb 27, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cmaloney commented May 19, 2025

Uh oh!

Uh oh!

cmaloney May 19, 2025 • 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!

Uh oh!

miss-islington-app bot commented May 21, 2025

Uh oh!

miss-islington-app bot commented May 21, 2025

Uh oh!

bedevere-app bot commented May 21, 2025

Uh oh!

bedevere-app bot commented May 21, 2025

Uh oh!

Uh oh!

cmaloney commented Feb 27, 2025 •

edited by github-actions bot

Loading

cmaloney May 19, 2025 •

edited

Loading