[issue14674] Add link to RFC 4627 from json documentation
New submission from Serhiy Storchaka <storchaka@gmail.com>: 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. ---------- assignee: docs@python components: Documentation messages: 159367 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Add link to RFC 4627 from json documentation type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +easy nosy: +eric.araujo stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Nurhusien Hasen <nurhusien.hasen27@gmail.com> added the comment: find python truste .net all serves ---------- nosy: +Nurhusien.Hasen _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Nurhusien Hasen <nurhusien.hasen27@gmail.com> added the comment: find python .org public all serves On 5/6/12, Nurhusien Hasen <report@bugs.python.org> wrote:
Nurhusien Hasen <nurhusien.hasen27@gmail.com> added the comment:
find python truste .net all serves
---------- nosy: +Nurhusien.Hasen
_______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- Removed message: http://bugs.python.org/msg160089 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- Removed message: http://bugs.python.org/msg160098 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: -Nurhusien.Hasen _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ---------- keywords: +patch nosy: +cvrebert Added file: http://bugs.python.org/file25591/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Added file: http://bugs.python.org/file25592/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ---------- Added file: http://bugs.python.org/file25594/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Serhiy Storchaka <storchaka@gmail.com> added the comment:
for key, value in pairs: if key in pairs:
"if key in obj:"? ---------- title: Link to & explain deviations from RFC 4627 in json module docs -> Add link to RFC 4627 from json documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Serhiy Storchaka <storchaka@gmail.com> added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Further copyediting. ---------- Added file: http://bugs.python.org/file25595/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Reflect broader scope ---------- title: Add link to RFC 4627 from json documentation -> Link to & explain deviations from RFC 4627 in json module docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Notification of any future Rietveld comments would be appreciated. ---------- Added file: http://bugs.python.org/file25603/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Added file: http://bugs.python.org/file25606/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file25591/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file25592/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: So, does the refactored patch need any further revising, or is it good to go? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: A message should have been sent to pybugs@rebertia.com. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- stage: needs patch -> commit review title: Add link to RFC 4627 from json documentation -> Link to & explain deviations from RFC 4627 in json module docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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 ---------- Added file: http://bugs.python.org/file25667/final-json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file25594/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Any further comments now that the matter of encodings is covered more thoroughly? ---------- Added file: http://bugs.python.org/file25999/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file25606/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: Pinging on this, since it's been just short of a month since Éric's "last call" comment. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Petri Lehtinen added the 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. ---------- nosy: +petri.lehtinen _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Éric Araujo added the comment: See also #13212. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Georg Brandl added the comment: 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. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Chris Rebert added the comment: 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"... ---------- Added file: http://bugs.python.org/file26981/json.rst.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Antoine Pitrou added the comment: Chris, I'm gonna take a look if nobody beats me to it. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
Antoine Pitrou added the comment: Ok, thank you Chris! ---------- resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________
participants (9)
-
Antoine Pitrou -
Chris Rebert
-
Ezio Melotti
-
Georg Brandl
-
Nurhusien Hasen
-
Petri Lehtinen
-
Roundup Robot
-
Serhiy Storchaka
-
Éric Araujo