circuitpython/docs/library/json.rst

:mod:`json` -- JSON encoding and decoding
=========================================

.. module:: json
   :synopsis: JSON encoding and decoding

|see_cpython_module| :mod:`python:json`.

This modules allows to convert between Python objects and the JSON
data format.

Functions
---------

.. function:: dump(obj, stream, separators=None)

   Serialise ``obj`` to a JSON string, writing it to the given *stream*.

   If specified, separators should be an ``(item_separator, key_separator)``
   tuple. The default is ``(', ', ': ')``. To get the most compact JSON
   representation, you should specify ``(',', ':')`` to eliminate whitespace.

.. function:: dumps(obj, separators=None)

   Return ``obj`` represented as a JSON string.

   The arguments have the same meaning as in `dump`.

.. function:: load(stream)

   Parse the given ``stream``, interpreting it as a JSON string and
   deserialising the data to a Python object.  The resulting object is
   returned.

   Parsing continues until end-of-file is encountered.
   A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed.

.. function:: loads(str)

   Parse the JSON *str* and return an object.  Raises :exc:`ValueError` if the
   string is not correctly formed.
CIRCUITPY_* switches for JSON, RE, etc. Doc cleanup 2021-01-24 22:49:28 -05:00			:mod:`json` -- JSON encoding and decoding
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com> 2021-08-12 13:59:29 +10:00			`=========================================`
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00
CIRCUITPY_* switches for JSON, RE, etc. Doc cleanup 2021-01-24 22:49:28 -05:00			`.. module:: json`
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00			`:synopsis: JSON encoding and decoding`

docs/library: Add CPython docs xref to each pertinent module. Cross-reference text/link is implemented as RST substitution, so easy to consistently. 2017-07-02 15:37:31 +03:00			\|see_cpython_module\| :mod:`python:json`.

docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00			`This modules allows to convert between Python objects and the JSON`
			`data format.`

			`Functions`
			`---------`

extmod/modujson: Add support for dump/dumps separators keyword-argument. Optionally enabled via MICROPY_PY_UJSON_SEPARATORS. Enabled by default. For dump, make sure mp_get_stream_raise is called after mod_ujson_separators since CPython does it in this order (if both separators and stream are invalid, separators will raise an exception first). Add separators argument in the docs as well. Signed-off-by: Peter Züger <zueger.peter@icloud.com> Signed-off-by: Damien George <damien@micropython.org> 2021-02-03 09:24:25 +01:00			`.. function:: dump(obj, stream, separators=None)`
docs/library/ujson: Document dump() and load() functions. 2018-02-06 15:48:24 +11:00
WIP: complete manual inspection of all significant changes 2018-07-23 21:34:25 -04:00			Serialise ``obj`` to a JSON string, writing it to the given stream.
docs/library/ujson: Document dump() and load() functions. 2018-02-06 15:48:24 +11:00
extmod/modujson: Add support for dump/dumps separators keyword-argument. Optionally enabled via MICROPY_PY_UJSON_SEPARATORS. Enabled by default. For dump, make sure mp_get_stream_raise is called after mod_ujson_separators since CPython does it in this order (if both separators and stream are invalid, separators will raise an exception first). Add separators argument in the docs as well. Signed-off-by: Peter Züger <zueger.peter@icloud.com> Signed-off-by: Damien George <damien@micropython.org> 2021-02-03 09:24:25 +01:00			If specified, separators should be an ``(item_separator, key_separator)``
			tuple. The default is ``(', ', ': ')``. To get the most compact JSON
			representation, you should specify ``(',', ':')`` to eliminate whitespace.

			`.. function:: dumps(obj, separators=None)`
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00
WIP: complete manual inspection of all significant changes 2018-07-23 21:34:25 -04:00			Return ``obj`` represented as a JSON string.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00
extmod/modujson: Add support for dump/dumps separators keyword-argument. Optionally enabled via MICROPY_PY_UJSON_SEPARATORS. Enabled by default. For dump, make sure mp_get_stream_raise is called after mod_ujson_separators since CPython does it in this order (if both separators and stream are invalid, separators will raise an exception first). Add separators argument in the docs as well. Signed-off-by: Peter Züger <zueger.peter@icloud.com> Signed-off-by: Damien George <damien@micropython.org> 2021-02-03 09:24:25 +01:00			The arguments have the same meaning as in `dump`.

docs/library/ujson: Document dump() and load() functions. 2018-02-06 15:48:24 +11:00			`.. function:: load(stream)`

WIP: complete manual inspection of all significant changes 2018-07-23 21:34:25 -04:00			Parse the given ``stream``, interpreting it as a JSON string and
docs/library/ujson: Document dump() and load() functions. 2018-02-06 15:48:24 +11:00			`deserialising the data to a Python object. The resulting object is`
			`returned.`

			`Parsing continues until end-of-file is encountered.`
WIP: complete manual inspection of all significant changes 2018-07-23 21:34:25 -04:00			A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00
			`.. function:: loads(str)`

docs/library/ujson: Update to conform with docs conventions. The formatting of exception objects is done as per CPython conventions, eg: :exc:`TypeError` 2018-02-15 11:31:34 +11:00			Parse the JSON str and return an object. Raises :exc:`ValueError` if the
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory. 2014-10-31 01:37:19 +00:00			`string is not correctly formed.`