Documentation: unclear exception types for ClientResponse read errors

[bcmills]

Describe the bug

The current documentation for the ClientResponse.read() method says:

Raise an aiohttp.ClientResponseError if the data can’t be read.

And the documentation for the related ClientResponse.content attribute notes that:

Reading from the stream may raise aiohttp.ClientPayloadError if the response object is closed before response receives all data or in case if any transfer encoding related errors like malformed chunked encoding of broken compression data.

Both of those seem surprising: given the exception hierarchy documented later on the page, I would expect a read error caused by a connection reset to instead raise a ClientConnectionResetError, but at the moment the rest of the ClientResponse documentation doesn't seem to mention it one way or another, and I'm having a hard time following the implementation clearly enough to figure out what is actually raised if the connection is reset in the middle of a response body.

FWIW the only place where I see read() explicitly raising an exception, it's a ClientConnectionError, not a ClientResponseError:

aiohttp/aiohttp/client_reqrep.py

Line 1163 in 3f07b1a

raise ClientConnectionError("Connection closed")

Either way, I would appreciate clearer documentation on the relationship between the various ways to read a ClientResponse body and the various subclasses of ClientConnectionError.

To Reproduce

1. Read the documentation at https://docs.aiohttp.org/en/stable/client_reference.html#response-object.
2. Read the documentation at https://docs.aiohttp.org/en/stable/client_reference.html#connection-errors.
3. Try to figure out how the two relate.

Expected behavior

Clear, concise documentation of the behavior of ClientResponse.read() and ClientResponse.content in case of an unexpected connection reset.

Code of Conduct

• I agree to follow the aio-libs Code of Conduct

[Dreamsorcerer]

Both of those seem surprising: given the exception hierarchy documented later on the page, I would expect a read error caused by a connection reset to instead raise a ClientConnectionResetError

I think a ClientConnectionResetError is a TCP-level error (i.e. the TCP connection got reset). The errors you referred to in the documentation are HTTP-level errors (i.e. the TCP connection behaved correctly, but the peer sent an invalid HTTP message or similar).

The exceptions that inherit from builtin exceptions should behave much the same as the builtins (and in many cases are just wrappers around the builtin exception that was caught from cpython code). e.g. For ClientConnectionResetError, you can refer to https://docs.python.org/3/library/exceptions.html#ConnectionResetError

[bcmills]

Yeah, that matches my intuitive expectations — but it isn't currently clear in the documentation, and I'm not sure how to confirm the actual behavior. (I tried reading through the relevant tests, but I wasn't able to find any tests that demonstrate a mid-response read error.)

I'd be happy to send a PR to update the documentation if someone can point me to a reference for what the behavior to be documented actually is. 🙃

[Dreamsorcerer]

If you have specific suggestions to improve the docs, then it would be great if you could put them into a PR. Otherwise, I think this is just a discussion.