# 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**](#methods) section for more information about the methods provided
by the library.

```python
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"
```

<a id="methods"></a>
### 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](https://www.docker.com) image is
created within which the tests are run. To run the unit tests, ensure Docker and Docker
Compose is [installed](https://docs.docker.com/engine/install/), 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:

```shell
$ 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:

```shell
$ docker compose run tests -v -s
```

See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding
available optional command line arguments.

### Copyright & License Information

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