jsonxox 0.8.0

Parsing for extended JSON with optional comments and trailing commas

JSONXOX: Extended JSON Parsing

Do you love the JSON serialization format but wish it included support for optional comments and trailing commas? Well if so, the JSONXOX library is for you.

The JSONXOX library provides support for parsing extended JSON files and strings – JSON files and strings which may contain optional C-style single-line and multi-line comments as well as trailing commas.

Requirements

The JSONXOX library has been tested with Python 3.10, 3.11, 3.12, 3.13 and 3.14. The library has not been tested with, nor is it likely compatible with Python 3.9 and earlier.

Installation

The JSONXOX library is available from PyPI, so may be added to a project's dependencies via its requirements.txt file or similar by referencing the JSONXOX library's name, jsonxox, or the library may be installed directly into the local runtime environment using pip install by running the following command:

$ pip install jsonxox

Usage Example

To use the JSONXOX library, simply import the library into your project as a drop-in replacement for the standard json library, and use it as you would to load a JSON file or JSON string. The library can be used to load standard JSON files and strings as well as extended JSON files and strings containing single- and multi-line comments as well as trailing commas. The library can also be used to save standard JSON files and strings.

See the Methods section for more information about the methods provided by the library.

import jsonxox

sample: str = """
/* this is a multi-line comment block
that can span multiple lines or just a single line
*/
{
  "a": 123, /* this is also a multi-line comment block (using a single line) */
  // this is a single-line comment
  "b": "456", // notice the trailing comma
}
"""

data = jsonxox.loads(sample)

assert isinstance(data, dict)

assert "a" in data
assert data["a"] == 123

assert "b" in data
assert data["b"] == "456"

Methods

The jsonxox library provides the following methods, mirroring the standard json library in its available methods and overall functionality:

• load(handle, **kwargs) (object) – The load() method takes a file handle or file handle like object that is an instance of io.TextIOWrapper or one of its subclasses as input and removes any single and multi-line comments as well as any trailing commas from the input string contents read from the file handle, and then passes the cleaned string to the standard library's json.loads() method for quick deserialization to its corresponding Python data types. Any additional keyword arguments are passed to the json.loads() method, as such any additional keyword arguments must be compatible with the json.loads() method.

• loads(handle, **kwargs) (object) – The loads() method takes a string as input and removes any single and multi-line comments as well as any trailing commas from the input string, and then passes the cleaned string to the standard library's json.loads() method for quick deserialization to its corresponding Python data types. Any additional keyword arguments are passed to the json.loads() method, as such any additional keyword arguments must be compatible with the json.loads() method

• dump(*args, **kwargs) – The dump() method is a passthrough to the standard json library's dump() method and accepts the same arguments and has the same return values. Note that the dump() method cannot be used to re-save any comments or trailing commas that may have been present in the original extended JSON file or string.

• dumps(*args, **kwargs) (str) – The dumps() method is a passthrough to the standard json library's dumps() method and accepts the same arguments and has the same return values. Note that the dumps() method cannot be used to re-save any comments or trailing commas that may have been present in the original extended JSON file or string.

Classes

The jsonxox library provides the following classes, mirroring the standard json library in its available classes:

• JSONDecoder – The JSONDecoder class is a direct import of and reference to the standard json library's JSONDecoder class.

• JSONEncoder – The JSONEncoder class is a direct import of and reference to the standard json library's JSONEncoder class.

Exceptions

The jsonxox library provides the following exception classes, mirroring the standard json library in its available exception classes:

• JSONDecodeError – The JSONDecodeError exception class is a direct import of and reference to the standard json library's JSONDecodeError exception class.

• JSONXOXDecodeError – The JSONXOXDecodeError exception class is a subclass of the standard json library's JSONDecodeError class and will be raised by the jsonxox library if an exception occurs while attempting to clean or load the JSON input.

Unit Tests

The JSONXOX library includes a suite of comprehensive unit tests which ensure that the library functionality operates as expected. The unit tests were developed with and are run via pytest.

To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a Docker image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is installed, and perform the following commands, which will build the Docker image via docker compose build and then run the tests via docker compose run – the output the tests will be displayed:

$ docker compose build
$ docker compose run tests

To run the unit tests with optional command line arguments being passed to pytest, append the relevant arguments to the docker compose run tests command, as follows, for example passing -v to enable verbose output and -s to print standard output:

$ docker compose run tests -v -s

See the documentation for PyTest regarding available optional command line arguments.

Copyright & License Information

Copyright © 2023–2026 Daniel Sissman; licensed under the MIT License.