json.dumps() documentation is slightly incorrect.

[tomchristie]

BPO	14042
Nosy	@rhettinger, @terryjreedy, @ezio-melotti, @merwok, @tomchristie, @akheron
Superseder	bpo-13769: json.dump(ensure_ascii=False) return str instead of unicode

^{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-28.10:51:25.761>
created_at = <Date 2012-02-17.16:07:49.861>
labels = ['type-bug', 'docs']
title = 'json.dumps() documentation is slightly incorrect.'
updated_at = <Date 2012-09-01.09:37:34.542>
user = 'https://github.com/tomchristie'

bugs.python.org fields:

activity = <Date 2012-09-01.09:37:34.542>
actor = 'petri.lehtinen'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-08-28.10:51:25.761>
closer = 'petri.lehtinen'
components = ['Documentation']
creation = <Date 2012-02-17.16:07:49.861>
creator = 'tomchristie'
dependencies = []
files = []
hgrepos = []
issue_num = 14042
keywords = []
message_count = 5.0
messages = ['153558', '153621', '153638', '169271', '169618']
nosy_count = 7.0
nosy_names = ['rhettinger', 'terry.reedy', 'ezio.melotti', 'eric.araujo', 'tomchristie', 'docs@python', 'petri.lehtinen']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '13769'
type = 'behavior'
url = 'https://bugs.python.org/issue14042'
versions = ['Python 2.7']

[tomchristie]

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.

[terryjreedy]

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?

[ezio-melotti]

See bpo-13770 and bpo-13769.

[akheron]

This is a documentation bug for 2.7. Setting as duplicate of bpo-13769.

[akheron]

Fixed, see bpo-13769.