JSONC Parser

1.1.5 · active · verified Thu Apr 16

jsonc-parser is a lightweight, zero-dependency Python module designed for parsing `.jsonc` files, which are JSON files extended to support JavaScript-style comments. It allows developers to easily deserialize JSONC content into Python dictionaries, stripping out comments in the process. The library is currently at version 1.1.5 and is actively maintained with updates released on an as-needed basis rather than a strict schedule.

Common errors

```
ModuleNotFoundError: No module named 'jsonc_parser'
```
cause The `jsonc-parser` package is either not installed or is imported incorrectly. The main class is within a submodule.

fix Ensure the package is installed with `pip install jsonc-parser`. Correct the import statement to `from jsonc_parser.parser import JsoncParser`.
```
jsonc_parser.errors.FunctionParameterError: filepath parameter is not a path-like object (str, bytes object representing a path, or os.PathLike compliant) or is empty
```
cause The `filepath` argument passed to `JsoncParser.parse_file()` is not a valid string, bytes object, or `os.PathLike` object.

fix Provide a valid path, for example, `JsoncParser.parse_file('path/to/file.jsonc')` or `JsoncParser.parse_file(pathlib.Path('path/to/file.jsonc'))`.
```
jsonc_parser.errors.ParserError: file cannot be parsed/contains invalid JSON data
```
cause The content of the `.jsonc` file or string is not valid JSON, even after comments are stripped. This can include syntax errors like missing braces, unquoted keys, or invalid values.

fix Review the `.jsonc` content for standard JSON syntax errors (excluding comments). Use a JSON linter to validate the content without comments if necessary.

Warnings

breaking In version 1.1.5, the `filepath` parameter in methods like `parse_file` was changed to expect `os.PathLike` types instead of just strings. While strings generally work as `PathLike` objects, explicitly passing non-string `os.PathLike` objects is now fully supported. Incorrect types will raise a `FunctionParameterError`.
Fix: Ensure `filepath` arguments are valid path-like objects (e.g., strings, `pathlib.Path` objects). The error message will explicitly state if the parameter is not path-like.
gotcha The `jsonc-parser` library handles comments in JSON files. However, it does not explicitly state support for other non-standard JSON features like trailing commas, which are common in some JSONC implementations (e.g., VS Code's configuration files). Standard JSON does not allow trailing commas, and this parser likely adheres to that. Expect `ParserError` if trailing commas are present.
Fix: Ensure JSONC files strictly adhere to standard JSON syntax for everything except comments. Remove any trailing commas in objects or arrays before parsing if errors occur.
gotcha Parsing methods (`parse_file`, `parse_str`) can raise specific exceptions for different issues: `FileError` for file access problems, `FunctionParameterError` for invalid arguments (e.g., non-path-like `filepath`), and `ParserError` for invalid JSONC content that cannot be parsed.
Fix: Implement robust error handling around `jsonc-parser` calls. Catch `FileError`, `FunctionParameterError`, and `ParserError` to gracefully manage issues like missing files, incorrect parameter types, or malformed JSONC data.

Install

pip install jsonc-parser Install latest version

Imports

JsoncParser
wrong:
```
import jsonc_parser
```
correct:
```
from jsonc_parser.parser import JsoncParser
```
The primary class `JsoncParser` resides within the `jsonc_parser.parser` submodule, not directly under `jsonc_parser`.

Quickstart

This quickstart demonstrates how to parse a `.jsonc` file and a JSONC string using the `JsoncParser` class. It creates a temporary `.jsonc` file, reads its content (including comments), and then parses a direct string, showcasing how comments are stripped to yield a standard Python dictionary.

import os
from jsonc_parser.parser import JsoncParser

# Create a dummy JSONC file for demonstration
jsonc_content = '''
{
  "name": "Test Config", // Application name
  "version": "1.0.0", /* Current version */
  "settings": {
    "debugMode": true,
    "logLevel": "INFO"
  }
}
'''

file_path = "./config.jsonc"
with open(file_path, "w") as f:
    f.write(jsonc_content)

try:
    # Parse the .jsonc file
    data = JsoncParser.parse_file(file_path)
    print("Parsed data:", data)

    # Parse a JSONC string
    jsonc_string = '{ "message": "Hello, /* commented */ World!" }'
    string_data = JsoncParser.parse_str(jsonc_string)
    print("Parsed string data:", string_data)

finally:
    # Clean up the dummy file
    if os.path.exists(file_path):
        os.remove(file_path)

view raw JSON →