Skip to content

gh-129011: Update docs for Raw I/O read, readinto, and write#135328

Open
cmaloney wants to merge 4 commits into
python:mainfrom
cmaloney:rawio_retry_nonblock
Open

gh-129011: Update docs for Raw I/O read, readinto, and write#135328
cmaloney wants to merge 4 commits into
python:mainfrom
cmaloney:rawio_retry_nonblock

Conversation

@cmaloney
Copy link
Copy Markdown
Contributor

@cmaloney cmaloney commented Jun 10, 2025 •
edited
Loading

Update RawIOBase and FileIO documentation to match implementation behavior around .read, .readinto, .readall and .write.

see also: gh-80050 / GH-130653 (similar work on Buffered I/O read docs)

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

@cmaloney
pythongh-129011: Update docs for Raw I/O read, readinto, and write
83261c2 
Update `RawIOBase` and `FileIO` documentation to match implementation
behavior around `.read`, `.readinto`, `.readall` and `.write`.

In particular:

 - They may make more than one system call (PEP-475)
 - Add warnings if `.write()` requires a wrapping retry loop (see: pythongh-126606)
    - "Raw I/O" `.write`` may not write all bytes
    - `buffering=0` example results in a "Raw I/O"
@bedevere-app bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Jun 10, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Jun 10, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Jun 10, 2025
Open
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 26, 2026

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 26, 2026
@cmaloney cmaloney removed the stale Stale PR or inactive for long period of time. label Apr 26, 2026
serhiy-storchaka
serhiy-storchaka approved these changes Jun 2, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. 👍

@vstinner, could you please look at this as the author of retry-on-interrupt logic?

@serhiy-storchaka serhiy-storchaka requested a review from vstinner June 2, 2026 17:08
@serhiy-storchaka serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 2, 2026
@read-the-docs-community
Copy link
Copy Markdown

read-the-docs-community Bot commented Jun 2, 2026 •
edited
Loading

Documentation build overview

📚 cpython-previews | 🛠️ Build #32996868 | 📁 Comparing c0b547b against main (f7e0fb6)

  🔍 Preview build  

73 files changed · + 1 added · ± 72 modified

+ Added

± Modified

@vstinner
Copy link
Copy Markdown
Member

vstinner commented Jun 4, 2026

Tests / Docs / Docs (pull_request): Failing after 16s

A git command failed with fatal: shallow file has changed since we read it.

vstinner
vstinner approved these changes Jun 4, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I just have some minor formatting suggestions.

Sometimes, I wish that the io module has readall() and writeall() methods, similar to socket sendall() method.

Comment thread Doc/library/io.rst Outdated
Comment thread Doc/library/io.rst Outdated
Comment thread Doc/library/io.rst Outdated
Comment thread Doc/library/io.rst Outdated
@cmaloney @vstinner
Apply suggestions from code review
8731795 
Co-authored-by: Victor Stinner <vstinner@python.org>
@cmaloney
Copy link
Copy Markdown
Contributor Author

cmaloney commented Jun 4, 2026

FileIO has a .readall() which is used several times in CPython so to duck type replace it with BufferedIO in my I/O plans need to add one calling through to .read(-1). Happy to do that as a small earlier feature add

@cmaloney
Minor grammar tweaks
c0b547b 
 - Move to commas around nonessential phrase
 - Expand contraction
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vstinner vstinner vstinner approved these changes

@serhiy-storchaka serhiy-storchaka serhiy-storchaka approved these changes

Assignees

No one assigned

Labels

awaiting merge docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes skip news

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@cmaloney @vstinner @serhiy-storchaka