[docs] [issue12315] Improve http.client.HTTPResponse.read documentation

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

The patch does 3 things:

1. clarify that 'amt' in 'the next amt bytes' means 'amount'.

I do not think this is necessary; 'the next blah bytes' is clear. Actually, 'amt' really means 'number', not 'amount', which would imply that 'amt' is a float, not an int. 'amt' was a poor choice of parameter name and should have been 'n' or 'nbytes' I presume it has to be an int, not a float. Since it is passed on to the socket file wrapper, I suspect that io.rawiobase."read(n=-1) 
Read up to n bytes from the object and return them. As a convenience, if n is unspecified or -1, readall() is called. Otherwise, only one system call is ever made. Fewer than n bytes may be returned if the operating system call returns fewer than n bytes.

If 0 bytes are returned, and n was not 0, this indicates end of file. If the object is in non-blocking mode and no bytes are available, None is returned."
applies, but I am not really sure.

2. Add an example after the entry for .read().
This seems out of place since there is already a section for examples. All three of the existing examples use response.read. One of them could be enlarged slightly to read in chunks if an example is needed.

3. Document .closed
If it were mentioned that HTTPResponse is a subclass of RawIOBase, and perhaps it should be, the existence of .closed might be inferred. But since not everything is implemented, and since .closed is useful to iterate (as should be the example), I agree this should be added.

----------
nosy: +terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12315>
_______________________________________