Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of 

JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data 

interchange format. 

 

:mod:`json` exposes an API familiar to users of the standard library 

:mod:`marshal` and :mod:`pickle` modules. It is the externally maintained 

version of the :mod:`json` library contained in Python 2.6, but maintains 

compatibility with Python 2.4 and Python 2.5 and (currently) has 

significant performance advantages, even without using the optional C 

extension for speedups. 

 

Encoding basic Python object hierarchies:: 

 

    >>> import json 

    >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) 

    '["foo", {"bar": ["baz", null, 1.0, 2]}]' 

    >>> print json.dumps("\"foo\bar") 

    "\"foo\bar" 

    >>> print json.dumps(u'\u1234') 

    "\u1234" 

    >>> print json.dumps('\\') 

    "\\" 

    >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) 

    {"a": 0, "b": 0, "c": 0} 

    >>> from StringIO import StringIO 

    >>> io = StringIO() 

    >>> json.dump(['streaming API'], io) 

    >>> io.getvalue() 

    '["streaming API"]' 

 

Compact encoding:: 

 

    >>> import json 

    >>> json.dumps([1,2,3,{'4': 5, '6': 7}], sort_keys=True, separators=(',',':')) 

    '[1,2,3,{"4":5,"6":7}]' 

 

Pretty printing:: 

 

    >>> import json 

    >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, 

    ...                  indent=4, separators=(',', ': ')) 

    { 

        "4": 5, 

        "6": 7 

    } 

 

Decoding JSON:: 

 

    >>> import json 

    >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] 

    >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj 

    True 

    >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' 

    True 

    >>> from StringIO import StringIO 

    >>> io = StringIO('["streaming API"]') 

    >>> json.load(io)[0] == 'streaming API' 

    True 

 

Specializing JSON object decoding:: 

 

    >>> import json 

    >>> def as_complex(dct): 

    ...     if '__complex__' in dct: 

    ...         return complex(dct['real'], dct['imag']) 

    ...     return dct 

    ... 

    >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', 

    ...     object_hook=as_complex) 

    (1+2j) 

    >>> from decimal import Decimal 

    >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1') 

    True 

 

Specializing JSON object encoding:: 

 

    >>> import json 

    >>> def encode_complex(obj): 

    ...     if isinstance(obj, complex): 

    ...         return [obj.real, obj.imag] 

    ...     raise TypeError(repr(o) + " is not JSON serializable") 

    ... 

    >>> json.dumps(2 + 1j, default=encode_complex) 

    '[2.0, 1.0]' 

    >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) 

    '[2.0, 1.0]' 

    >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) 

    '[2.0, 1.0]' 

 

 

Using json.tool from the shell to validate and pretty-print:: 

 

    $ echo '{"json":"obj"}' | python -m json.tool 

    { 

        "json": "obj" 

    } 

    $ echo '{ 1.2:3.4}' | python -m json.tool 

    Expecting property name enclosed in double quotes: line 1 column 3 (char 2) 

