Mercurial > cpython-lru_cache-weakref

annotate Lib/json/__init__.py @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 9854520c8200
children 40aedc7da30f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
1 r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
2 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
3 interchange format.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
4
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
5 :mod:`json` exposes an API familiar to users of the standard library
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
6 :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
7 version of the :mod:`json` library contained in Python 2.6, but maintains
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
8 compatibility with Python 2.4 and Python 2.5 and (currently) has
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
9 significant performance advantages, even without using the optional C
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
10 extension for speedups.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
11
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
12 Encoding basic Python object hierarchies::
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
13
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
14 >>> import json
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
15 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
16 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
17 >>> print(json.dumps("\"foo\bar"))
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
18 "\"foo\bar"
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
19 >>> print(json.dumps('\u1234'))
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
20 "\u1234"
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
21 >>> print(json.dumps('\\'))
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
22 "\\"
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
23 >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
24 {"a": 0, "b": 0, "c": 0}
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
25 >>> from io import StringIO
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
26 >>> io = StringIO()
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
27 >>> json.dump(['streaming API'], io)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
28 >>> io.getvalue()
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
29 '["streaming API"]'
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
30
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
31 Compact encoding::
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
32
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
33 >>> import json
75066
f4b7ecf8a5f8 Issue #13703: add a way to randomize the hash values of basic types (str, bytes, datetime)
Georg Brandl <georg@python.org>
parents: 69610
diff changeset
34 >>> from collections import OrderedDict
f4b7ecf8a5f8 Issue #13703: add a way to randomize the hash values of basic types (str, bytes, datetime)
Georg Brandl <georg@python.org>
parents: 69610
diff changeset
35 >>> mydict = OrderedDict([('4', 5), ('6', 7)])
f4b7ecf8a5f8 Issue #13703: add a way to randomize the hash values of basic types (str, bytes, datetime)
Georg Brandl <georg@python.org>
parents: 69610
diff changeset
36 >>> json.dumps([1,2,3,mydict], separators=(',', ':'))
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
37 '[1,2,3,{"4":5,"6":7}]'
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
38
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
39 Pretty printing::
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
40
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
41 >>> import json
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
42 >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
43 >>> print('\n'.join([l.rstrip() for l in s.splitlines()]))
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
44 {
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
45 "4": 5,
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
46 "6": 7
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
47 }
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
48
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
49 Decoding JSON::
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
50
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
51 >>> import json
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
52 >>> obj = ['foo', {'bar': ['baz', None, 1.0, 2]}]
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
53 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
54 True
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
55 >>> json.loads('"\\"foo\\bar"') == '"foo\x08ar'
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
56 True
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
57 >>> from io import StringIO
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
58 >>> io = StringIO('["streaming API"]')
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
59 >>> json.load(io)[0] == 'streaming API'
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
60 True
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
61
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
62 Specializing JSON object decoding::
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
63
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
64 >>> import json
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
65 >>> def as_complex(dct):
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
66 ... if '__complex__' in dct:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
67 ... return complex(dct['real'], dct['imag'])
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
68 ... return dct
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
69 ...
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
70 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
71 ... object_hook=as_complex)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
72 (1+2j)
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
73 >>> from decimal import Decimal
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
74 >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1')
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
75 True
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
76
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
77 Specializing JSON object encoding::
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
78
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
79 >>> import json
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
80 >>> def encode_complex(obj):
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
81 ... if isinstance(obj, complex):
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
82 ... return [obj.real, obj.imag]
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
83 ... raise TypeError(repr(o) + " is not JSON serializable")
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
84 ...
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
85 >>> json.dumps(2 + 1j, default=encode_complex)
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
86 '[2.0, 1.0]'
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
87 >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
88 '[2.0, 1.0]'
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
89 >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
90 '[2.0, 1.0]'
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
91
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
92
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
93 Using json.tool from the shell to validate and pretty-print::
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
94
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
95 $ echo '{"json":"obj"}' | python -m json.tool
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
96 {
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
97 "json": "obj"
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
98 }
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
99 $ echo '{ 1.2:3.4}' | python -m json.tool
77840
9854520c8200 Issue #5067: improve some json error messages.
Antoine Pitrou <solipsis@pitrou.net>
parents: 75066
diff changeset
100 Expecting property name enclosed in double quotes: line 1 column 2 (char 2)
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
101 """
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
102 __version__ = '2.0.9'
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
103 __all__ = [
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
104 'dump', 'dumps', 'load', 'loads',
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
105 'JSONDecoder', 'JSONEncoder',
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
106 ]
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
107
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
108 __author__ = 'Bob Ippolito <bob@redivi.com>'
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
109
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
110 from .decoder import JSONDecoder
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
111 from .encoder import JSONEncoder
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
112
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
113 _default_encoder = JSONEncoder(
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
114 skipkeys=False,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
115 ensure_ascii=True,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
116 check_circular=True,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
117 allow_nan=True,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
118 indent=None,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
119 separators=None,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
120 default=None,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
121 )
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
122
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
123 def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
124 allow_nan=True, cls=None, indent=None, separators=None,
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
125 default=None, **kw):
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
126 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
127 ``.write()``-supporting file-like object).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
128
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
129 If ``skipkeys`` is true then ``dict`` keys that are not basic types
63575
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
130 (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
131 instead of raising a ``TypeError``.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
132
63575
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
133 If ``ensure_ascii`` is false, then the strings written to ``fp`` can
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
134 contain non-ASCII characters if they appear in strings contained in
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
135 ``obj``. Otherwise, all such characters are escaped in JSON strings.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
136
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
137 If ``check_circular`` is false, then the circular reference check
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
138 for container types will be skipped and a circular reference will
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
139 result in an ``OverflowError`` (or worse).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
140
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
141 If ``allow_nan`` is false, then it will be a ``ValueError`` to
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
142 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
143 in strict compliance of the JSON specification, instead of using the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
144 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
145
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
146 If ``indent`` is a non-negative integer, then JSON array elements and
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
147 object members will be pretty-printed with that indent level. An indent
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
148 level of 0 will only insert newlines. ``None`` is the most compact
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
149 representation.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
150
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
151 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
152 then it will be used instead of the default ``(', ', ': ')`` separators.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
153 ``(',', ':')`` is the most compact JSON representation.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
154
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
155 ``default(obj)`` is a function that should return a serializable version
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
156 of obj or raise TypeError. The default simply raises TypeError.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
157
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
158 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
159 ``.default()`` method to serialize additional types), specify it with
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
160 the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
161
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
162 """
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
163 # cached encoder
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
164 if (not skipkeys and ensure_ascii and
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
165 check_circular and allow_nan and
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
166 cls is None and indent is None and separators is None and
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
167 default is None and not kw):
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
168 iterable = _default_encoder.iterencode(obj)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
169 else:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
170 if cls is None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
171 cls = JSONEncoder
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
172 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
173 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
174 separators=separators,
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
175 default=default, **kw).iterencode(obj)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
176 # could accelerate with writelines in some versions of Python, at
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
177 # a debuggability cost
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
178 for chunk in iterable:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
179 fp.write(chunk)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
180
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
181
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
182 def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
183 allow_nan=True, cls=None, indent=None, separators=None,
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
184 default=None, **kw):
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
185 """Serialize ``obj`` to a JSON formatted ``str``.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
186
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
187 If ``skipkeys`` is false then ``dict`` keys that are not basic types
63575
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
188 (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
189 instead of raising a ``TypeError``.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
190
63575
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
191 If ``ensure_ascii`` is false, then the return value can contain non-ASCII
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
192 characters if they appear in strings contained in ``obj``. Otherwise, all
4874efd1f657 #9087: update json docstrings -- unicode and long do not exist anymore.
Georg Brandl <georg@python.org>
parents: 53667
diff changeset
193 such characters are escaped in JSON strings.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
194
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
195 If ``check_circular`` is false, then the circular reference check
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
196 for container types will be skipped and a circular reference will
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
197 result in an ``OverflowError`` (or worse).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
198
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
199 If ``allow_nan`` is false, then it will be a ``ValueError`` to
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
200 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
201 strict compliance of the JSON specification, instead of using the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
202 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
203
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
204 If ``indent`` is a non-negative integer, then JSON array elements and
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
205 object members will be pretty-printed with that indent level. An indent
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
206 level of 0 will only insert newlines. ``None`` is the most compact
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
207 representation.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
208
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
209 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
210 then it will be used instead of the default ``(', ', ': ')`` separators.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
211 ``(',', ':')`` is the most compact JSON representation.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
212
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
213 ``default(obj)`` is a function that should return a serializable version
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
214 of obj or raise TypeError. The default simply raises TypeError.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
215
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
216 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
217 ``.default()`` method to serialize additional types), specify it with
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
218 the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
219
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
220 """
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
221 # cached encoder
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
222 if (not skipkeys and ensure_ascii and
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
223 check_circular and allow_nan and
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
224 cls is None and indent is None and separators is None and
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
225 default is None and not kw):
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
226 return _default_encoder.encode(obj)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
227 if cls is None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
228 cls = JSONEncoder
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
229 return cls(
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
230 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
231 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
232 separators=separators, default=default,
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
233 **kw).encode(obj)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
234
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
235
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
236 _default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None)
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
237
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
238
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
239 def load(fp, cls=None, object_hook=None, parse_float=None,
53296
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
240 parse_int=None, parse_constant=None, object_pairs_hook=None, **kw):
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
241 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
242 a JSON document) to a Python object.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
243
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
244 ``object_hook`` is an optional function that will be called with the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
245 result of any object literal decode (a ``dict``). The return value of
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
246 ``object_hook`` will be used instead of the ``dict``. This feature
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
247 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
248
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
249 ``object_pairs_hook`` is an optional function that will be called with the
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
250 result of any object literal decoded with an ordered list of pairs. The
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
251 return value of ``object_pairs_hook`` will be used instead of the ``dict``.
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
252 This feature can be used to implement custom decoders that rely on the
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
253 order that the key and value pairs are decoded (for example,
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
254 collections.OrderedDict will remember the order of insertion). If
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
255 ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
256
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
257 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
258 kwarg; otherwise ``JSONDecoder`` is used.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
259
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
260 """
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
261 return loads(fp.read(),
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
262 cls=cls, object_hook=object_hook,
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
263 parse_float=parse_float, parse_int=parse_int,
53296
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
264 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, **kw)
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
265
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
266
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
267 def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
53296
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
268 parse_int=None, parse_constant=None, object_pairs_hook=None, **kw):
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
269 """Deserialize ``s`` (a ``str`` instance containing a JSON
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
270 document) to a Python object.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
271
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
272 ``object_hook`` is an optional function that will be called with the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
273 result of any object literal decode (a ``dict``). The return value of
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
274 ``object_hook`` will be used instead of the ``dict``. This feature
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
275 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
276
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
277 ``object_pairs_hook`` is an optional function that will be called with the
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
278 result of any object literal decoded with an ordered list of pairs. The
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
279 return value of ``object_pairs_hook`` will be used instead of the ``dict``.
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
280 This feature can be used to implement custom decoders that rely on the
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
281 order that the key and value pairs are decoded (for example,
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
282 collections.OrderedDict will remember the order of insertion). If
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
283 ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
284
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
285 ``parse_float``, if specified, will be called with the string
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
286 of every JSON float to be decoded. By default this is equivalent to
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
287 float(num_str). This can be used to use another datatype or parser
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
288 for JSON floats (e.g. decimal.Decimal).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
289
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
290 ``parse_int``, if specified, will be called with the string
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
291 of every JSON int to be decoded. By default this is equivalent to
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
292 int(num_str). This can be used to use another datatype or parser
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
293 for JSON integers (e.g. float).
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
294
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
295 ``parse_constant``, if specified, will be called with one of the
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
296 following strings: -Infinity, Infinity, NaN, null, true, false.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
297 This can be used to raise an exception if invalid JSON numbers
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
298 are encountered.
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
299
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
300 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
65374
6f4cf73032fc #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
Georg Brandl <georg@python.org>
parents: 63575
diff changeset
301 kwarg; otherwise ``JSONDecoder`` is used.
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
302
67712
8e0b617c6c22 Fix JSON docs about loads() accepting only str objects, not bytes.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65374
diff changeset
303 The ``encoding`` argument is ignored and deprecated.
8e0b617c6c22 Fix JSON docs about loads() accepting only str objects, not bytes.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65374
diff changeset
304
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
305 """
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
306 if (cls is None and object_hook is None and
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
307 parse_int is None and parse_float is None and
53296
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
308 parse_constant is None and object_pairs_hook is None and not kw):
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
309 return _default_decoder.decode(s)
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
310 if cls is None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
311 cls = JSONDecoder
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
312 if object_hook is not None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
313 kw['object_hook'] = object_hook
53296
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
314 if object_pairs_hook is not None:
93c929a2fac7 Forward port r70471: Add object_pairs_hook. Issue 5381.
Raymond Hettinger <python@rcn.com>
parents: 46737
diff changeset
315 kw['object_pairs_hook'] = object_pairs_hook
46737
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
316 if parse_float is not None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
317 kw['parse_float'] = parse_float
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
318 if parse_int is not None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
319 kw['parse_int'] = parse_int
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
320 if parse_constant is not None:
9f45979558a9 Merged revisions 62734,62736,62748,62769 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
321 kw['parse_constant'] = parse_constant
53667
f686aced02a3 port simplejson upgrade from the trunk #4136
Benjamin Peterson <benjamin@python.org>
parents: 53296
diff changeset
322 return cls(**kw).decode(s)