classification
Title: json.dumps() documentation is slightly incorrect.
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder: json.dump(ensure_ascii=False) return str instead of unicode
View: 13769
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ezio.melotti, petri.lehtinen, rhettinger, terry.reedy, tomchristie
Priority: normal Keywords:

Created on 2012-02-17 16:07 by tomchristie, last changed 2012-09-01 09:37 by petri.lehtinen. This issue is now closed.

Messages (5)
msg153558 - (view) Author: Tom Christie (tomchristie) * Date: 2012-02-17 16:07
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.
msg153621 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-02-18 01:33
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?
msg153638 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-18 10:48
See #13770 and #13769.
msg169271 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-08-28 10:51
This is a documentation bug for 2.7. Setting as duplicate of #13769.
msg169618 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-09-01 09:37
Fixed, see #13769.
History
Date User Action Args
2012-09-01 09:37:34petri.lehtinensetmessages: + msg169618
2012-08-28 10:51:25petri.lehtinensetstatus: open -> closed

superseder: json.dump(ensure_ascii=False) return str instead of unicode
versions: - Python 3.2, Python 3.3
nosy: + petri.lehtinen

messages: + msg169271
resolution: duplicate
stage: needs patch -> resolved
2012-02-18 10:48:23ezio.melottisetnosy: + eric.araujo
messages: + msg153638
2012-02-18 01:33:14terry.reedysetassignee: docs@python
components: + Documentation, - Library (Lib)
versions: + Python 3.2, Python 3.3, - Python 2.6
nosy: + rhettinger, ezio.melotti, terry.reedy, docs@python

messages: + msg153621
stage: needs patch
2012-02-17 16:07:49tomchristiecreate