json-five

1.1.2 verified Mon Apr 27 auth: no python

A JSON5 parser and serializer for Python that supports round-trip preservation of comments, identifiers, and formatting. Current version 1.1.2, with a release cadence of a few months. Requires Python >=3.8.

pip install json-five

Common errors

error ModuleNotFoundError: No module named 'json_five' ↓

cause Incorrect import path – the package name on PyPI is 'json-five', but the module is 'json_five'.

fix

Use import json_five or from json_five import ....

error json_five.exceptions.JSON5DecodeError: ... ↓

cause Passing a bogus string that is not valid JSON5 (e.g., single-line comment syntax without proper structure).

fix

Ensure the input is valid JSON5 (use linters or test with a simple object).

error AttributeError: module 'json_five' has no attribute 'JSON5Codec' ↓

cause Trying to import JSON5Codec directly from top-level module; it is in the codec submodule.

fix

Use from json_five.codec import JSON5Codec.

Warnings

breaking In v1.0.0, support for Python 3.6 and 3.7 was dropped. Python >=3.8 is required. ↓

fix Upgrade Python to 3.8 or later.

gotcha The `loads` and `dumps` functions return plain Python objects by default, not the comment-preserving model. To preserve comments, use `JSON5Codec.decode/encode`. ↓

fix Use `json_five.codec.JSON5Codec` for round-trip comment preservation.

gotcha JSON5 identifiers (e.g. unquoted keys like `{foo: 1}`) are parsed as `JsonIdentifier` objects, which inherit from `str` since v1.0.0. Before v1.0.0, they were `UserString` subclasses, which could break code that expects `str`-only behavior. ↓

fix If you rely on `isinstance(x, str)` checks, note that `JsonIdentifier` now passes. To disable parsing of identifiers, pass `parse_json5_identifiers=False`.

deprecated The `codec` module's `loads` and `dumps` are still available but importing them from `json_five` is the recommended API. ↓

fix Use `from json_five import loads, dumps` instead of `from json_five.codec import loads, dumps`.

Imports

JSON5Codec
```
from json_five.codec import JSON5Codec
```
Main class for encoding/decoding with round-trip preservation
Node
```
from json_five.model import Node
```
Base class for the comment-preserving model
loads
wrong
```
from json_five.codec import loads
```
correct
```
from json_five import loads
```
In v1.0.0+, the top-level imports are the canonical API; codec submodule also available.

dumps

wrong

from json_five.codec import dumps

correct

from json_five import dumps

Same as loads – top-level import is preferred.

Quickstart

Basic usage: parse JSON5 string, round-trip with comments, and dump with indentation.

from json_five import loads, dumps

# Parse JSON5 string (supports comments, trailing commas, etc.)
data = '''{
  "name": "Alice",
  // This is a comment
  "age": 30,
}'''
parsed = loads(data)
print(parsed)  # {'name': 'Alice', 'age': 30}

# Round-trip with comments preserved (using codec)
from json_five.codec import JSON5Codec
codec = JSON5Codec()
obj = codec.decode(data)
print(codec.encode(obj)) # includes comments

# Dump without indentation (default)
print(dumps(parsed))  # {"name":"Alice","age":30}

# Dump with indentation
print(dumps(parsed, indent=2))