Terry J. Reedy added the comment: To me, the JSONDecoder doc at the top of this section http://docs.python.org/3/library/json.html#encoders-and-decoders is unclear about decoding process and timing of application and the signature of all 5 hook functions. The timing and signature issues are related. My questions and suggestions: - 'Simple JSON decoder.' + 'A simple JSON decoder that splits JSON strings into JSON substrings that represent programming objects and then converts the substrings into Python objects.' I took the above from Mark's description, using 'substring' instead of 'token'. - '\nPerforms the following translations in decoding by default:' + 'The default translations from JSON object strings to Python objects are as follows:' Should the table have multiple notes? The intended use case for JSON is program to program communication, where both programs 'understand' the legal JSON syntax. Is handcrafting JSON strings, without knowing the syntax, also an intended usecase? I think not. Teaching the syntax is out of scope for the docs. However, the table could be followed by a generic note that JSON syntax and Python syntax for objects are different. + "The legal JSON syntax for various classes is different from Python syntax for the same classes. The tranformations above are only applied to legal JSON strings. For instance, both float('.5') and float(0.5) are legal Python code, but a JSON encoder will only produce '0.5', so a JSON decoder will reject '.5' as an error and not pass it on to float() or its parse_float substitute." This suggestion is intended to replace class by class notes or the proposed addition to the parse_float entry. I think the description of the parse hooks would be clearer if the input signature were given immediately with the name. object_hook: I do not understand enough to suggest anything. Is the input a json string representing an object or a Python dict? object_pairs_hook: Ditto. What is its input? parse_int: This should come before parse_float, to match the table. - '*parse_int*, if specified ...' + '*parse_int*(*num_str*), if specified ...' 'num_str' as the parameter name is used in the ... part. parse_float(num_str): ditto parse_constant(const_str): I do not understand "This can be used to raise an exception if invalid JSON numbers are encountered."

...

...

def f(s): raise ValueError('custom') ... json.loads('.5', parse_constant=f)

gives same error as as without parse_constant. The sentence should be rewritten or removed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue19871> _______________________________________