gh-100226: Clarify StreamReader.read behavior #101807
Conversation
This clarifies the `StreamReader.read` behavior in the public documentation; mostly copying from the more precise docstring of the function. While we're at it, also fix some minor grammar in the docstring itself. Addresses python#100226.
jgosmann
requested review from
1st1,
asvetlov,
gvanrossum and
kumaraditya303
as code owners
|
Most changes to Python require a NEWS entry. Please add it using the blurb_it web app or the blurb command-line tool. |
|
All commit authors signed the Contributor License Agreement. |
|
This does not seem to require a NEWS entry to me, but I'm happy to add one if I'm mistaken. |
CAM-Gerlach
added
docs
There was a problem hiding this comment.
Standard reminder: You can directly apply all the suggestions you want in one go with Files changed -> Add to batch -> Commit
Sorry for the delay reviewing this. This is certainly an improvement—I'd suggest a number of further clarifications and revisions to fix things that still initially confused me.
Yes; standard practice is to backport any docs-only fixes that affect bugfix-supported branches, as it fixes a docs defect and ensures that other changes can be backported cleanly too. I've added the appropriate tags to line up the backports when this is merged.
No need, you're quite right—it's a docs-only fix. |
|
No time to review today, but once CAM approves I'll skim and merge. |
Co-authored-by: C.A.M. Gerlach <[email protected]>
(based on review comments)
There was a problem hiding this comment.
Thanks for checking and correcting the subject matter accuracy of my previous suggestions—I was quite confused by the current text, and my limited background in this area led my guesses for how to clarify the intended meaning to be quite off the mark.
I've suggested a couple followup changes, including seems like it one fairly important apparent omission.
|
|
||
| If *n* is not provided, or set to ``-1``, | ||
| read until EOF, then return all read :class:`bytes`. |
There was a problem hiding this comment.
As a beginning reader, before having read @jgosmann 's detailed explaination and @gvanrossum 's summary, I was evidently confused here about what "until EOF" specifically meant in this context. It therefore might warrant some more clarity here, but maybe its just my lack of subject matter expertise compared with the target audience.
Co-authored-by: C.A.M. Gerlach <[email protected]>
It discusses how many bytes are returned in slightly more detail.
|
The macOS build seems to fail for unrelated reasons. |
|
Thanks @jgosmann for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
(cherry picked from commit 77d95c8) Co-authored-by: Jan Gosmann <[email protected]>
|
GH-102001 is a backport of this pull request to the 3.11 branch. |
|
GH-102002 is a backport of this pull request to the 3.10 branch. |
(cherry picked from commit 77d95c8) Co-authored-by: Jan Gosmann <[email protected]>
(cherry picked from commit 77d95c8) Co-authored-by: Jan Gosmann <[email protected]>
Yeah, that's a known unrelated failure, FWIW. |
…2001) gh-100226: Clarify StreamReader.read behavior (GH-101807) (cherry picked from commit 77d95c8) Co-authored-by: Jan Gosmann <[email protected]> Co-authored-by: Shantanu <[email protected]>
This clarifies the
StreamReader.readbehavior in the public documentation; mostly copying from the more precise docstring of the function.While we're at it, also fix some minor grammar in the docstring itself.
Addresses #100226.
Should this be backported so that the documentation for older releases is also updated?
asyncio.StreamReader.readdoes what exactly? #100226