JSON with the json Module

## Four names, two jobs The `json` module exposes its work through four top-level callables, and the whole naming scheme rests on one letter. `load` and `loads` **decode**: JSON text in, Python objects out. `dump` and `dumps` **encode**: Python objects in, JSON text out. The trailing `s` on `loads` and `dumps` stands for **string** — those are the in-memory variants. The two names without the `s` are the file-object variants. Candidates routinely misread the `s` as "stream", which inverts the whole API in their head, so it is worth fixing the mnemonic early. ## The decode side `json.loads(text)` accepts a `str` and returns the corresponding Python object graph. It also accepts `bytes` and `bytearray` directly, autodetecting UTF-8, UTF-16 or UTF-32 from the leading bytes, which is why you can hand it a response body without decoding it yourself. `json.load(fp)` accepts a **file object** — anything with a `.read()` method, which includes a file returned by `open()`, an `io.StringIO`, an `io.BytesIO`, or a network stream wrapper. It calls `fp.read()` once and then does exactly what `loads` does. Passing a *filename* is the classic beginner error: `json.load("data.json")` raises `AttributeError: 'str' object has no attribute 'read'`, because a `str` has no `.read()`. Open the file first, or read the text yourself and call `loads`. ## The encode side `json.dumps(obj)` returns a `str` of JSON text — never `bytes`. `json.dump(obj, fp)` serializes and calls `fp.write(...)` with the resulting text; it returns `None`. Note the argument order: the object comes first, the destination second. Writing `json.dump(fp, obj)` is a frequent slip and usually fails with a confusing serialization error about the file object. Because `json.dump` writes `str`, it never chooses an encoding itself. The bytes on disk are decided by the file you opened: ```python import json from pathlib import Path with open("digest.json", "w", encoding="utf-8") as fp: json.dump({"sent": 4}, fp) print(json.loads(Path("digest.json").read_text(encoding="utf-8"))) ``` Relying on the platform default encoding is how a file that reads fine on one machine becomes mojibake on another; pass `encoding="utf-8"` explicitly. If you genuinely need bytes, encode the result of `dumps` yourself: `json.dumps(obj).encode("utf-8")`. ## Formatting knobs are shared All the presentation options belong to the encoder, so `dump` and `dumps` accept the same keywords: `indent` for pretty-printing (an integer or a string), `sort_keys=True` for deterministic key order, `separators` to strip whitespace for the most compact possible output, and `ensure_ascii` (default `True`) which escapes every non-ASCII character as a `\uXXXX` sequence. Setting `ensure_ascii=False` keeps the characters literal, which is smaller and far more readable for non-English text — as long as the file is actually written as UTF-8. ## What the file variants do *not* do The most common wrong assumption at this level is that `json.load` streams. It does not. It reads the entire document and builds the entire Python object graph before returning, so a 2 GB file needs the file's bytes plus the parsed structure in memory at once. `json.dump` is slightly better on the write side — it writes incrementally through the encoder's chunk iterator rather than building one giant string — but the object graph is still fully in memory before you call it. When documents outgrow RAM, the answer is a different shape entirely: newline-delimited records parsed one line at a time with `loads`, or a pull parser, not a different member of this family. ## Round trip in practice The read-modify-write pattern is three lines and worth being able to type from memory: ```python import json with open("config.json", encoding="utf-8") as fp: config = json.load(fp) config["recipients"] = 4 with open("config.json", "w", encoding="utf-8") as fp: json.dump(config, fp, indent=2, sort_keys=True) ``` One anti-pattern to name: `fp.write(json.dumps(obj))` is not wrong, merely redundant — that is precisely what `json.dump` does. The reverse mistake, `json.dump(json.dumps(obj), fp)`, double-encodes and produces a JSON *string* containing JSON text, which the consumer then has to parse twice. ## From the shell The module ships a command line for exactly this: `python -m json --indent 2 file.json` on Python 3.14, and `python -m json.tool`, which has existed far longer and still works. Both parse and re-emit the document, so they double as a fast syntax check on a file you were handed.