Mercurial > cpython-lru_cache-weakref

annotate Doc/library/json.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 170055d7b494
children 3148d70528b6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
1 :mod:`json` --- JSON encoder and decoder
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
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
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
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
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
10 JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
11 syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
12
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
13 :mod:`json` exposes an API familiar to users of the standard library
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
14 :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
15
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
16 Encoding basic Python object hierarchies::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
17
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
18 >>> 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
19 >>> 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
20 '["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
21 >>> 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
22 "\"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
23 >>> 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
24 "\u1234"
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('\\')
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
26 "\\"
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({"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
28 {"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
29 >>> 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
30 >>> 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
31 >>> 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
32 >>> 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
33 '["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
34
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
35 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
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 >>> 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
38 >>> 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
39 '[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
40
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
41 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
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 >>> 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
44 >>> 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
45 {
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
46 "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
47 "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
48 }
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
49
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
50 Decoding JSON::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
51
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
52 >>> 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
53 >>> 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
54 [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
55 >>> 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
56 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
57 >>> 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
58 >>> 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
59 >>> 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
60 [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
61
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
62 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
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 >>> 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
65 >>> 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
66 ... 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
67 ... 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
68 ... return dct
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
69 ...
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
70 >>> 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
71 ... 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
72 (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
73 >>> 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
74 >>> 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
75 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
76
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
77 Extending :class:`JSONEncoder`::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
78
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
79 >>> 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
80 >>> 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
81 ... 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
82 ... 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
83 ... 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
84 ... return json.JSONEncoder.default(self, obj)
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
85 ...
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
86 >>> 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
87 '[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
88 >>> 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
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 >>> 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
91 ['[', '2.0', ', ', '1.0', ']']
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
92
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
93
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
94 .. 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
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 Using json.tool from the shell to validate and pretty-print::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
97
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
98 $ 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
99 {
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
100 "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
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 $ echo '{ 1.2:3.4}' | 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
103 Expecting property name: line 1 column 2 (char 2)
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
104
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
105 .. 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
106
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
107 .. 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
108
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
109 The JSON produced by this module's default settings is a subset of
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 YAML, so it may be used as a serializer for that as well.
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
111
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
112
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
113 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
114 -----------
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 .. 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
117
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
118 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
119 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
120
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
121 If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
122 of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
123 :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
124 :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
125
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
126 If *ensure_ascii* is ``False`` (default: ``True``), then some chunks written
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
127 to *fp* may be :class:`unicode` instances, subject to normal Python
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
128 :class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
129 explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) this
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
130 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
131
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
132 If *check_circular* is ``False`` (default: ``True``), then the circular
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
133 reference check for container types will be skipped and a circular reference
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
134 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
135
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
136 If *allow_nan* is ``False`` (default: ``True``), then it will be a
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
137 :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
138 ``inf``, ``-inf``) in strict compliance of the JSON specification, instead of
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
139 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
140
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
141 If *indent* is a non-negative integer, then JSON array elements and object
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
142 members will be pretty-printed with that indent level. An indent level of 0
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
143 will only insert newlines. ``None`` (the default) selects the most compact
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
144 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
145
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
146 If *separators* is an ``(item_separator, dict_separator)`` tuple, then it
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
147 will be used instead of the default ``(', ', ': ')`` separators. ``(',',
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
148 ':')`` 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
149
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
150 *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
151
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
152 *default(obj)* is a function that should return a serializable version of
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
153 *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
154
50459
8eddd665e9b9 #4811: fix markup glitches (mostly remains of the conversion),
Georg Brandl <georg@python.org>
parents: 50424
diff changeset
155 To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
156 :meth:`default` method to serialize additional types), specify it with the
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
157 *cls* kwarg.
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
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
159
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
160 .. 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
161
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
162 Serialize *obj* to a JSON formatted :class:`str`.
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
163
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
164 If *ensure_ascii* is ``False``, then the return value will be a
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
165 :class:`unicode` instance. The other arguments have the same meaning as in
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
166 :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
167
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
168
52225
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
169 .. 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
170
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
171 Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
172 document) to a Python object.
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
173
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
174 If the contents of *fp* are encoded with an ASCII based encoding other than
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
175 UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
176 Encodings that are not ASCII based (such as UCS-2) are not allowed, and
53328
170055d7b494 #5820: fix bug in usage of getreader().
Georg Brandl <georg@python.org>
parents: 52484
diff changeset
177 should be wrapped with ``codecs.getreader(encoding)(fp)``, or simply decoded
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
178 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
179
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
180 *object_hook* is an optional function that will be called with the result of
52484
43eba789158f Typo fixes
Andrew M. Kuchling <amk@amk.ca>
parents: 52225
diff changeset
181 any object literal decoded (a :class:`dict`). The return value of
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
182 *object_hook* will be used instead of the :class:`dict`. This feature can be used
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
183 to implement custom decoders (e.g. JSON-RPC class hinting).
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
184
52225
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
185 *object_pairs_hook* is an optional function that will be called with the
52484
43eba789158f Typo fixes
Andrew M. Kuchling <amk@amk.ca>
parents: 52225
diff changeset
186 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
187 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
188 :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
189 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
190 :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
191 *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
192
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
193 .. versionchanged:: 2.7
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
194 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
195
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
196 *parse_float*, if specified, will be called with the string of every JSON
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
197 float to be decoded. By default, this is equivalent to ``float(num_str)``.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
198 This can be used to use another datatype or parser for JSON floats
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
199 (e.g. :class:`decimal.Decimal`).
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
200
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
201 *parse_int*, if specified, will be called with the string of every JSON int
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
202 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
203 be used to use another datatype or parser for JSON integers
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
204 (e.g. :class:`float`).
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
205
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
206 *parse_constant*, if specified, will be called with one of the following
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
207 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``,
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
208 ``'false'``. This can be used to raise an exception if invalid JSON numbers
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
209 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
210
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
211 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
212 kwarg. Additional keyword arguments will be passed to the constructor of the
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
213 class.
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
214
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
215
52225
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
216 .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
217
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
218 Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
219 document) to a Python object.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
220
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
221 If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
222 other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
223 specified. Encodings that are not ASCII based (such as UCS-2) are not
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
224 allowed and should be decoded to :class:`unicode` first.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
225
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
226 The other arguments have the same meaning as in :func:`dump`.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
227
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
228
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
229 Encoders and decoders
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
230 ---------------------
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
231
52225
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
232 .. 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
233
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
234 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
235
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
236 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
237
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 | 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
240 +===============+===================+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
241 | 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
242 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
243 | 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
244 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
245 | 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
246 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
247 | 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
248 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
249 | 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
250 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
251 | 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
252 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
253 | 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
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 | 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
256 +---------------+-------------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
257
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
258 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
259 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
260
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
261 *encoding* determines the encoding used to interpret any :class:`str` objects
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
262 decoded by this instance (UTF-8 by default). It has no effect when decoding
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
263 :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
264
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
265 Note that currently only encodings that are a superset of ASCII work, strings
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
266 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
267
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
268 *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
269 object decoded and its return value will be used in place of the given
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
270 :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
271 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
272
52225
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
273 *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
274 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
275 *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
276 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
277 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
278 :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
279 *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
280
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
281 .. versionchanged:: 2.7
a11a676fe6c0 Issue 5381: Add object_pairs_hook to the json module.
Raymond Hettinger <python@rcn.com>
parents: 50508
diff changeset
282 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
283
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
284 *parse_float*, if specified, will be called with the string of every JSON
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
285 float to be decoded. By default, this is equivalent to ``float(num_str)``.
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
286 This can be used to use another datatype or parser for JSON floats
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
287 (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
288
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
289 *parse_int*, if specified, will be called with the string of every JSON int
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
290 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
291 be used to use another datatype or parser for JSON integers
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
292 (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
293
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
294 *parse_constant*, if specified, will be called with one of the following
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
295 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``,
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
296 ``'false'``. This can be used to raise an exception if invalid JSON numbers
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
297 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
298
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
299
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
300 .. 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
301
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
302 Return the Python representation of *s* (a :class:`str` or
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
303 :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
304
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
305 .. 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
306
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
307 Decode a JSON document from *s* (a :class:`str` or :class:`unicode`
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
308 beginning with a JSON document) and return a 2-tuple of the Python
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
309 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
310
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
311 This can be used to decode a JSON document from a string that may have
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
312 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
313
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
314
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
315 .. 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
316
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
317 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
318
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
319 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
320
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
321 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
322 | 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
323 +===================+===============+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
324 | 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
325 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
326 | 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
327 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
328 | 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
329 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
330 | 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
331 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
332 | 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
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 | 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
335 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
336 | 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
337 +-------------------+---------------+
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
338
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
339 To extend this to recognize other objects, subclass and implement a
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
340 :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
341 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
342 (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
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 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
345 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
346 *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
347
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
348 If *ensure_ascii* is ``True`` (the default), the output is guaranteed to be
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
349 :class:`str` objects with all incoming unicode characters escaped. If
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
350 *ensure_ascii* is ``False``, the output will be a unicode 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
351
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
352 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
353 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
354 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
355 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
356
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
357 If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
358 ``-Infinity`` will be encoded as such. This behavior is not JSON
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
359 specification compliant, but is consistent with most JavaScript based
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
360 encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
361 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
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 If *sort_keys* is ``True`` (the default), then the output of dictionaries
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
364 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
365 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
366
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
367 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
368 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
369 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
370 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
371
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
372 If specified, *separators* should be an ``(item_separator, key_separator)``
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
373 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
374 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
375
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
376 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
377 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
378 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
379
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
380 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
381 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
382 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
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
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
385 .. 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
386
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
387 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
388 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
389 :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
390
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
391 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
392 like this::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
393
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 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
395 try:
49286
25da07fe3630 Indentation normalization.
Georg Brandl <georg@python.org>
parents: 46677
diff changeset
396 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
397 except TypeError:
49286
25da07fe3630 Indentation normalization.
Georg Brandl <georg@python.org>
parents: 46677
diff changeset
398 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
399 else:
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
400 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
401 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
402
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
403
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
404 .. 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
405
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
406 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
407 example::
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
408
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
409 >>> 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
410 '{"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
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
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
413 .. 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
414
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
415 Encode the given object, *o*, and yield each string representation as
46677
34a5380ee275 Fix JSON module docs.
Georg Brandl <georg@python.org>
parents: 46676
diff changeset
416 available. For example::
50508
c52177f36852 Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 50459
diff changeset
417
46676
4ded35754cb7 Add the 'json' package. Code taken from simplejson 1.9 and contributed by Bob
Brett Cannon <bcannon@gmail.com>
parents:
diff changeset
418 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
419 mysocket.write(chunk)