""" 

__version__ = '2.0.9' 

__all__ = [ 

    'dump', 'dumps', 'load', 'loads', 

    'JSONDecoder', 'JSONEncoder', 

] 

 

__author__ = 'Bob Ippolito <bob@redivi.com>' 

 

from .decoder import JSONDecoder 

from .encoder import JSONEncoder 

 

_default_encoder = JSONEncoder( 

    skipkeys=False, 

    ensure_ascii=True, 

    check_circular=True, 

    allow_nan=True, 

    indent=None, 

    separators=None, 

    encoding='utf-8', 

    default=None, 

) 

 

def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, 

        allow_nan=True, cls=None, indent=None, separators=None, 

        encoding='utf-8', default=None, sort_keys=False, **kw): 

    """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a 

    ``.write()``-supporting file-like object). 

 

    If ``skipkeys`` is true then ``dict`` keys that are not basic types 

    (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 

    will be skipped instead of raising a ``TypeError``. 

 

    If ``ensure_ascii`` is true (the default), all non-ASCII characters in the 

    output are escaped with ``\uXXXX`` sequences, and the result is a ``str`` 

    instance consisting of ASCII characters only.  If ``ensure_ascii`` is 

    ``False``, some chunks written to ``fp`` may be ``unicode`` instances. 

    This usually happens because the input contains unicode strings or the 

    ``encoding`` parameter is used. Unless ``fp.write()`` explicitly 

    understands ``unicode`` (as in ``codecs.getwriter``) this is likely to 

    cause an error. 

 

    If ``check_circular`` is false, then the circular reference check 

    for container types will be skipped and a circular reference will 

    result in an ``OverflowError`` (or worse). 

 

    If ``allow_nan`` is false, then it will be a ``ValueError`` to 

    serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) 

    in strict compliance of the JSON specification, instead of using the 

    JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 

 

    If ``indent`` is a non-negative integer, then JSON array elements and 

    object members will be pretty-printed with that indent level. An indent 

    level of 0 will only insert newlines. ``None`` is the most compact 

    representation.  Since the default item separator is ``', '``,  the 

    output might include trailing whitespace when ``indent`` is specified. 

    You can use ``separators=(',', ': ')`` to avoid this. 

 

    If ``separators`` is an ``(item_separator, dict_separator)`` tuple 

    then it will be used instead of the default ``(', ', ': ')`` separators. 

    ``(',', ':')`` is the most compact JSON representation. 

 

    ``encoding`` is the character encoding for str instances, default is UTF-8. 

 

    ``default(obj)`` is a function that should return a serializable version 

    of obj or raise TypeError. The default simply raises TypeError. 

 

    If *sort_keys* is ``True`` (default: ``False``), then the output of 

    dictionaries will be sorted by key. 

 

    To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 

    ``.default()`` method to serialize additional types), specify it with 

    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 

 

    """ 

    # cached encoder 

    if (not skipkeys and ensure_ascii and 

        check_circular and allow_nan and 

        cls is None and indent is None and separators is None and 

        encoding == 'utf-8' and default is None and not sort_keys and not kw): 

        iterable = _default_encoder.iterencode(obj) 

    else: 

        if cls is None: 

            cls = JSONEncoder 

        iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, 

            check_circular=check_circular, allow_nan=allow_nan, indent=indent, 

            separators=separators, encoding=encoding, 

            default=default, sort_keys=sort_keys, **kw).iterencode(obj) 

    # could accelerate with writelines in some versions of Python, at 

    # a debuggability cost 

    for chunk in iterable: 

        fp.write(chunk) 

 

 

def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, 

        allow_nan=True, cls=None, indent=None, separators=None, 

        encoding='utf-8', default=None, sort_keys=False, **kw): 

    """Serialize ``obj`` to a JSON formatted ``str``. 

 

    If ``skipkeys`` is false then ``dict`` keys that are not basic types 

    (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 

    will be skipped instead of raising a ``TypeError``. 

 

    If ``ensure_ascii`` is false, all non-ASCII characters are not escaped, and 

    the return value may be a ``unicode`` instance. See ``dump`` for details. 

 

    If ``check_circular`` is false, then the circular reference check 

    for container types will be skipped and a circular reference will 

    result in an ``OverflowError`` (or worse). 

 

    If ``allow_nan`` is false, then it will be a ``ValueError`` to 

    serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in 

    strict compliance of the JSON specification, instead of using the 

    JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 

 

    If ``indent`` is a non-negative integer, then JSON array elements and 

    object members will be pretty-printed with that indent level. An indent 

    level of 0 will only insert newlines. ``None`` is the most compact 

    representation.  Since the default item separator is ``', '``,  the 

    output might include trailing whitespace when ``indent`` is specified. 

    You can use ``separators=(',', ': ')`` to avoid this. 

 

    If ``separators`` is an ``(item_separator, dict_separator)`` tuple 

    then it will be used instead of the default ``(', ', ': ')`` separators. 

    ``(',', ':')`` is the most compact JSON representation. 

 

    ``encoding`` is the character encoding for str instances, default is UTF-8. 

 

    ``default(obj)`` is a function that should return a serializable version 

    of obj or raise TypeError. The default simply raises TypeError. 

 

    If *sort_keys* is ``True`` (default: ``False``), then the output of 

    dictionaries will be sorted by key. 

 

    To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 

    ``.default()`` method to serialize additional types), specify it with 

    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 

 

    """ 

    # cached encoder 

    if (not skipkeys and ensure_ascii and 

        check_circular and allow_nan and 

        cls is None and indent is None and separators is None and 

        encoding == 'utf-8' and default is None and not sort_keys and not kw): 

        return _default_encoder.encode(obj) 

    if cls is None: 

        cls = JSONEncoder 

    return cls( 

        skipkeys=skipkeys, ensure_ascii=ensure_ascii, 

        check_circular=check_circular, allow_nan=allow_nan, indent=indent, 

        separators=separators, encoding=encoding, default=default, 

        sort_keys=sort_keys, **kw).encode(obj) 

 

 

_default_decoder = JSONDecoder(encoding=None, object_hook=None, 

                               object_pairs_hook=None) 

 

 

def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, 

        parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 

    """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing 

    a JSON document) to a Python object. 

 

    If the contents of ``fp`` is encoded with an ASCII based encoding other 

    than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must 

    be specified. Encodings that are not ASCII based (such as UCS-2) are 

    not allowed, and should be wrapped with 

    ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode`` 

    object and passed to ``loads()`` 

 

    ``object_hook`` is an optional function that will be called with the 

    result of any object literal decode (a ``dict``). The return value of 

    ``object_hook`` will be used instead of the ``dict``. This feature 

    can be used to implement custom decoders (e.g. JSON-RPC class hinting). 

 

    ``object_pairs_hook`` is an optional function that will be called with the 

    result of any object literal decoded with an ordered list of pairs.  The 

    return value of ``object_pairs_hook`` will be used instead of the ``dict``. 

    This feature can be used to implement custom decoders that rely on the 

    order that the key and value pairs are decoded (for example, 

    collections.OrderedDict will remember the order of insertion). If 

    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 

 

    To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 

    kwarg; otherwise ``JSONDecoder`` is used. 

 

    """ 

    return loads(fp.read(), 

        encoding=encoding, cls=cls, object_hook=object_hook, 

        parse_float=parse_float, parse_int=parse_int, 

        parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, 

        **kw) 

 

 

def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, 

        parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 

    """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON 

    document) to a Python object. 

 

    If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding 

    other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name 

    must be specified. Encodings that are not ASCII based (such as UCS-2) 

    are not allowed and should be decoded to ``unicode`` first. 

 

    ``object_hook`` is an optional function that will be called with the 

    result of any object literal decode (a ``dict``). The return value of 

    ``object_hook`` will be used instead of the ``dict``. This feature 

    can be used to implement custom decoders (e.g. JSON-RPC class hinting). 

 

    ``object_pairs_hook`` is an optional function that will be called with the 

    result of any object literal decoded with an ordered list of pairs.  The 

    return value of ``object_pairs_hook`` will be used instead of the ``dict``. 

    This feature can be used to implement custom decoders that rely on the 

    order that the key and value pairs are decoded (for example, 

    collections.OrderedDict will remember the order of insertion). If 

    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 

 

    ``parse_float``, if specified, will be called with the string 

    of every JSON float to be decoded. By default this is equivalent to 

    float(num_str). This can be used to use another datatype or parser 

    for JSON floats (e.g. decimal.Decimal). 

 

    ``parse_int``, if specified, will be called with the string 

    of every JSON int to be decoded. By default this is equivalent to 

    int(num_str). This can be used to use another datatype or parser 

    for JSON integers (e.g. float). 

 

    ``parse_constant``, if specified, will be called with one of the 

    following strings: -Infinity, Infinity, NaN, null, true, false. 

    This can be used to raise an exception if invalid JSON numbers 

    are encountered. 

 

    To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 

    kwarg; otherwise ``JSONDecoder`` is used. 

 

    """ 

    if (cls is None and encoding is None and object_hook is None and 

            parse_int is None and parse_float is None and 

            parse_constant is None and object_pairs_hook is None and not kw): 

        return _default_decoder.decode(s) 

    if cls is None: 

        cls = JSONDecoder 

    if object_hook is not None: 

        kw['object_hook'] = object_hook 

    if object_pairs_hook is not None: 

        kw['object_pairs_hook'] = object_pairs_hook 

    if parse_float is not None: 

        kw['parse_float'] = parse_float 

    if parse_int is not None: 

        kw['parse_int'] = parse_int 

    if parse_constant is not None: 

        kw['parse_constant'] = parse_constant 

    return cls(encoding=encoding, **kw).decode(s)