Registry / serialization / commentjson

commentjson

JSON →
library0.9.0pypypi✓ verified 25d ago

commentjson is a Python package that enables you to include Python-style (#) and JavaScript-style (//) comments within your JSON files. Its API closely mirrors the standard library's `json` module, providing `load`, `loads`, `dump`, and `dumps` functionalities. Currently at version 0.9.0, the library is actively maintained, with recent releases focusing on performance improvements and compatibility.

pip install commentjson
INSTALL
IMPORT
SIG · COMMENTJSON
C
commentjson
serializationpythonv0.9.0
Install
3.2s avg
Import
204ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.206s · 19.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.2s · import 0.202s · 20MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

commentjson
import commentjson
The library is imported directly as 'commentjson', mirroring the standard 'json' module's import pattern.

This quickstart demonstrates how to parse a JSON string containing both Python-style `#` and JavaScript-style `//` comments using `commentjson.loads`. It then shows how to serialize a Python dictionary back into a JSON string using `commentjson.dumps`, which behaves like the standard `json` module, meaning comments are typically discarded during serialization. The API is designed to be a drop-in replacement for the standard `json` library.

import commentjson import os # Example JSON string with comments json_string_with_comments = '''{ "name": "Vaidik Kapoor", # Person's name "location": "Delhi, India", // Person's location # Section contains info about // person's appearance "appearance": { "hair_color": "black", "eyes_color": "black", "height": "6" } }''' # Deserialize JSON with comments data = commentjson.loads(json_string_with_comments) print(f"Loaded data: {data}") # Serialize Python object back to JSON (comments are not preserved by default in dumps/dump) # To demonstrate, let's modify and dump data['appearance']['height'] = '6 ft' output_json = commentjson.dumps(data, indent=4) print(f"\nSerialized data (without original comments):\n{output_json}") # If you were to load from a file, you'd use commentjson.load # with open('config.jsonc', 'w') as f: # f.write(json_string_with_comments) # with open('config.jsonc', 'r') as f: # file_data = commentjson.load(f) # print(f"\nLoaded from file: {file_data}")
Debug
Known issues
breakingPython 2.6 support was officially dropped in version 0.8.0. Applications targeting Python 2.6 will not be compatible with this or newer versions.
fix
Upgrade to Python 2.7 or, preferably, Python 3 for compatibility.
affects: >=0.8.0
gotchacommentjson relies on the `lark` parser. Earlier versions (0.8.1, 0.8.3) experienced compatibility issues with specific `lark-parser` releases. While generally resolved, ensure your `lark` dependency is compatible if you encounter parsing errors after updates.
fix
Ensure `commentjson` and `lark` are updated to their latest compatible versions. If issues persist, consider pinning `lark` to a known working version as specified by `commentjson`'s `requirements.txt` on GitHub.
affects: >=0.8.1
gotchaStandard JSON (per RFC 8259) does not officially support comments. Using `commentjson` allows you to *parse* JSON files with comments, but if you `dump` or `dumps` the data, the comments will be lost. Any other standard JSON parser will fail if fed a file containing comments.
fix
Understand that `commentjson` is for *reading* commented JSON. If comments need to be preserved across read/modify/write cycles, you would need a more sophisticated solution or a different configuration format like YAML or JSONC, or manually manage comments (which `commentjson` does not support for round-tripping comments).
affects: all
gotchaVersion 0.8.2 fixed unicode handling issues to align with the standard `json` package. Older versions might have subtle differences in how unicode characters are processed.
fix
Upgrade to version 0.8.2 or newer to ensure consistent and correct unicode handling.
affects: <0.8.2
gotchaPrior to v0.9.0, trailing commas in JSON were not officially supported and would cause parsing errors. While v0.9.0 added support, be aware that standard JSON does not permit trailing commas, so other parsers will still fail.
fix
Upgrade to version 0.9.0 or newer to use trailing commas. Remember that this is still non-standard JSON, only supported by `commentjson`.
affects: <0.9.0
Errors
Common errors & fixes
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line X column Y (char Z)
This error occurs when you try to parse a JSON file or string containing Python-style (#) or JavaScript-style (//) comments using Python's standard `json` module, which does not support comments.
fix
Use `commentjson.load` or `commentjson.loads` instead of `json.load` or `json.loads` to correctly parse the JSON with comments. Example: `import commentjson; data = commentjson.loads(commented_json_string)`
ImportError: cannot import name 'dump' from 'commentjson' (or 'loads')
This error happens when you try to import specific functions like `dump` or `loads` directly from the `commentjson` package (e.g., `from commentjson import dump`). The `commentjson` library is designed to be imported as a module, mimicking the standard `json` library's API.
fix
Import `commentjson` as a module and then access its methods. Example: `import commentjson; commentjson.dump(obj, fp)` or `commentjson.loads(text)`
commentjson.JSONLibraryException: Expecting property name enclosed in double quotes: line X column Y (char Z)
`commentjson` successfully stripped the comments from your input, but the remaining text still contains invalid JSON syntax that the underlying standard `json` module cannot parse. This often includes issues like missing commas, unquoted keys, or incorrect data types after comment removal.
fix
Examine the JSON content *after* comments have been removed to identify and fix any remaining syntax errors. The error message within `JSONLibraryException` provides details from the standard `json` module about the specific parsing issue and location.
Upgrade
Version history
0.9.0latest on PyPI · released Oct 5, 2020
Audit
Dependencies
larkrequiredUsed as the underlying parsing engine for robust comment handling.
Agent activity
11 hits · last 30 days
node
8
OpenAI (training)
1
Resources
commentjson — pip install commentjson · libregistry