homepage

The json module documentation should give a link to RFC 4627 and explain the current implementation is different from it. For example, according to RFC 4627 only an object or an array can be top-level JSON element.

Draft docs patch. More cross-referencing. Analysis of deviations from RFC based on previous docs & the RFC.
Don't know if there are relevant, more precise implementation limitations that need to be mentioned.
If backported to 2.x, will need to cover encodings slightly more.

New revision per Éric's Rietveld feedback.
Sidenote: Is there any way to get notified of these reviews? I only saw it because I happened to click the "review" link on a lark.

The "import json"s were left for uniformity with the other code samples in the module's docs.
Also, here's what the pedantically-strict recipes might look like:
def _reject_inf_nan(string):
 if string in {'-Infinity', 'Infinity', 'NaN'}:
 raise ValueError("JSON does not allow infinite or NaN number values")
def _reject_dupe_keys(pairs):
 obj = {}
 for key, value in pairs:
 if key in pairs:
 raise ValueError("Name %s repeated in an object" % repr(key))
 obj[key] = value
 return obj
def strict_loads(string):
 result = loads(string, parse_constant=_reject_inf_nan, object_pairs_hook=_reject_dupe_keys)
 if not isinstance(result, (dict, list)):
 raise ValueError("The top-level entity of the JSON text was not an object or an array")
 return result
def strict_dumps(obj):
 if not isinstance(obj, (dict, list)):
 raise TypeError("The top-level object of a JSON text must be a dict or a list")
 return dumps(obj, allow_nan=False)

Thanks for the patch, I left more comments on the review page.
IMHO it would be better to list the differences in a bullet list and expand later, rather than having a section for the parser and one for the generator.
AFAIU the differences are:
 * top-level scalar values are accepted/generated;
 * inf and nan are accepted/generated;
 * unicode strings (rather than utf-8) are produced/consumed;
 * duplicate keys are accepted, and the only the last one is used;
You can then add examples and explain "workarounds", either inline or after the list (I don't think it's necessary to add the snippets you posted in the last message though).
> Sidenote: Is there any way to get notified of these reviews?
In theory you should get notifications, in practice it doesn't always work. We are still working on make it better.

Further copyediting.

Reflect broader scope

> for key, value in pairs:
> if key in pairs:
"if key in obj:"?

IMHO, it would be sufficient to have a simple bullet list of differences
and notes or warnings in places where Python can generate non-standard
JSON (top-level scalars, inf and nan, non-utf8 encoded strings).

>> for key, value in pairs:
>> if key in pairs:
> 
> "if key in obj:"?
Yes, obviously. :-) It wrote those very late at night.
@Ezio: These were per Éric's feedback but would be for a separate bug/patch.

Notification of any future Rietveld comments would be appreciated.

So, does the refactored patch need any further revising, or is it good to go?

A message should have been sent to pybugs@rebertia.com. 

Hopefully final revision. Thanks for the quick response Éric!
Changes:
- Cover `ensure_ascii` parameter per latest review comment
- Add enhanced "Character Encodings" section for 2.x backport
-- Cover `encoding` parameter & restrictions
-- Cover non-implementation of encoding detection feature
- Hyperlink the JSON-RPC mention

Any further comments now that the matter of encodings is covered more thoroughly?

This looks good to me, apart from very minor style things that I can change before committing. Ezio, any last comments?
One thing I haven’t done is comparing the length of the new section to the rest of the file to see if it’s a small or big addition; if it’s too big, that would be distracting.

Pinging on this, since it's been just short of a month since Éric's "last call" comment.

Using the word "scalar" sounds wrong to me. Are strings really considered scalars in Python? At least RFC 4627 doesn't talk about scalars.
+Since the RFC permits RFC-compliant parsers to accept input texts that are not
+RFC-compliant, this module's deserializer is technically RFC-compliant under
+default settings.
This might scare users. Maybe it should note that there are parameters that can be used to turn off the most "harmful" extra features (namely the Inf and NaN support).
Otherwise, the additions look very good and important.

See also #13212.

Neither json.org nor RFC 4627 mention "scalar". I don't think we should introduce that term, with the necessary ambiguity given the context, needlessly.

Revised patch yet again to instead speak of "non-object, non-array" values and "JSON null, boolean, number, or string" values.
Re: Petri, the patch already mentions the specific parameters one can use to get stricter behavior, albeit not in that particular short paragraph. Feel free to edit the patch.
Any hope of getting this applied soon-ish? I began drafting this over 3 months ago, and yet this issue is tagged "easy"...

Chris, I'm gonna take a look if nobody beats me to it.

New changeset 132886ef135d by Antoine Pitrou in branch '3.2':
Issue #14674: Add a discussion of the json module's standard compliance.
http://hg.python.org/cpython/rev/132886ef135d
New changeset 16c0e26fc9cd by Antoine Pitrou in branch 'default':
Issue #14674: Add a discussion of the json module's standard compliance.
http://hg.python.org/cpython/rev/16c0e26fc9cd
New changeset d413b36dbee5 by Antoine Pitrou in branch '2.7':
Issue #14674: Add a discussion of the json module's standard compliance.
http://hg.python.org/cpython/rev/d413b36dbee5 

Ok, thank you Chris!