JSON in Python

Python's standard library has a json module with the same four jobs as JavaScript's two functions: text to values, values to text, and the same for files. Its defaults differ from JavaScript's in ways that matter: it adds spaces, it escapes non-ASCII characters, it accepts NaN, and it turns tuples and integer keys into things that do not come back the same. This chapter walks through the module, shows what survives a round trip and what does not (measured), then covers hooks for dates, Decimal and dataclasses, and the one place Python bites on Windows: reading and writing files without saying which encoding. It builds on Working with JSON 1 (the format's rules) and Working with JSON 2 (the JavaScript side to compare with); basic Python comes from Python Fundamentals.

The Four Functions

The "s" in loads and dumps stands for string, a common source of confusion with load and dump, which take files. I round-tripped a dictionary:

Notice what changed on the way: True became true and None became null, and there is a space after every : and ,. JavaScript's stringify prints {"a":1} with no spaces. Both are valid JSON; the difference only matters for size and for tests that compare strings. The loads function also accepts bytes: I passed UTF-8 bytes and UTF-16 bytes and it detected each encoding and parsed both.

Formatting Options for dumps

• indent: a number of spaces or a string (I tried '\t' for tabs). With indent=0 you still get newlines, one item per line, but no indentation.
• sort_keys=True: keys in alphabetical order, which makes output stable for diffs and tests. Unlike JavaScript, Python keeps insertion order by default and never reorders numeric-looking keys.
• ensure_ascii: True (the default) turns every non-ASCII character into \uXXXX, with a surrogate pair for 😀 (\ud83d\ude00). The output is pure ASCII, safe in any file or pipe, but unreadable for non-English text and about 6 characters per accented letter. False keeps the characters, and then you must write the result in UTF-8 (see the file section).
• separators: a pair (item_separator, key_separator). The default is (', ', ': ') normally and (',', ': ') when indent is set (so no trailing spaces at line ends). (',', ':') is the compact form.

Comparing the two languages' floats on the same numbers, I found Python and JavaScript mostly agree but not always in how they write them: 1e-7 is 1e-07 in Python and 1e-7 in JavaScript; 1.0 stays 1.0 in Python but is 1 in JavaScript; 1e16 is 1e+16 in Python and 10000000000000000 in JavaScript. All of these are valid JSON and parse to the same numbers.

The Type Mapping, and What Does Not Round-Trip

Everything not in the right-hand column raises TypeError. I ran each of these through dumps then loads and compared with the original:

Three results deserve attention. Tuples come back as lists and every non-string key comes back as a string, so a dictionary keyed by integers is not the same dictionary after a round trip. Worse, the key collision case produced invalid-looking output: {1: 'int', '1': 'str'} became {"1": "int", "1": "str"}, with a duplicate key, and reading it back kept only the last. Python had two different keys, JSON has one. Nothing raised an error. The other failures are loud: TypeError: Object of type set is not JSON serializable (the same message for datetime, bytes, complex and plain objects), and TypeError: keys must be str, int, float, bool or None, not tuple for a tuple key. skipkeys=True silently drops such keys, which is rarely what you want.

A circular dictionary raised ValueError: Circular reference detected, the counterpart of the JavaScript error from Chapter 2. Python integers have no size limit, so 10**20 round-trips exactly, unlike in JavaScript. There is one limit, though, added to Python for safety: converting a very long digit string to an int is capped. I parsed a 4,300-digit number fine, and a 4,301-digit one failed with ValueError: Exceeds the limit (4300 digits) for integer string conversion (the limit is sys.get_int_max_str_digits()). Ordinary data never gets near it, but an attacker's input can, which is why the limit exists.

Teaching dumps New Types: default=

A default function is called for every object the encoder does not know. It should return something the encoder does know, or raise TypeError. Here is one that handles the types most programs have, tested on a dictionary holding every one of them at once:

Details worth knowing. dataclasses.asdict converts nested dataclasses for you, and then default is called again for the Decimal and date inside. A set has no order, so sort it to make the output repeatable. pathlib paths, uuid.UUID and enum.Enum values work the same way: I tested PurePosixPath('/tmp/x') (via .as_posix()), a UUID (via str) and an Enum (via .value) with a similar function and each produced a plain string. If you prefer a class, subclass json.JSONEncoder, override its default method, and pass cls=MyEncoder; I confirmed that gave the same output.

