json5-document

A typed JSON5 parser that preserves comments, tokens, and source spans. It requires Python 3.12 or newer and has no runtime dependencies.

Installation

pip install json5-document

Usage

"""Parse JSON5 while preserving source comments."""

import json5_document

source = "// heading\n{count: 2,}"
document = json5_document.parse(source=source)
assert document.value == {"count": 2}
assert document.comments[0].text == "// heading"
assert document.to_source() == source

Use loads(source=...) when only Python values are needed. See the documentation for the full API and parsing policies.

API reference

Typed JSON5 parsing with comments and original source spans.

class json5_document.Document(source: str, root: Node, tokens: tuple[Token, ...])

A parsed JSON5 source snapshot with every lexical token retained.

Mutating a returned Python collection does not rewrite source text. Source editing is outside the document API.

property comments: tuple[Token, ...]

Return line and block comments in source order.

root: Node
source: str
to_source() → str

Return the original source, preserving all spelling and spacing.

tokens: tuple[Token, ...]
property value: Value

Return the decoded Python value.

class json5_document.ErrorKind(*values)

Structured error categories for applications adapting diagnostics.

DEPTH = 5
DUPLICATE_KEY = 2
INTEGER_DIGITS = 4
NUMBER_RANGE = 3
SYNTAX = 1
exception json5_document.JSON5DecodeError(*, message: str, source: str, position: int, reason: ErrorKind)

A syntax or data-policy error with original source coordinates.

pos is a zero-based character offset. lineno and colno are one-based and recognize CR, LF, CRLF, U+2028, and U+2029.

colno: int
lineno: int
reason: ErrorKind
class json5_document.Node(value: Value, start: int, end: int, children: tuple[Node, ...], keys: tuple[Token, ...], commas: tuple[Token, ...])

A value and its syntax tree, retaining object keys in source order.

children contains array elements or object member values. keys is empty for arrays and scalars. Collection delimiters are included in the node’s half-open source span.

children: tuple[Node, ...]
commas: tuple[Token, ...]
end: int
keys: tuple[Token, ...]
start: int
value: Value
class json5_document.Token(kind: TokenKind, text: str, start: int, end: int, value: Scalar)

A token’s original spelling and half-open Unicode source span.

end: int
kind: TokenKind
start: int
text: str
value: Scalar
class json5_document.TokenKind(*values)

The lexical categories retained in a document.

COMMENT = 5
IDENTIFIER = 3
NUMBER = 4
PUNCTUATION = 1
STRING = 2
WHITESPACE = 6
json5_document.loads(*, source: str) → Value

Decode a JSON5 string to ordinary Python values.

json5_document.parse(*, source: str) → Document

Parse a JSON5 document, retaining tokens, comments, and source spans.

Duplicate keys and finite numbers outside binary64 range are rejected. Up to 512 nested collections are accepted. No source is executed.

json5_document.tokenize(*, source: str) → Iterator[Token]

Yield every source token, including comments and whitespace.

Lexical validity is checked; use parse to validate the complete document grammar.

Public recursive types for decoded JSON5 values.

type json5_document.types.Scalar = str | int | float | bool | None

A decoded string, number, Boolean, or null value.

type json5_document.types.Value = Scalar | list[Value] | dict[str, Value]

A decoded scalar or recursively nested JSON5 collection.