8817bb2e |
1 | r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of |
2 | JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data |
3 | interchange format. |
4 | |
5 | :mod:`simplejson` exposes an API familiar to users of the standard library |
6 | :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained |
7 | version of the :mod:`json` library contained in Python 2.6, but maintains |
8 | compatibility with Python 2.4 and Python 2.5 and (currently) has |
9 | significant performance advantages, even without using the optional C |
10 | extension for speedups. |
11 | |
12 | Encoding basic Python object hierarchies:: |
13 | |
14 | >>> import simplejson as json |
15 | >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) |
16 | '["foo", {"bar": ["baz", null, 1.0, 2]}]' |
17 | >>> print json.dumps("\"foo\bar") |
18 | "\"foo\bar" |
19 | >>> print json.dumps(u'\u1234') |
20 | "\u1234" |
21 | >>> print json.dumps('\\') |
22 | "\\" |
23 | >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) |
24 | {"a": 0, "b": 0, "c": 0} |
25 | >>> from StringIO import StringIO |
26 | >>> io = StringIO() |
27 | >>> json.dump(['streaming API'], io) |
28 | >>> io.getvalue() |
29 | '["streaming API"]' |
30 | |
31 | Compact encoding:: |
32 | |
33 | >>> import simplejson as json |
34 | >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) |
35 | '[1,2,3,{"4":5,"6":7}]' |
36 | |
37 | Pretty printing:: |
38 | |
39 | >>> import simplejson as json |
40 | >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) |
41 | >>> print '\n'.join([l.rstrip() for l in s.splitlines()]) |
42 | { |
43 | "4": 5, |
44 | "6": 7 |
45 | } |
46 | |
47 | Decoding JSON:: |
48 | |
49 | >>> import simplejson as json |
50 | >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] |
51 | >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj |
52 | True |
53 | >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' |
54 | True |
55 | >>> from StringIO import StringIO |
56 | >>> io = StringIO('["streaming API"]') |
57 | >>> json.load(io)[0] == 'streaming API' |
58 | True |
59 | |
60 | Specializing JSON object decoding:: |
61 | |
62 | >>> import simplejson as json |
63 | >>> def as_complex(dct): |
64 | ... if '__complex__' in dct: |
65 | ... return complex(dct['real'], dct['imag']) |
66 | ... return dct |
67 | ... |
68 | >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', |
69 | ... object_hook=as_complex) |
70 | (1+2j) |
71 | >>> import decimal |
72 | >>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1') |
73 | True |
74 | |
75 | Specializing JSON object encoding:: |
76 | |
77 | >>> import simplejson as json |
78 | >>> def encode_complex(obj): |
79 | ... if isinstance(obj, complex): |
80 | ... return [obj.real, obj.imag] |
81 | ... raise TypeError(repr(o) + " is not JSON serializable") |
82 | ... |
83 | >>> json.dumps(2 + 1j, default=encode_complex) |
84 | '[2.0, 1.0]' |
85 | >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) |
86 | '[2.0, 1.0]' |
87 | >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) |
88 | '[2.0, 1.0]' |
89 | |
90 | |
91 | Using simplejson.tool from the shell to validate and pretty-print:: |
92 | |
93 | $ echo '{"json":"obj"}' | python -m simplejson.tool |
94 | { |
95 | "json": "obj" |
96 | } |
97 | $ echo '{ 1.2:3.4}' | python -m simplejson.tool |
98 | Expecting property name: line 1 column 2 (char 2) |
99 | """ |
100 | __version__ = '2.0.9' |
101 | __all__ = [ |
102 | 'dump', 'dumps', 'load', 'loads', |
103 | 'JSONDecoder', 'JSONEncoder', |
104 | ] |
105 | |
106 | __author__ = 'Bob Ippolito <bob@redivi.com>' |
107 | |
108 | from decoder import JSONDecoder |
109 | from encoder import JSONEncoder |
110 | |
111 | _default_encoder = JSONEncoder( |
112 | skipkeys=False, |
113 | ensure_ascii=True, |
114 | check_circular=True, |
115 | allow_nan=True, |
116 | indent=None, |
117 | separators=None, |
118 | encoding='utf-8', |
119 | default=None, |
120 | ) |
121 | |
122 | def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, |
123 | allow_nan=True, cls=None, indent=None, separators=None, |
124 | encoding='utf-8', default=None, **kw): |
125 | """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a |
126 | ``.write()``-supporting file-like object). |
127 | |
128 | If ``skipkeys`` is true then ``dict`` keys that are not basic types |
129 | (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) |
130 | will be skipped instead of raising a ``TypeError``. |
131 | |
132 | If ``ensure_ascii`` is false, then the some chunks written to ``fp`` |
133 | may be ``unicode`` instances, subject to normal Python ``str`` to |
134 | ``unicode`` coercion rules. Unless ``fp.write()`` explicitly |
135 | understands ``unicode`` (as in ``codecs.getwriter()``) this is likely |
136 | to cause an error. |
137 | |
138 | If ``check_circular`` is false, then the circular reference check |
139 | for container types will be skipped and a circular reference will |
140 | result in an ``OverflowError`` (or worse). |
141 | |
142 | If ``allow_nan`` is false, then it will be a ``ValueError`` to |
143 | serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) |
144 | in strict compliance of the JSON specification, instead of using the |
145 | JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). |
146 | |
147 | If ``indent`` is a non-negative integer, then JSON array elements and object |
148 | members will be pretty-printed with that indent level. An indent level |
149 | of 0 will only insert newlines. ``None`` is the most compact representation. |
150 | |
151 | If ``separators`` is an ``(item_separator, dict_separator)`` tuple |
152 | then it will be used instead of the default ``(', ', ': ')`` separators. |
153 | ``(',', ':')`` is the most compact JSON representation. |
154 | |
155 | ``encoding`` is the character encoding for str instances, default is UTF-8. |
156 | |
157 | ``default(obj)`` is a function that should return a serializable version |
158 | of obj or raise TypeError. The default simply raises TypeError. |
159 | |
160 | To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the |
161 | ``.default()`` method to serialize additional types), specify it with |
162 | the ``cls`` kwarg. |
163 | |
164 | """ |
165 | # cached encoder |
166 | if (not skipkeys and ensure_ascii and |
167 | check_circular and allow_nan and |
168 | cls is None and indent is None and separators is None and |
169 | encoding == 'utf-8' and default is None and not kw): |
170 | iterable = _default_encoder.iterencode(obj) |
171 | else: |
172 | if cls is None: |
173 | cls = JSONEncoder |
174 | iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, |
175 | check_circular=check_circular, allow_nan=allow_nan, indent=indent, |
176 | separators=separators, encoding=encoding, |
177 | default=default, **kw).iterencode(obj) |
178 | # could accelerate with writelines in some versions of Python, at |
179 | # a debuggability cost |
180 | for chunk in iterable: |
181 | fp.write(chunk) |
182 | |
183 | |
184 | def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, |
185 | allow_nan=True, cls=None, indent=None, separators=None, |
186 | encoding='utf-8', default=None, **kw): |
187 | """Serialize ``obj`` to a JSON formatted ``str``. |
188 | |
189 | If ``skipkeys`` is false then ``dict`` keys that are not basic types |
190 | (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) |
191 | will be skipped instead of raising a ``TypeError``. |
192 | |
193 | If ``ensure_ascii`` is false, then the return value will be a |
194 | ``unicode`` instance subject to normal Python ``str`` to ``unicode`` |
195 | coercion rules instead of being escaped to an ASCII ``str``. |
196 | |
197 | If ``check_circular`` is false, then the circular reference check |
198 | for container types will be skipped and a circular reference will |
199 | result in an ``OverflowError`` (or worse). |
200 | |
201 | If ``allow_nan`` is false, then it will be a ``ValueError`` to |
202 | serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in |
203 | strict compliance of the JSON specification, instead of using the |
204 | JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). |
205 | |
206 | If ``indent`` is a non-negative integer, then JSON array elements and |
207 | object members will be pretty-printed with that indent level. An indent |
208 | level of 0 will only insert newlines. ``None`` is the most compact |
209 | representation. |
210 | |
211 | If ``separators`` is an ``(item_separator, dict_separator)`` tuple |
212 | then it will be used instead of the default ``(', ', ': ')`` separators. |
213 | ``(',', ':')`` is the most compact JSON representation. |
214 | |
215 | ``encoding`` is the character encoding for str instances, default is UTF-8. |
216 | |
217 | ``default(obj)`` is a function that should return a serializable version |
218 | of obj or raise TypeError. The default simply raises TypeError. |
219 | |
220 | To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the |
221 | ``.default()`` method to serialize additional types), specify it with |
222 | the ``cls`` kwarg. |
223 | |
224 | """ |
225 | # cached encoder |
226 | if (not skipkeys and ensure_ascii and |
227 | check_circular and allow_nan and |
228 | cls is None and indent is None and separators is None and |
229 | encoding == 'utf-8' and default is None and not kw): |
230 | return _default_encoder.encode(obj) |
231 | if cls is None: |
232 | cls = JSONEncoder |
233 | return cls( |
234 | skipkeys=skipkeys, ensure_ascii=ensure_ascii, |
235 | check_circular=check_circular, allow_nan=allow_nan, indent=indent, |
236 | separators=separators, encoding=encoding, default=default, |
237 | **kw).encode(obj) |
238 | |
239 | |
240 | _default_decoder = JSONDecoder(encoding=None, object_hook=None) |
241 | |
242 | |
243 | def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, |
244 | parse_int=None, parse_constant=None, **kw): |
245 | """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing |
246 | a JSON document) to a Python object. |
247 | |
248 | If the contents of ``fp`` is encoded with an ASCII based encoding other |
249 | than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must |
250 | be specified. Encodings that are not ASCII based (such as UCS-2) are |
251 | not allowed, and should be wrapped with |
252 | ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode`` |
253 | object and passed to ``loads()`` |
254 | |
255 | ``object_hook`` is an optional function that will be called with the |
256 | result of any object literal decode (a ``dict``). The return value of |
257 | ``object_hook`` will be used instead of the ``dict``. This feature |
258 | can be used to implement custom decoders (e.g. JSON-RPC class hinting). |
259 | |
260 | To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` |
261 | kwarg. |
262 | |
263 | """ |
264 | return loads(fp.read(), |
265 | encoding=encoding, cls=cls, object_hook=object_hook, |
266 | parse_float=parse_float, parse_int=parse_int, |
267 | parse_constant=parse_constant, **kw) |
268 | |
269 | |
270 | def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, |
271 | parse_int=None, parse_constant=None, **kw): |
272 | """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON |
273 | document) to a Python object. |
274 | |
275 | If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding |
276 | other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name |
277 | must be specified. Encodings that are not ASCII based (such as UCS-2) |
278 | are not allowed and should be decoded to ``unicode`` first. |
279 | |
280 | ``object_hook`` is an optional function that will be called with the |
281 | result of any object literal decode (a ``dict``). The return value of |
282 | ``object_hook`` will be used instead of the ``dict``. This feature |
283 | can be used to implement custom decoders (e.g. JSON-RPC class hinting). |
284 | |
285 | ``parse_float``, if specified, will be called with the string |
286 | of every JSON float to be decoded. By default this is equivalent to |
287 | float(num_str). This can be used to use another datatype or parser |
288 | for JSON floats (e.g. decimal.Decimal). |
289 | |
290 | ``parse_int``, if specified, will be called with the string |
291 | of every JSON int to be decoded. By default this is equivalent to |
292 | int(num_str). This can be used to use another datatype or parser |
293 | for JSON integers (e.g. float). |
294 | |
295 | ``parse_constant``, if specified, will be called with one of the |
296 | following strings: -Infinity, Infinity, NaN, null, true, false. |
297 | This can be used to raise an exception if invalid JSON numbers |
298 | are encountered. |
299 | |
300 | To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` |
301 | kwarg. |
302 | |
303 | """ |
304 | if (cls is None and encoding is None and object_hook is None and |
305 | parse_int is None and parse_float is None and |
306 | parse_constant is None and not kw): |
307 | return _default_decoder.decode(s) |
308 | if cls is None: |
309 | cls = JSONDecoder |
310 | if object_hook is not None: |
311 | kw['object_hook'] = object_hook |
312 | if parse_float is not None: |
313 | kw['parse_float'] = parse_float |
314 | if parse_int is not None: |
315 | kw['parse_int'] = parse_int |
316 | if parse_constant is not None: |
317 | kw['parse_constant'] = parse_constant |
318 | return cls(encoding=encoding, **kw).decode(s) |