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.