Issue 14042: json.dumps() documentation is slightly incorrect. (original) (raw)

json.dumps() documentation is slightly incorrect.

http://docs.python.org/library/json.html#json.dumps

Reads:

"If ensure_ascii is False, then the return value will be a unicode instance."

Should read:

"If ensure_ascii is False, then the return value MAY BE be a unicode instance."

(Without the caps of course)

bash: python Python 2.7.1 (r271:86832, Jun 16 2011, 16:59:05) [GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] on darwin Type "help", "copyright", "credits" or "license" for more information.

import json type(json.dumps({'a': 1}, ensure_ascii=False)) <type 'str'>

Tested against 2.6 and 2.7.

Entry for dump says "If ensure_ascii is False (default: True), then some chunks written to fp may be unicode instances," Entry for dumps says "If ensure_ascii is False, then the return value will be a unicode instance." Entry for JSONEncoder says "If ensure_ascii is True (the default), the output is guaranteed to be str objects with all incoming unicode characters escaped. If ensure_ascii is False, the output will be a unicode object."

I suspect the latter two meant to say something like "If ensure_ascii is False and any chunk would be unicode, then the whole output is unicode."

And should 'all incoming unicode characters' either be or include 'all non-ascii chars (as in 3.x)?

In 3.x, ensure_ascii apparently has a different meaning. "If ensure_ascii is True (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If ensure_ascii is False, these characters will be output as-is."

Unlike other params used in multiple json functions, ensure_ascii is only defined once, under json.JSONEncoder and not under dump and dumps. Should the JSONEncoder entry to copied to dump and dumps?