5.28. JSON¶

JSON (JavaScript Object Notation) is a compact, human-readable text format for structured data. It defines six types – string, number, boolean, null, array, and object – each of which maps directly onto a Python value, so converting between Python and JSON is a single function call in either direction.

JSON is the lingua franca of config files and web APIs. Reach for it whenever you need to save a small bundle of settings to disk in a form you can also read by eye, or to exchange structured data with another program.

Two functions cover most needs:

json.dumps() – dump string: turn a Python value into a JSON string.
json.loads() – load string: parse a JSON string back into Python.

The pair json.dump / json.load (no s) does the same job but takes a file object directly.

5.28.1. Encoding (dumps)¶

import json

config = {
    "name":  "OpenMV",
    "width": 320,
    "tags":  ["red", "round"],
}

text = json.dumps(config)
print(text)

Output:

{"name": "OpenMV", "width": 320, "tags": ["red", "round"]}

The mapping is:

dict (string keys) → JSON object.
list and tuple → JSON array.
str → JSON string.
int, float → JSON number.
True, False, None → true, false, null.

Anything outside that set (a custom class, a bytes buffer, a set) raises TypeError. Convert the value first.

Note

CPython’s json.dumps() accepts an indent argument for pretty-printed output; MicroPython’s does not. The only formatting knob is separators, which controls the in-line spacing – pass (',', ':') for the most compact form. Multi-line, indented output has to be produced by hand if needed.

5.28.2. Decoding (loads)¶

text = '{"name": "OpenMV", "width": 320}'
config = json.loads(text)
print(config["name"], config["width"])

Output:

OpenMV 320

JSON objects become dict, arrays become list, and the rest map back to their Python equivalents. Bad JSON raises ValueError.

5.28.3. Reading and writing files¶

The file-based pair plays nicely with with:

import json

with open("config.json") as f:
    config = json.load(f)

config["width"] = 640

with open("config.json", "w") as f:
    json.dump(config, f)

Treat the JSON file as a complete record – read it in, modify the Python value, write it back. Trying to edit JSON in place inside a file usually creates more bugs than it saves.