`json.load` should document that it uses `json.loads`

[godlygeek]

Documentation

json.load is implemented in terms of json.loads. This is surprising: typically APIs that accept file objects work incrementally and don't require buffering the entire contents of the file in memory (and in fact, json.dump does work incrementally and doesn't buffer the entire contents of the file in memory).

The documentation doesn't mention that json.load reads the entire file into memory. It only says that the file-like passed to load needs to support .read(), but of course all readable file-likes support .read(). It doesn't say that .read() will be called only once and with no arguments.

If anything, the current documentation heavily implies that loads is implemented in terms of load, rather than the reverse. Currently all of the parameters are documented for json.load, and json.loads only refers to that documentation by saying:

Identical to load(), but instead of a file-like object, deserialize s (a str, bytes or bytearray instance containing a JSON document)

To me, this implies that loads behaves as though by load(StringIO(s)).

This documentation should be reversed: all of the documentation that currently lives on json.load should be moved to json.loads, and the docs for json.load should be updated to say:

Identical to loads, passing fp.read() as the string to decode.

[dagangtj]

I'll work on this documentation fix. Assigning to myself.