Mercurial > cpython-lru_cache-weakref
annotate Doc/library/json.rst @ 79675:c0a2294de787 2.7
Issue #16199: Backport 2to3 typo fix from 3.2.
| author | Chris Jerdonek <chris.jerdonek@gmail.com> |
|---|---|
| date | Thu, 11 Oct 2012 16:15:46 -0700 |
| parents | a1884b3027c5 |
| children | 7784008e9ade |
| rev | line source |
|---|---|
| 46677 | 1 :mod:`json` --- JSON encoder and decoder |
| 2 ======================================== | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
3 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
4 .. module:: json |
| 46677 | 5 :synopsis: Encode and decode the JSON format. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
6 .. moduleauthor:: Bob Ippolito <bob@redivi.com> |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
7 .. sectionauthor:: Bob Ippolito <bob@redivi.com> |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
8 .. versionadded:: 2.6 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
9 |
|
78741
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
10 `JSON (JavaScript Object Notation) <http://json.org>`_, specified by |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
11 :rfc:`4627`, is a lightweight data interchange format based on a subset of |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
12 `JavaScript <http://en.wikipedia.org/wiki/JavaScript>`_ syntax (`ECMA-262 3rd |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
13 edition <http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf>`_). |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
14 |
| 46677 | 15 :mod:`json` exposes an API familiar to users of the standard library |
| 16 :mod:`marshal` and :mod:`pickle` modules. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
17 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
18 Encoding basic Python object hierarchies:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
19 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
20 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
21 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
22 '["foo", {"bar": ["baz", null, 1.0, 2]}]' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
23 >>> print json.dumps("\"foo\bar") |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
24 "\"foo\bar" |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
25 >>> print json.dumps(u'\u1234') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
26 "\u1234" |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
27 >>> print json.dumps('\\') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
28 "\\" |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
29 >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
30 {"a": 0, "b": 0, "c": 0} |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
31 >>> from StringIO import StringIO |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
32 >>> io = StringIO() |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
33 >>> json.dump(['streaming API'], io) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
34 >>> io.getvalue() |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
35 '["streaming API"]' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
36 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
37 Compact encoding:: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
38 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
39 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
40 >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
41 '[1,2,3,{"4":5,"6":7}]' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
42 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
43 Pretty printing:: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
44 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
45 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
46 >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
47 { |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
48 "4": 5, |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
49 "6": 7 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
50 } |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
51 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
52 Decoding JSON:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
53 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
54 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
55 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
56 [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
57 >>> json.loads('"\\"foo\\bar"') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
58 u'"foo\x08ar' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
59 >>> from StringIO import StringIO |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
60 >>> io = StringIO('["streaming API"]') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
61 >>> json.load(io) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
62 [u'streaming API'] |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
63 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
64 Specializing JSON object decoding:: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
65 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
66 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
67 >>> def as_complex(dct): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
68 ... if '__complex__' in dct: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
69 ... return complex(dct['real'], dct['imag']) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
70 ... return dct |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
71 ... |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
72 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
73 ... object_hook=as_complex) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
74 (1+2j) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
75 >>> import decimal |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
76 >>> json.loads('1.1', parse_float=decimal.Decimal) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
77 Decimal('1.1') |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
78 |
| 46677 | 79 Extending :class:`JSONEncoder`:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
80 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
81 >>> import json |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
82 >>> class ComplexEncoder(json.JSONEncoder): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
83 ... def default(self, obj): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
84 ... if isinstance(obj, complex): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
85 ... return [obj.real, obj.imag] |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
86 ... return json.JSONEncoder.default(self, obj) |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
87 ... |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
88 >>> dumps(2 + 1j, cls=ComplexEncoder) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
89 '[2.0, 1.0]' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
90 >>> ComplexEncoder().encode(2 + 1j) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
91 '[2.0, 1.0]' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
92 >>> list(ComplexEncoder().iterencode(2 + 1j)) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
93 ['[', '2.0', ', ', '1.0', ']'] |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
94 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
95 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
96 .. highlight:: none |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
97 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
98 Using json.tool from the shell to validate and pretty-print:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
99 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
100 $ echo '{"json":"obj"}' | python -mjson.tool |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
101 { |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
102 "json": "obj" |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
103 } |
|
77842
7762816e3fcd
Issue #5067: improve some json error messages.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77081
diff
changeset
|
104 $ echo '{1.2:3.4}' | python -mjson.tool |
|
7762816e3fcd
Issue #5067: improve some json error messages.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77081
diff
changeset
|
105 Expecting property name enclosed in double quotes: line 1 column 1 (char 1) |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
106 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
107 .. highlight:: python |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
108 |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
109 .. note:: |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
110 |
|
78741
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
111 JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
112 this module's default settings (in particular, the default *separators* |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
113 value) is also a subset of YAML 1.0 and 1.1. This module can thus also be |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
114 used as a YAML serializer. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
115 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
116 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
117 Basic Usage |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
118 ----------- |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
119 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
120 .. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
121 |
| 46677 | 122 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting |
|
78743
b60875fec9b7
Add glossary references
Antoine Pitrou <solipsis@pitrou.net>
parents:
78741
diff
changeset
|
123 :term:`file-like object`). |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
124 |
| 46677 | 125 If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not |
| 126 of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`, | |
| 127 :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a | |
| 128 :exc:`TypeError`. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
129 |
|
78824
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
130 If *ensure_ascii* is ``True`` (the default), all non-ASCII characters in the |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
131 output are escaped with ``\uXXXX`` sequences, and the result is a |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
132 :class:`str` instance consisting of ASCII characters only. If |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
133 *ensure_ascii* is ``False``, some chunks written to *fp* may be |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
134 :class:`unicode` instances. This usually happens because the input contains |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
135 unicode strings or the *encoding* parameter is used. Unless ``fp.write()`` |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
136 explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
137 this is likely to cause an error. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
138 |
| 46677 | 139 If *check_circular* is ``False`` (default: ``True``), then the circular |
| 140 reference check for container types will be skipped and a circular reference | |
| 141 will result in an :exc:`OverflowError` (or worse). | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
142 |
| 46677 | 143 If *allow_nan* is ``False`` (default: ``True``), then it will be a |
| 144 :exc:`ValueError` to serialize out of range :class:`float` values (``nan``, | |
| 145 ``inf``, ``-inf``) in strict compliance of the JSON specification, instead of | |
| 146 using the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
147 |
| 46677 | 148 If *indent* is a non-negative integer, then JSON array elements and object |
|
69293
8264f68e8251
#10019: Fix regression relative to 2.6: add newlines if indent=0
R David Murray <rdmurray@bitdance.com>
parents:
68256
diff
changeset
|
149 members will be pretty-printed with that indent level. An indent level of 0, |
|
8264f68e8251
#10019: Fix regression relative to 2.6: add newlines if indent=0
R David Murray <rdmurray@bitdance.com>
parents:
68256
diff
changeset
|
150 or negative, will only insert newlines. ``None`` (the default) selects the |
|
8264f68e8251
#10019: Fix regression relative to 2.6: add newlines if indent=0
R David Murray <rdmurray@bitdance.com>
parents:
68256
diff
changeset
|
151 most compact representation. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
152 |
| 46677 | 153 If *separators* is an ``(item_separator, dict_separator)`` tuple, then it |
| 154 will be used instead of the default ``(', ', ': ')`` separators. ``(',', | |
| 155 ':')`` is the most compact JSON representation. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
156 |
| 46677 | 157 *encoding* is the character encoding for str instances, default is UTF-8. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
158 |
| 46677 | 159 *default(obj)* is a function that should return a serializable version of |
| 160 *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
161 |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
162 To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the |
| 46677 | 163 :meth:`default` method to serialize additional types), specify it with the |
|
65375
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
164 *cls* kwarg; otherwise :class:`JSONEncoder` is used. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
165 |
|
69355
8dbf072556b9
#4783: document that is not possible to use json.dump twice on the same stream.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69293
diff
changeset
|
166 .. note:: |
|
8dbf072556b9
#4783: document that is not possible to use json.dump twice on the same stream.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69293
diff
changeset
|
167 |
|
8dbf072556b9
#4783: document that is not possible to use json.dump twice on the same stream.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69293
diff
changeset
|
168 Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol so |
|
8dbf072556b9
#4783: document that is not possible to use json.dump twice on the same stream.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69293
diff
changeset
|
169 trying to serialize more objects with repeated calls to :func:`dump` and |
|
8dbf072556b9
#4783: document that is not possible to use json.dump twice on the same stream.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69293
diff
changeset
|
170 the same *fp* will result in an invalid JSON file. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
171 |
| 46677 | 172 .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
173 |
|
78824
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
174 Serialize *obj* to a JSON formatted :class:`str`. If *ensure_ascii* is |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
175 ``False``, the result may contain non-ASCII characters and the return value |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
176 may be a :class:`unicode` instance. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
177 |
|
78824
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
178 The arguments have the same meaning as in :func:`dump`. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
179 |
|
75777
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
180 .. note:: |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
181 |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
182 Keys in key/value pairs of JSON are always of the type :class:`str`. When |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
183 a dictionary is converted into JSON, all the keys of the dictionary are |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
184 coerced to strings. As a result of this, if a dictionary is convered |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
185 into JSON and then back into a dictionary, the dictionary may not equal |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
186 the original one. That is, ``loads(dumps(x)) != x`` if x has non-string |
|
7c818b4cd98a
explain json.dumps for non-string keys in dicts. closes issue6566. Patch contributed Kirubakaran Athmanathan
Senthil Kumaran <senthil@uthcode.com>
parents:
69355
diff
changeset
|
187 keys. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
188 |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
189 .. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]]) |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
190 |
|
78743
b60875fec9b7
Add glossary references
Antoine Pitrou <solipsis@pitrou.net>
parents:
78741
diff
changeset
|
191 Deserialize *fp* (a ``.read()``-supporting :term:`file-like object` |
|
b60875fec9b7
Add glossary references
Antoine Pitrou <solipsis@pitrou.net>
parents:
78741
diff
changeset
|
192 containing a JSON document) to a Python object. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
193 |
| 46677 | 194 If the contents of *fp* are encoded with an ASCII based encoding other than |
| 195 UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified. | |
| 196 Encodings that are not ASCII based (such as UCS-2) are not allowed, and | |
|
53569
02d6f3a6977f
Merged revisions 71786-71787,71814-71817,71901-71903 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50522
diff
changeset
|
197 should be wrapped with ``codecs.getreader(encoding)(fp)``, or simply decoded |
| 46677 | 198 to a :class:`unicode` object and passed to :func:`loads`. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
199 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
200 *object_hook* is an optional function that will be called with the result of |
|
56807
096b42ccb258
Merged revisions 70590,70650,70704,70768-70769,70776,71008,71010-71011 via svnmerge from
Georg Brandl <georg@python.org>
parents:
53569
diff
changeset
|
201 any object literal decoded (a :class:`dict`). The return value of |
| 46677 | 202 *object_hook* will be used instead of the :class:`dict`. This feature can be used |
|
78741
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
203 to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_ |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
204 class hinting). |
| 46677 | 205 |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
206 *object_pairs_hook* is an optional function that will be called with the |
| 52484 | 207 result of any object literal decoded with an ordered list of pairs. The |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
208 return value of *object_pairs_hook* will be used instead of the |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
209 :class:`dict`. This feature can be used to implement custom decoders that |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
210 rely on the order that the key and value pairs are decoded (for example, |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
211 :func:`collections.OrderedDict` will remember the order of insertion). If |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
212 *object_hook* is also defined, the *object_pairs_hook* takes priority. |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
213 |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
214 .. versionchanged:: 2.7 |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
215 Added support for *object_pairs_hook*. |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
216 |
| 46677 | 217 *parse_float*, if specified, will be called with the string of every JSON |
| 218 float to be decoded. By default, this is equivalent to ``float(num_str)``. | |
| 219 This can be used to use another datatype or parser for JSON floats | |
| 220 (e.g. :class:`decimal.Decimal`). | |
| 221 | |
| 222 *parse_int*, if specified, will be called with the string of every JSON int | |
| 223 to be decoded. By default, this is equivalent to ``int(num_str)``. This can | |
| 224 be used to use another datatype or parser for JSON integers | |
| 225 (e.g. :class:`float`). | |
| 226 | |
| 227 *parse_constant*, if specified, will be called with one of the following | |
|
77000
30d16d1e5175
#14692 Fix json docs to reflect changes in json.load
Hynek Schlawack <hs@ox.cx>
parents:
75777
diff
changeset
|
228 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. |
|
30d16d1e5175
#14692 Fix json docs to reflect changes in json.load
Hynek Schlawack <hs@ox.cx>
parents:
75777
diff
changeset
|
229 This can be used to raise an exception if invalid JSON numbers |
| 46677 | 230 are encountered. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
231 |
|
77081
aad7cf67b9ea
Document when json.load's parse_constant behaviour changed
Hynek Schlawack <hs@ox.cx>
parents:
77000
diff
changeset
|
232 .. versionchanged:: 2.7 |
|
aad7cf67b9ea
Document when json.load's parse_constant behaviour changed
Hynek Schlawack <hs@ox.cx>
parents:
77000
diff
changeset
|
233 *parse_constant* doesn't get called on 'null', 'true', 'false' anymore. |
|
aad7cf67b9ea
Document when json.load's parse_constant behaviour changed
Hynek Schlawack <hs@ox.cx>
parents:
77000
diff
changeset
|
234 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
235 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls`` |
|
65375
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
236 kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments |
|
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
237 will be passed to the constructor of the class. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
238 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
239 |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
240 .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]]) |
| 46677 | 241 |
| 242 Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON | |
| 243 document) to a Python object. | |
| 244 | |
| 245 If *s* is a :class:`str` instance and is encoded with an ASCII based encoding | |
| 246 other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be | |
| 247 specified. Encodings that are not ASCII based (such as UCS-2) are not | |
| 248 allowed and should be decoded to :class:`unicode` first. | |
| 249 | |
|
61488
3148d70528b6
#8642: fix wrong function name.
Georg Brandl <georg@python.org>
parents:
53328
diff
changeset
|
250 The other arguments have the same meaning as in :func:`load`. |
| 46677 | 251 |
| 252 | |
|
78741
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
253 Encoders and Decoders |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
254 --------------------- |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
255 |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
256 .. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict[, object_pairs_hook]]]]]]]) |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
257 |
| 46677 | 258 Simple JSON decoder. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
259 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
260 Performs the following translations in decoding by default: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
261 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
262 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
263 | JSON | Python | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
264 +===============+===================+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
265 | object | dict | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
266 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
267 | array | list | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
268 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
269 | string | unicode | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
270 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
271 | number (int) | int, long | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
272 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
273 | number (real) | float | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
274 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
275 | true | True | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
276 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
277 | false | False | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
278 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
279 | null | None | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
280 +---------------+-------------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
281 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
282 It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
283 corresponding ``float`` values, which is outside the JSON spec. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
284 |
| 46677 | 285 *encoding* determines the encoding used to interpret any :class:`str` objects |
| 286 decoded by this instance (UTF-8 by default). It has no effect when decoding | |
| 287 :class:`unicode` objects. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
288 |
| 46677 | 289 Note that currently only encodings that are a superset of ASCII work, strings |
| 290 of other encodings should be passed in as :class:`unicode`. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
291 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
292 *object_hook*, if specified, will be called with the result of every JSON |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
293 object decoded and its return value will be used in place of the given |
| 46677 | 294 :class:`dict`. This can be used to provide custom deserializations (e.g. to |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
295 support JSON-RPC class hinting). |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
296 |
|
52225
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
297 *object_pairs_hook*, if specified will be called with the result of every |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
298 JSON object decoded with an ordered list of pairs. The return value of |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
299 *object_pairs_hook* will be used instead of the :class:`dict`. This |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
300 feature can be used to implement custom decoders that rely on the order |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
301 that the key and value pairs are decoded (for example, |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
302 :func:`collections.OrderedDict` will remember the order of insertion). If |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
303 *object_hook* is also defined, the *object_pairs_hook* takes priority. |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
304 |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
305 .. versionchanged:: 2.7 |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
306 Added support for *object_pairs_hook*. |
|
a11a676fe6c0
Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents:
50508
diff
changeset
|
307 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
308 *parse_float*, if specified, will be called with the string of every JSON |
| 46677 | 309 float to be decoded. By default, this is equivalent to ``float(num_str)``. |
| 310 This can be used to use another datatype or parser for JSON floats | |
| 311 (e.g. :class:`decimal.Decimal`). | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
312 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
313 *parse_int*, if specified, will be called with the string of every JSON int |
| 46677 | 314 to be decoded. By default, this is equivalent to ``int(num_str)``. This can |
| 315 be used to use another datatype or parser for JSON integers | |
| 316 (e.g. :class:`float`). | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
317 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
318 *parse_constant*, if specified, will be called with one of the following |
| 46677 | 319 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``, |
| 320 ``'false'``. This can be used to raise an exception if invalid JSON numbers | |
| 321 are encountered. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
322 |
|
65375
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
323 If *strict* is ``False`` (``True`` is the default), then control characters |
|
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
324 will be allowed inside strings. Control characters in this context are |
|
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
325 those with character codes in the 0-31 range, including ``'\t'`` (tab), |
|
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
326 ``'\n'``, ``'\r'`` and ``'\0'``. |
|
9347b0a85caf
Recorded merge of revisions 85543 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65127
diff
changeset
|
327 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
328 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
329 .. method:: decode(s) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
330 |
| 46677 | 331 Return the Python representation of *s* (a :class:`str` or |
| 332 :class:`unicode` instance containing a JSON document) | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
333 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
334 .. method:: raw_decode(s) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
335 |
| 46677 | 336 Decode a JSON document from *s* (a :class:`str` or :class:`unicode` |
| 337 beginning with a JSON document) and return a 2-tuple of the Python | |
| 338 representation and the index in *s* where the document ended. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
339 |
| 46677 | 340 This can be used to decode a JSON document from a string that may have |
| 341 extraneous data at the end. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
342 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
343 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
344 .. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]]) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
345 |
| 46677 | 346 Extensible JSON encoder for Python data structures. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
347 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
348 Supports the following objects and types by default: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
349 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
350 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
351 | Python | JSON | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
352 +===================+===============+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
353 | dict | object | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
354 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
355 | list, tuple | array | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
356 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
357 | str, unicode | string | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
358 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
359 | int, long, float | number | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
360 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
361 | True | true | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
362 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
363 | False | false | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
364 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
365 | None | null | |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
366 +-------------------+---------------+ |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
367 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
368 To extend this to recognize other objects, subclass and implement a |
| 46677 | 369 :meth:`default` method with another method that returns a serializable object |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
370 for ``o`` if possible, otherwise it should call the superclass implementation |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
371 (to raise :exc:`TypeError`). |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
372 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
373 If *skipkeys* is ``False`` (the default), then it is a :exc:`TypeError` to |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
374 attempt encoding of keys that are not str, int, long, float or None. If |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
375 *skipkeys* is ``True``, such items are simply skipped. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
376 |
|
78824
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
377 If *ensure_ascii* is ``True`` (the default), all non-ASCII characters in the |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
378 output are escaped with ``\uXXXX`` sequences, and the results are |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
379 :class:`str` instances consisting of ASCII characters only. If |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
380 *ensure_ascii* is ``False``, a result may be a :class:`unicode` |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
381 instance. This usually happens if the input contains unicode strings or the |
|
a1884b3027c5
#13769: Enhance docs for ensure_ascii semantics in JSON decoding functions
Petri Lehtinen <petri@digip.org>
parents:
78743
diff
changeset
|
382 *encoding* parameter is used. |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
383 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
384 If *check_circular* is ``True`` (the default), then lists, dicts, and custom |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
385 encoded objects will be checked for circular references during encoding to |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
386 prevent an infinite recursion (which would cause an :exc:`OverflowError`). |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
387 Otherwise, no such check takes place. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
388 |
| 46677 | 389 If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and |
| 390 ``-Infinity`` will be encoded as such. This behavior is not JSON | |
| 391 specification compliant, but is consistent with most JavaScript based | |
| 392 encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode | |
| 393 such floats. | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
394 |
|
65127
ff734f225b47
Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents:
61488
diff
changeset
|
395 If *sort_keys* is ``True`` (default ``False``), then the output of dictionaries |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
396 will be sorted by key; this is useful for regression tests to ensure that |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
397 JSON serializations can be compared on a day-to-day basis. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
398 |
| 46677 | 399 If *indent* is a non-negative integer (it is ``None`` by default), then JSON |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
400 array elements and object members will be pretty-printed with that indent |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
401 level. An indent level of 0 will only insert newlines. ``None`` is the most |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
402 compact representation. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
403 |
| 46677 | 404 If specified, *separators* should be an ``(item_separator, key_separator)`` |
| 405 tuple. The default is ``(', ', ': ')``. To get the most compact JSON | |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
406 representation, you should specify ``(',', ':')`` to eliminate whitespace. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
407 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
408 If specified, *default* is a function that gets called for objects that can't |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
409 otherwise be serialized. It should return a JSON encodable version of the |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
410 object or raise a :exc:`TypeError`. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
411 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
412 If *encoding* is not ``None``, then all input strings will be transformed |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
413 into unicode using that encoding prior to JSON-encoding. The default is |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
414 UTF-8. |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
415 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
416 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
417 .. method:: default(o) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
418 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
419 Implement this method in a subclass such that it returns a serializable |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
420 object for *o*, or calls the base implementation (to raise a |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
421 :exc:`TypeError`). |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
422 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
423 For example, to support arbitrary iterators, you could implement default |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
424 like this:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
425 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
426 def default(self, o): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
427 try: |
|
49286
25da07fe3630
Indentation normalization.
Georg Brandl <georg@python.org>
parents:
46677
diff
changeset
|
428 iterable = iter(o) |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
429 except TypeError: |
|
49286
25da07fe3630
Indentation normalization.
Georg Brandl <georg@python.org>
parents:
46677
diff
changeset
|
430 pass |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
431 else: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
432 return list(iterable) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
433 return JSONEncoder.default(self, o) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
434 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
435 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
436 .. method:: encode(o) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
437 |
| 46677 | 438 Return a JSON string representation of a Python data structure, *o*. For |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
439 example:: |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
440 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
441 >>> JSONEncoder().encode({"foo": ["bar", "baz"]}) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
442 '{"foo": ["bar", "baz"]}' |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
443 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
444 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
445 .. method:: iterencode(o) |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
446 |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
447 Encode the given object, *o*, and yield each string representation as |
| 46677 | 448 available. For example:: |
|
50522
ee9ced92843a
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents:
50424
diff
changeset
|
449 |
|
46676
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
450 for chunk in JSONEncoder().iterencode(bigobject): |
|
4ded35754cb7
Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff
changeset
|
451 mysocket.write(chunk) |
|
78741
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
452 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
453 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
454 Standard Compliance |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
455 ------------------- |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
456 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
457 The JSON format is specified by :rfc:`4627`. This section details this |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
458 module's level of compliance with the RFC. For simplicity, |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
459 :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and parameters other |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
460 than those explicitly mentioned, are not considered. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
461 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
462 This module does not comply with the RFC in a strict fashion, implementing some |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
463 extensions that are valid JavaScript but not valid JSON. In particular: |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
464 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
465 - Top-level non-object, non-array values are accepted and output; |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
466 - Infinite and NaN number values are accepted and output; |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
467 - Repeated names within an object are accepted, and only the value of the last |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
468 name-value pair is used. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
469 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
470 Since the RFC permits RFC-compliant parsers to accept input texts that are not |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
471 RFC-compliant, this module's deserializer is technically RFC-compliant under |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
472 default settings. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
473 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
474 Character Encodings |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
475 ^^^^^^^^^^^^^^^^^^^ |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
476 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
477 The RFC recommends that JSON be represented using either UTF-8, UTF-16, or |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
478 UTF-32, with UTF-8 being the default. Accordingly, this module uses UTF-8 as |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
479 the default for its *encoding* parameter. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
480 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
481 This module's deserializer only directly works with ASCII-compatible encodings; |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
482 UTF-16, UTF-32, and other ASCII-incompatible encodings require the use of |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
483 workarounds described in the documentation for the deserializer's *encoding* |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
484 parameter. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
485 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
486 The RFC also non-normatively describes a limited encoding detection technique |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
487 for JSON texts; this module's deserializer does not implement this or any other |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
488 kind of encoding detection. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
489 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
490 As permitted, though not required, by the RFC, this module's serializer sets |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
491 *ensure_ascii=True* by default, thus escaping the output so that the resulting |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
492 strings only contain ASCII characters. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
493 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
494 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
495 Top-level Non-Object, Non-Array Values |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
496 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
497 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
498 The RFC specifies that the top-level value of a JSON text must be either a |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
499 JSON object or array (Python :class:`dict` or :class:`list`). This module's |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
500 deserializer also accepts input texts consisting solely of a |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
501 JSON null, boolean, number, or string value:: |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
502 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
503 >>> just_a_json_string = '"spam and eggs"' # Not by itself a valid JSON text |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
504 >>> json.loads(just_a_json_string) |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
505 u'spam and eggs' |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
506 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
507 This module itself does not include a way to request that such input texts be |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
508 regarded as illegal. Likewise, this module's serializer also accepts single |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
509 Python :data:`None`, :class:`bool`, numeric, and :class:`str` |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
510 values as input and will generate output texts consisting solely of a top-level |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
511 JSON null, boolean, number, or string value without raising an exception:: |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
512 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
513 >>> neither_a_list_nor_a_dict = u"spam and eggs" |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
514 >>> json.dumps(neither_a_list_nor_a_dict) # The result is not a valid JSON text |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
515 '"spam and eggs"' |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
516 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
517 This module's serializer does not itself include a way to enforce the |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
518 aforementioned constraint. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
519 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
520 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
521 Infinite and NaN Number Values |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
522 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
523 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
524 The RFC does not permit the representation of infinite or NaN number values. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
525 Despite that, by default, this module accepts and outputs ``Infinity``, |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
526 ``-Infinity``, and ``NaN`` as if they were valid JSON number literal values:: |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
527 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
528 >>> # Neither of these calls raises an exception, but the results are not valid JSON |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
529 >>> json.dumps(float('-inf')) |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
530 '-Infinity' |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
531 >>> json.dumps(float('nan')) |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
532 'NaN' |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
533 >>> # Same when deserializing |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
534 >>> json.loads('-Infinity') |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
535 -inf |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
536 >>> json.loads('NaN') |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
537 nan |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
538 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
539 In the serializer, the *allow_nan* parameter can be used to alter this |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
540 behavior. In the deserializer, the *parse_constant* parameter can be used to |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
541 alter this behavior. |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
542 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
543 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
544 Repeated Names Within an Object |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
545 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
546 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
547 The RFC specifies that the names within a JSON object should be unique, but |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
548 does not specify how repeated names in JSON objects should be handled. By |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
549 default, this module does not raise an exception; instead, it ignores all but |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
550 the last name-value pair for a given name:: |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
551 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
552 >>> weird_json = '{"x": 1, "x": 2, "x": 3}' |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
553 >>> json.loads(weird_json) |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
554 {u'x': 3} |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
555 |
|
d413b36dbee5
Issue #14674: Add a discussion of the json module's standard compliance.
Antoine Pitrou <solipsis@pitrou.net>
parents:
77842
diff
changeset
|
556 The *object_pairs_hook* parameter can be used to alter this behavior. |