update json module docs in light of RFC 7159 & ECMA-404

[cvrebert]

BPO	21514
Nosy	@rhettinger, @etrepum, @pitrou, @ezio-melotti, @berkerpeksag, @serhiy-storchaka
Files	json-rfc-7159_1.patch: v1 of patch that updates the json module docs

^{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 = 'https://github.com/serhiy-storchaka'
closed_at = <Date 2014-11-27.19:29:04.124>
created_at = <Date 2014-05-16.04:52:48.125>
labels = ['type-feature', 'docs']
title = 'update json module docs in light of RFC 7159 & ECMA-404'
updated_at = <Date 2014-11-27.19:31:05.394>
user = 'https://bugs.python.org/cvrebert'

bugs.python.org fields:

activity = <Date 2014-11-27.19:31:05.394>
actor = 'serhiy.storchaka'
assignee = 'serhiy.storchaka'
closed = True
closed_date = <Date 2014-11-27.19:29:04.124>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2014-05-16.04:52:48.125>
creator = 'cvrebert'
dependencies = []
files = ['35945']
hgrepos = []
issue_num = 21514
keywords = ['patch']
message_count = 13.0
messages = ['218644', '222972', '223038', '223040', '223041', '223051', '225136', '225178', '231055', '231751', '231770', '231771', '231774']
nosy_count = 9.0
nosy_names = ['rhettinger', 'bob.ippolito', 'pitrou', 'ezio.melotti', 'cvrebert', 'docs@python', 'python-dev', 'berker.peksag', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21514'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[cvrebert]

json module docs: https://docs.python.org/3/library/json.html

New superseding JSON RFC: https://tools.ietf.org/html/rfc7159
Errata to the new RFC: http://www.rfc-editor.org/errata_search.php?rfc=7159
ECMA-404: http://www.ecma-international.org/publications/standards/Ecma-404.htm

These updated specs are of particular relevance to the Standard Compliance section of the json module docs. There are also a bunch of new interoperability notes in the RFC that could probably bear repeating in the module's docs.

[cvrebert]

Here's a draft patch against the default branch that updates the json module's docs accordingly.

Note that under "Implementation Limitations", the statement "This module does not impose any such limits beyond those of the relevant Python datatypes themselves or the Python interpreter itself." is just a guess; I need someone who's familiar with the implementation to verify/correct this.

[etrepum]

This patch looks reasonable to me as-is.

With regard to "Infinite and NaN number values are accepted and output;" there's an option for that (allow_nan=False in encoding, parse_constant=some_function_that_raises in decoding). Since an exception can't be raised in a lambda there's no simple one-liner to ensure compliant decode.

[cvrebert]

Thanks for the speedy review!

Those NaN-related arguments are already mentioned in the docs (see last 2 sentences of https://docs.python.org/3/library/json.html#infinite-and-nan-number-values ), and this patch doesn't touch that subsection.

[etrepum]

Good call, I was just doing a quick review of the patch in isolation. Now I don't have anything at all to comment on :)

[rhettinger]

Thanks Bob. If you want me to apply the patch, just assign this back to me.

[cvrebert]

So, when might I expect to see this patch merged, since it's now been approved?

[rhettinger]

Soonish.

[cvrebert]

Ping! It's been about 3 months since this was given the green light...

[rhettinger]

Serhiy, can you take this one. The patch passes both mine and Bob's review; however, it doesn't apply cleanly to 2.7 and 3.4. I haven't had the time to do the needed backports.

[python-dev]

New changeset 7e534e18a99a by Serhiy Storchaka in branch '2.7':
Issue bpo-21514: The documentation of the json module now refers to new JSON RFC
https://hg.python.org/cpython/rev/7e534e18a99a

New changeset 89bb4384f1e1 by Serhiy Storchaka in branch '3.4':
Issue bpo-21514: The documentation of the json module now refers to new JSON RFC
https://hg.python.org/cpython/rev/89bb4384f1e1

New changeset aced2548345a by Serhiy Storchaka in branch 'default':
Issue bpo-21514: The documentation of the json module now refers to new JSON RFC
https://hg.python.org/cpython/rev/aced2548345a

[cvrebert]

Thanks Serhiy!

[serhiy-storchaka]

Thank you Chris for your patch.