JSON5 for Python

Common errors

• ModuleNotFoundError: No module named 'json5'

  cause The `json5` Python package is not installed in the current environment.
  fix Install the `json5` library using pip: `pip install json5`.

• json5.json5.Json5DecodeError: Unexpected token

  cause The input JSON5 string contains a syntax error that even the more lenient JSON5 parser cannot handle, such as a malformed structure, an invalid unquoted key, or an unexpected character.
  fix Review the JSON5 string for syntax errors. Ensure that unquoted keys are valid JavaScript identifiers, and check for missing commas, unclosed strings, or other structural issues.

• json5.json5.Json5DecodeError: Invalid control character at: line X column Y (char Z)

  cause The JSON5 input string contains unescaped control characters (e.g., raw newline, tab, or carriage return characters) within a string literal that must be escaped.
  fix Replace unescaped control characters within string literals with their corresponding JSON escape sequences (e.g., `\n` for newline, `\t` for tab, `\r` for carriage return).

Warnings

• gotcha Performance Warning: `json5` is significantly slower than Python's built-in `json` module (especially the C-optimized version). It can be 1000-6000x slower for parsing and 200x slower than the pure Python `json` module. Consider performance implications for high-throughput applications.
  Fix: For performance-critical scenarios, process JSON5 during development/configuration loading and convert to standard JSON for runtime if possible, or use the `json` module if JSON5 features are not strictly needed.
• breaking Unsupported `cls` argument: The `cls` keyword argument, commonly used in `json.load()`, `json.loads()`, `json.dump()`, and `json.dumps()` for custom `JSONDecoder` or `JSONEncoder` subclasses, is not supported by `json5` due to a different parsing approach.
  Fix: Custom deserialization/serialization logic needs to be implemented externally or by using `object_hook` and `default` arguments, which *are* supported, if applicable. Direct subclassing of internal `json5` classes is not an option.
• gotcha Encoding in `dump()` is ignored: The `encoding` method to `dump()` is ignored, and unicode strings are always returned. This differs from the behavior of the standard `json` module.
  Fix: Be aware that `dump()` will always produce Unicode output. Handle encoding to specific byte streams explicitly after getting the Unicode string if non-UTF-8 output is required.
• gotcha Duplicate keys handling: By default, `json5.load()` and `json5.loads()` allow duplicate object keys, with the last key-value pair taking precedence (standard JSON behavior). However, you can explicitly reject duplicates by passing `allow_duplicate_keys=False`. This is a notable difference in explicit control compared to the standard `json` module.
  Fix: To enforce uniqueness of keys in parsed JSON5 documents, use `json5.loads(data, allow_duplicate_keys=False)` or `json5.load(file, allow_duplicate_keys=False)`.
• gotcha Not a full JavaScript parser: The `json5` library is designed to parse JSON5 documents, not arbitrary JavaScript code. Attempting to parse non-JSON5 JavaScript syntax (e.g., bare integers as object keys, or complex expressions) will result in parsing errors.
  Fix: Ensure input adheres strictly to the JSON5 specification. If arbitrary JavaScript parsing is needed, a dedicated JavaScript parser library should be used.

Install

• pip install json5 Install with pip

Imports

• json5

  import json5

  The library typically exposes functions like `load`, `loads`, `dump`, `dumps` directly under the `json5` module, mimicking the standard `json` library.

Quickstart

Demonstrates parsing JSON5 strings using `json5.loads()` and serializing Python objects to JSON5 strings using `json5.dumps()`. The API closely resembles Python's standard `json` module.

import json5

# Parse a JSON5 string with comments and trailing commas
config_string = """
{
  // Application settings
  name: 'my-app',
  version: '1.0.0',
  features: [
    'comments',
    'trailing commas',
  ],
}
"""
config = json5.loads(config_string)
print(f"App Name: {config['name']}")

# Convert a Python object to a JSON5 string
data = {
  'name': 'another-app',
  'debug': True,
  'ports': [3000, 3001],
}
json5_string = json5.dumps(data, indent=2, quote_keys=False, trailing_commas=True)
print("\nSerialized JSON5:")
print(json5_string)

# Example of reading/writing a file (assuming a config.json5 exists)
# with open('config.json5', 'w') as f:
#     json5.dump(data, f, indent=2)
#
# with open('config.json5', 'r') as f:
#     loaded_config = json5.load(f)
# print(f"\nLoaded from file: {loaded_config['name']}")