Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(18350)

Side by Side Diff: Doc/library/json.rst

Issue 19361: Specialize exceptions thrown by JSON parser
Patch Set: Created 4 years, 9 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Lib/json/decoder.py » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`json` --- JSON encoder and decoder 1 :mod:`json` --- JSON encoder and decoder
2 ======================================== 2 ========================================
3 3
4 .. module:: json 4 .. module:: json
5 :synopsis: Encode and decode the JSON format. 5 :synopsis: Encode and decode the JSON format.
6 .. moduleauthor:: Bob Ippolito <bob@redivi.com> 6 .. moduleauthor:: Bob Ippolito <bob@redivi.com>
7 .. sectionauthor:: Bob Ippolito <bob@redivi.com> 7 .. sectionauthor:: Bob Ippolito <bob@redivi.com>
8 8
9 `JSON (JavaScript Object Notation) <http://json.org>`_, specified by 9 `JSON (JavaScript Object Notation) <http://json.org>`_, specified by
10 :rfc:`7159` (which obsoletes :rfc:`4627`) and by 10 :rfc:`7159` (which obsoletes :rfc:`4627`) and by
(...skipping 232 matching lines...) Expand 10 before | Expand all | Expand 10 after
243 are encountered. 243 are encountered.
244 244
245 .. versionchanged:: 3.1 245 .. versionchanged:: 3.1
246 *parse_constant* doesn't get called on 'null', 'true', 'false' anymore. 246 *parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
247 247
248 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls`` 248 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
249 kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments 249 kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments
250 will be passed to the constructor of the class. 250 will be passed to the constructor of the class.
251 251
252 If the data being deserialized is not a valid JSON document, a 252 If the data being deserialized is not a valid JSON document, a
253 :exc:`ValueError` will be raised. 253 :exc:`JSONDecodeError` will be raised.
254 254
255 .. function:: loads(s, encoding=None, cls=None, object_hook=None, parse_float=No ne, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) 255 .. function:: loads(s, encoding=None, cls=None, object_hook=None, parse_float=No ne, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
256 256
257 Deserialize *s* (a :class:`str` instance containing a JSON document) to a 257 Deserialize *s* (a :class:`str` instance containing a JSON document) to a
258 Python object using this :ref:`conversion table <json-to-py-table>`. 258 Python object using this :ref:`conversion table <json-to-py-table>`.
259 259
260 The other arguments have the same meaning as in :func:`load`, except 260 The other arguments have the same meaning as in :func:`load`, except
261 *encoding* which is ignored and deprecated. 261 *encoding* which is ignored and deprecated.
262 262
263 If the data being deserialized is not a valid JSON document, a 263 If the data being deserialized is not a valid JSON document, a
264 :exc:`ValueError` will be raised. 264 :exc:`JSONDecodeError` will be raised.
265 265
266 Encoders and Decoders 266 Encoders and Decoders
267 --------------------- 267 ---------------------
268 268
269 .. class:: JSONDecoder(object_hook=None, parse_float=None, parse_int=None, parse _constant=None, strict=True, object_pairs_hook=None) 269 .. class:: JSONDecoder(object_hook=None, parse_float=None, parse_int=None, parse _constant=None, strict=True, object_pairs_hook=None)
270 270
271 Simple JSON decoder. 271 Simple JSON decoder.
272 272
273 Performs the following translations in decoding by default: 273 Performs the following translations in decoding by default:
274 274
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after
327 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``, 327 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``,
328 ``'false'``. This can be used to raise an exception if invalid JSON numbers 328 ``'false'``. This can be used to raise an exception if invalid JSON numbers
329 are encountered. 329 are encountered.
330 330
331 If *strict* is ``False`` (``True`` is the default), then control characters 331 If *strict* is ``False`` (``True`` is the default), then control characters
332 will be allowed inside strings. Control characters in this context are 332 will be allowed inside strings. Control characters in this context are
333 those with character codes in the 0-31 range, including ``'\t'`` (tab), 333 those with character codes in the 0-31 range, including ``'\t'`` (tab),
334 ``'\n'``, ``'\r'`` and ``'\0'``. 334 ``'\n'``, ``'\r'`` and ``'\0'``.
335 335
336 If the data being deserialized is not a valid JSON document, a 336 If the data being deserialized is not a valid JSON document, a
337 :exc:`ValueError` will be raised. 337 :exc:`JSONDecodeError` will be raised.
338 338
339 .. method:: decode(s) 339 .. method:: decode(s)
340 340
341 Return the Python representation of *s* (a :class:`str` instance 341 Return the Python representation of *s* (a :class:`str` instance
342 containing a JSON document) 342 containing a JSON document)
343 343
344 :exc:`JSONDecodeError` will be raised if the given JSON document is not
345 valid.
346
344 .. method:: raw_decode(s) 347 .. method:: raw_decode(s)
345 348
346 Decode a JSON document from *s* (a :class:`str` beginning with a 349 Decode a JSON document from *s* (a :class:`str` beginning with a
347 JSON document) and return a 2-tuple of the Python representation 350 JSON document) and return a 2-tuple of the Python representation
348 and the index in *s* where the document ended. 351 and the index in *s* where the document ended.
349 352
350 This can be used to decode a JSON document from a string that may have 353 This can be used to decode a JSON document from a string that may have
351 extraneous data at the end. 354 extraneous data at the end.
352 355
353 356
(...skipping 106 matching lines...) Expand 10 before | Expand all | Expand 10 after
460 '{"foo": ["bar", "baz"]}' 463 '{"foo": ["bar", "baz"]}'
461 464
462 465
463 .. method:: iterencode(o) 466 .. method:: iterencode(o)
464 467
465 Encode the given object, *o*, and yield each string representation as 468 Encode the given object, *o*, and yield each string representation as
466 available. For example:: 469 available. For example::
467 470
468 for chunk in json.JSONEncoder().iterencode(bigobject): 471 for chunk in json.JSONEncoder().iterencode(bigobject):
469 mysocket.write(chunk) 472 mysocket.write(chunk)
473
474
475 Exceptions
476 ----------
477
478 .. exception:: JSONDecodeError(msg, doc, pos, end=None)
479
480 Subclass of :exc:`ValueError` with the following additional attributes:
481
482 .. attribute:: msg
483
484 The unformatted error message.
485
486 .. attribute:: doc
487
488 The JSON document being parsed.
489
490 .. attribute:: pos
491
492 The start index of *doc* where parsing failed.
493
494 .. attribute:: lineno
495
496 The line corresponding to *pos*.
497
498 .. attribute:: colno
499
500 The column corresponding to *pos*.
501
502 .. versionadded:: 3.5
470 503
471 504
472 Standard Compliance and Interoperability 505 Standard Compliance and Interoperability
473 ---------------------------------------- 506 ----------------------------------------
474 507
475 The JSON format is specified by :rfc:`7159` and by 508 The JSON format is specified by :rfc:`7159` and by
476 `ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm >`_. 509 `ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm >`_.
477 This section details this module's level of compliance with the RFC. 510 This section details this module's level of compliance with the RFC.
478 For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and 511 For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and
479 parameters other than those explicitly mentioned, are not considered. 512 parameters other than those explicitly mentioned, are not considered.
(...skipping 173 matching lines...) Expand 10 before | Expand all | Expand 10 after
653 Show the help message. 686 Show the help message.
654 687
655 688
656 .. rubric:: Footnotes 689 .. rubric:: Footnotes
657 690
658 .. [#rfc-errata] As noted in `the errata for RFC 7159 691 .. [#rfc-errata] As noted in `the errata for RFC 7159
659 <http://www.rfc-editor.org/errata_search.php?rfc=7159>`_, 692 <http://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
660 JSON permits literal U+2028 (LINE SEPARATOR) and 693 JSON permits literal U+2028 (LINE SEPARATOR) and
661 U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript 694 U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
662 (as of ECMAScript Edition 5.1) does not. 695 (as of ECMAScript Edition 5.1) does not.
OLDNEW
« no previous file with comments | « no previous file | Lib/json/decoder.py » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+