pyjson5

Warnings

• breaking In `pyjson5` v2.0.0, the `dump()` function now consistently writes `str` (Unicode) instead of `bytes` to file-like objects. This is a change from previous versions and can lead to `TypeError: a bytes-like object is required, not 'str'` if the target file object is opened in binary write mode (`'wb'`).
  Fix: Ensure that file-like objects passed to `pyjson5.dump()` are opened in text write mode (e.g., `open('file.json5', 'w')`) rather than binary write mode (`'wb'`).
• breaking Starting with `pyjson5` v2.0.0, the library explicitly requires Python 3.8 or later. Versions prior to `v1.6.8` supported Python 3.5+, and `v1.6.8` raised the minimum to Python 3.7+.
  Fix: Upgrade your Python environment to version 3.8 or newer to use `pyjson5` v2.0.0 and subsequent releases. If backward compatibility with older Python versions is required, use `pyjson5` v1.x.
• gotcha Unlike Python's standard `json` module, `pyjson5` does not support the `cls` keyword argument for custom `JSONDecoder` or `JSONEncoder` subclasses in its `load`, `loads`, `dump`, or `dumps` functions. This is due to its Cython-based parsing and serialization approach.
  Fix: Instead of `cls`, use the `default` keyword argument in `dumps` or `dump` for custom serialization of unsupported types. For custom deserialization, manual post-processing of the loaded Python object is often required.
• gotcha JSON5 is designed for human-editable configuration files, allowing features like comments and unquoted keys. It is generally not recommended for strict machine-to-machine communication, where the more rigid standard JSON format is often preferred due to broader tooling support and stricter validation.
  Fix: Consider the use case: if machine-to-machine interoperability is paramount, use Python's built-in `json` module. If human readability and maintainability of configuration files are the priority, `pyjson5` is a suitable choice.
• gotcha By default, `pyjson5.load()` and `pyjson5.loads()` allow duplicate keys within an object (dictionary) in the JSON5 input. When duplicate keys are present, the last encountered value for that key will override previous ones.
  Fix: To enforce strict parsing and disallow duplicate keys, pass `allow_duplicate_keys=False` to the `load()` or `loads()` functions. For example: `pyjson5.loads(json5_string, allow_duplicate_keys=False)`.

Install

• pip install pyjson5 Install latest version

Imports

• loads, dumps, load, dump

  import pyjson5
  # Use pyjson5.loads, pyjson5.dumps, etc.

  The PyPI package `json5` is a different, pure-Python implementation. This library (pyjson5, the Cython one) exposes its functions directly under the `pyjson5` module. Using `import json5` will import the other library if installed.

Quickstart

This quickstart demonstrates how to load JSON5 data from a string using `pyjson5.loads` and dump Python objects back to a JSON5 string using `pyjson5.dumps`. It also shows reading from and writing to file-like objects using `pyjson5.load` and `pyjson5.dump` respectively. Note the use of `io.StringIO` for in-memory file operations.

import pyjson5
import io

json5_data = """
{
  // This is a comment
  name: 'Project Alpha',
  version: 1.0.0,
  features: [
    'comments',
    'trailing commas',
  ],
  config: { key: 'value', }, // Trailing comma
}
"""

# Load from a string
data = pyjson5.loads(json5_data)
print(f"Loaded data: {data}")

# Dump to a string
output_json5 = pyjson5.dumps(data, indent=2)
print(f"\nDumped JSON5:\n{output_json5}")

# Load from a file-like object (StringIO acts like a file)
file_like_obj_read = io.StringIO(json5_data)
file_data = pyjson5.load(file_like_obj_read)
print(f"\nLoaded from file-like object: {file_data}")

# Dump to a file-like object
file_like_obj_write = io.StringIO()
pyjson5.dump(data, file_like_obj_write, indent=2)
print(f"\nDumped to file-like object:\n{file_like_obj_write.getvalue()}")