`asyncio.StreamReader.read` does what exactly?

[ygoe]

Documentation

https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamReader.read

It remains unclear what exactly that method does. It will give me no more than n bytes from the stream. That's a pretty vague contract. Will it sit there until so many bytes are available? Or will it return each one separately? Will they be fragmented in some way? How long will it wait for more bytes to become available?

And what does "EOF" mean?! I know this from the old DOS days as "end of file" but it has two meanings (the byte \x1A inside a file, or the actual end of a file on disk) which I don't see apply here.

Similarly for the other read methods, will they wait and only return when so many bytes have been received? Are there any timeouts? What about cancellation? I'm not sure if I can expect the same level of features as in .NET, but at least I'd like to know what to expect.

Linked PRs

• gh-100226: Clarify StreamReader.read behavior #101807
• [3.11] gh-100226: Clarify StreamReader.read behavior (GH-101807) #102001
• [3.10] gh-100226: Clarify StreamReader.read behavior (GH-101807) #102002

[ygoe]

Looks like calling read without argument hangs forever. I need to give it a chunk size I want to read with. Then it gives me all received bytes, up to the limit.

[sweeneyde]

It looks like there is more detail in the docstring than there is in the docs:

>>> from asyncio.streams import StreamReader
>>> help(StreamReader.read)
Help on function read in module asyncio.streams:

async read(self, n=-1)
    Read up to `n` bytes from the stream.

    If n is not provided, or set to -1, read until EOF and return all read
    bytes. If the EOF was received and the internal buffer is empty, return
    an empty bytes object.

    If n is zero, return empty bytes object immediately.

    If n is positive, this function try to read `n` bytes, and may return
    less or equal bytes than requested, but at least one byte. If EOF was
    received before any byte is read, this function returns empty byte
    object.

    Returned value is not limited with limit, configured at stream
    creation.

    If stream was paused, this function will automatically resume it if
    needed.

I'm not well versed in asyncio, but I'm guessing the docs page could be improved.

[ramvikrams]

i'll do the changes in doc for this and other read methods

[jgosmann]

The docstring is indeed much better than the docs page where I completely overlooked that with positive n less than n bytes might be returned (it is not made very explicit). However, it is still not clear to me whether n = -1 guarantees that everything until EOF (whatever that means) is read? Or could that also return before the EOF?

[jgosmann]

Ok, if I understand the code correctly, it should really read everything with n = -1 given that read always returns at least one byte.

[gvanrossum]

If someone wants to submit a quick PR that would be welcome. (The reason for the lack of precision is that this pretty much follows the same conventions as typical UNIX low-level read() calls, with the Python extension that omitting the argument reads until EOF -- but if you're new to Python that convention is not obvious, and we should not rely on it.)