Teaching loads New Types: Hooks

Python has four hooks on loads. object_hook is called with each decoded dictionary, innermost first (like the JavaScript reviver). I logged the order for {"a":{"b":{}}, "c":[{"d":1}]}: the hook saw [] (the innermost empty object), then ['b'], then ['d'], then ['a', 'c'], the outermost, last.

The hook rebuilt the datetime, the date and the Decimal, and the comparison with the original was True. Like the JavaScript reviver, it matches by key name: a string such as "2026-10-12 is a date" under another key was left alone in my test, but any key called price at any depth is converted. The tags set came back as a list, because JSON has no way to say "this array is a set"; convert it yourself if you need one.

The other three hooks, all measured:

• parse_float=Decimal: every number with a fraction or exponent is created with that function. sum(json.loads('[0.1,0.2]', parse_float=Decimal)) gave 0.3, and without it 0.30000000000000004. This is the way to read money from JSON as numbers without any rounding error. (parse_int works the same way for integers; parse_int=str turned 1 and 3 into strings and left 2.0 a float.)
• parse_constant: called for NaN, Infinity and -Infinity. Raising inside it rejects them (next section).
• object_pairs_hook: called with the list of (key, value) pairs before they become a dictionary, so it can see duplicates. json.loads('{"a":1,"a":2}') normally returned {'a': 2}, but a small hook that raises on a repeated key made it fail with duplicate key: 'a', and the same hook accepted clean input. Passing object_pairs_hook=list returned the pairs themselves in file order.

NaN and Infinity: Python's Extension

As Chapter 1 showed, Python accepts NaN, Infinity and -Infinity by default, and writes them too: json.dumps([float('nan'), float('inf'), -float('inf')]) gave [NaN, Infinity, -Infinity], which no standard-conforming parser (including JavaScript's) will read. To keep your output portable, switch it off in both directions:

allow_nan=False makes dumps raise instead of writing invalid JSON; for loads, the way to refuse is parse_constant. Note that 1e400, which is a legal JSON number, still parses to inf, so a value can become infinite without the word appearing. If you must handle NaN in your data, decide on a replacement (usually null) and convert before writing.

Reading Errors: JSONDecodeError

Bad input raises json.JSONDecodeError, a subclass of ValueError, so catching ValueError catches it too. It carries the details as attributes. For '{"a": 1,\n "b": }' I read:

pos is a character offset into doc (the original text), counted from 0; lineno and colno count from 1. They are what Chapter 1's exercise used to put a caret under the error. Keep in mind that the 4,301-digit failure above is a plain ValueError, not a JSONDecodeError.

Files, Encodings and Line Endings (Where Windows Bites)

json.load and json.dump work on files you open yourself, which means the encoding is chosen by open(), not by the json module. On this machine locale.getpreferredencoding(False) is cp1252, and the results are instructive. I wrote a file containing Zoë and 😀 in UTF-8, then read it back several ways:

The dangerous row is the second: reading UTF-8 JSON with the wrong encoding does not fail, it quietly produces garbage. The cure is to always write encoding='utf-8' in open(), which RFC 8259 also requires for JSON exchanged between systems. The default ensure_ascii=True is the reason many programs have never seen the problem: ASCII-only output reads the same in every encoding. The same file written with CRLF line endings is still valid JSON (newlines are whitespace), but it produces noisy diffs in a Git repository that expects LF.

The Command Line: python -m json.tool

The module can be run as a tool to check and format a file (as in Chapter 1). Python 3.14's options, from its --help, and my run of each on {"b":1,"a":{"z":"é"}}:

The help also lists --no-indent and --json-lines (parse JSON Lines input); I did not run those two, and I did not test older Pythons, which may offer fewer options.

Side by Side with JavaScript

Faster Third-Party Libraries (Names Only)

The standard module is fast enough for most work. Libraries that advertise being faster exist; three that are widely used are orjson, ujson and msgspec. I looked up their latest versions on PyPI today (orjson 3.13.0, ujson 6.0.0, msgspec 0.22.0) but did not install, test or time any of them, so this chapter makes no speed claim and no claim about how they differ from json on the edge cases above. Measure on your own data before switching, and run this chapter's round-trip table against any replacement, since libraries make different choices about big integers, NaN and key types.

Hands-On Exercises