JSON5 for Python

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']}")