pyjson5

pyjson5 is a Python implementation of the JSON5 data format. JSON5 extends the standard JSON format to make it more suitable for configuration files by allowing:

• JavaScript-style comments (both single and multi-line).
• Unquoted object keys (if they are legal ECMAScript identifiers).
• Trailing commas in objects and arrays.
• Single-quoted strings and multi-line string literals.

Note: This library is designed specifically for JSON5 documents and does not support arbitrary JavaScript (e.g., bare integers as object keys are not supported).

The pyjson5 API mirrors the standard Python json module for ease of use, but has several key differences:

Duplicate Key Detection

Unlike the standard json module, load() and loads() support an optional check for duplicate object keys. By default, duplicates are allowed. To reject them, pass allow_duplicate_keys=False.

Unsupported Arguments

• cls in load()/loads(): Not supported. This implementation does not use a JSONDecoder class.
• cls in dump()/dumps(): Not supported.
• encoding in dump(): Ignored. Unicode strings are always returned.

Supported Arguments

• default in dump()/dumps(): Supported and can be used as a workaround for custom object serialization.

The benchmarks/ directory contains a command-line program designed to compare the performance of the pyjson5 decoder against the standard Python built-in json decoder.

Note that performance results vary by hardware. On a 2018 Mac Mini (3 GHz 6 Core Intel Core i5, 64 GB RAM, MacOS 14.2.1), JSON5 was observed to be 800-1200x slower than the built-in JSON decoder.

This library is an early release and is significantly slower than optimized JSON libraries:

• It can be 1000-6000x slower than the C-optimized json module.
• It can be 200x slower (or more) than the pure Python json module.

When using load() or loads(), you can control whether duplicate keys in a single dictionary are permitted using the allow_duplicate_keys parameter.

• True (default): Allows duplicate keys.
• False: Rejects objects containing duplicate keys.

You can control how strings are encoded by default using the quote_style argument in dump() and dumps(). This is also available via the --quote-style flag when using the python -m json5 CLI tool.

Supported styles:

• QuoteStyle.ALWAYS_DOUBLE: Encodes all strings with double quotes (default, for compatibility).
• QuoteStyle.ALWAYS_SINGLE: Encodes all strings with single quotes.
• QuoteStyle.PREFER_SINGLE: Switches to single quotes when it eliminates the need to escape quotes.
• QuoteStyle.PREFER_DOUBLE: Switches to double quotes when it eliminates the need to escape quotes.

In versions v0.7 and later, dump() and dumps() have specific behaviors for formatting:

• Key Quoting: By default, object keys are not quoted if they are legal identifiers. To always quote keys, pass quote_keys=True.
• Trailing Commas: By default, trailing commas are inserted after the last item in an array or object if the output is printed across multiple lines (i.e., indent is not None). To disable this, pass trailing_commas=False.

The load(), loads(), and parse() methods support two additional parameters to control the parsing process:

• consume_trailing: A boolean specifying whether to keep parsing after a valid object is reached.
  • If True (default): The string must only contain trailing whitespace after the valid object.
  • If False: Parsing stops immediately once a valid object is reached.
• start: A zero-based integer offset specifying where to begin parsing the string or file.

You can use the json5.tool command line interface to process JSON5 files.

Available flags:

• --as-json: Output as standard JSON.
• --indent <int>: Set indentation level.
• --[no-]quote-keys: Control whether object keys are quoted.
• --[no-]trailing-commas: Control whether trailing commas are included.
• --quote-style <style>: Control the default string quoting style.

The main function can be called programmatically to execute the JSON5 processing logic. It accepts argv (a list of arguments) and an optional host object. The host object is responsible for I/O operations like reading files/stdin and printing to stdout/stderr.

from json5.tool import main
from json5.host import Host

# Execute the tool logic with a custom host
host = Host()
main(argv=['--as-json', 'my_file.json5'], host=host)