Link to & explain deviations from RFC 4627 in json module docs

@birkenfeld

BPO	14674
Nosy	@birkenfeld, @pitrou, @ezio-melotti, @merwok, @akheron, @serhiy-storchaka
Files	json.rst.patch: per Ezio's review comments json.rst.patch: reorganize, drop serializer/deserializer division json.rst.patch: hopefully the final version json.rst.patch: fix var name inconsistency in 1 example json.rst.patch: replace "scalar" terminology

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-08-24.17:55:09.756>
created_at = <Date 2012-04-26.14:15:11.891>
labels = ['easy', 'type-feature', 'docs']
title = 'Link to & explain deviations from RFC 4627 in json module docs'
updated_at = <Date 2012-08-24.17:55:09.755>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2012-08-24.17:55:09.755>
actor = 'pitrou'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-08-24.17:55:09.756>
closer = 'pitrou'
components = ['Documentation']
creation = <Date 2012-04-26.14:15:11.891>
creator = 'serhiy.storchaka'
dependencies = []
files = ['25595', '25603', '25667', '25999', '26981']
hgrepos = []
issue_num = 14674
keywords = ['patch', 'easy']
message_count = 24.0
messages = ['159367', '160677', '160692', '160693', '160694', '160695', '160696', '160698', '160699', '160750', '160781', '161239', '161298', '161310', '162726', '163888', '165947', '168935', '168949', '168952', '168976', '169053', '169058', '169060']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'pitrou', 'ezio.melotti', 'eric.araujo', 'cvrebert', 'docs@python', 'python-dev', 'petri.lehtinen', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14674'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

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).

A message should have been sent to [email protected].

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.

Navigation Menu

Repository navigation

Link to & explain deviations from RFC 4627 in json module docs #58879

3 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Link to & explain deviations from RFC 4627 in json module docs #58879

Description

Activity

serhiy-storchaka commented on Apr 26, 2012

cvrebert commented on May 15, 2012

cvrebert commented on May 15, 2012

cvrebert commented on May 15, 2012

ezio-melotti commented on May 15, 2012

cvrebert commented on May 15, 2012

cvrebert commented on May 15, 2012

serhiy-storchaka commented on May 15, 2012

serhiy-storchaka commented on May 15, 2012

3 remaining items

merwok commented on May 21, 2012

cvrebert commented on May 22, 2012

cvrebert commented on Jun 13, 2012

merwok commented on Jun 25, 2012

cvrebert commented on Jul 20, 2012

akheron commented on Aug 23, 2012

merwok commented on Aug 23, 2012

birkenfeld commented on Aug 23, 2012

cvrebert commented on Aug 24, 2012

pitrou commented on Aug 24, 2012

python-dev commented on Aug 24, 2012

pitrou commented on Aug 24, 2012

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions