jsonc-sdict 0.2.20260516

keep comment(round-trip) when read & write jsonc/hjson, sdict with extra context(parent/keypath)

简中文档

jsonc_sdict 即典

Round-trip comments for JSONC/HJSON, with dict-like APIs for config editing.

• Keep comments on read and write (loads → edit → body / full).
• Work with nested structures via sdict ≈ deepmerge + deepdiff + benedict

Comments are data too, just like codes are data too by John von Neumann

[!WARNING] This project is currently 0.2.x and still evolving.

Usage

Install

pip install "jsonc-sdict[full]"

For local development:

pip install -e ".[dev]"

Quick usage

import hjson
from jsonc_sdict import jsoncDict, CommentIn, NONE

raw = """
{
  "a": 1,
  "b": 2
}
""".strip()

jc = jsoncDict(raw, loads=hjson.loads, dumps=hjson.dumps)
jc["b"] = 3
jc[CommentIn(NONE, "a")] = "// inserted before a"

print(jc.full)

Advanced usage

import hjson
from jsonc_sdict import jsoncDict, CommentIn, NONE

raw = """
// header
{
  "a": 1, // inline
  "b": 2
}
// footer
""".strip()

jc = jsoncDict(raw, loads=hjson.loads, dumps=hjson.dumps)
jc[CommentIn(NONE, "a")] = "// before a"
jc[CommentIn("a")] = {
    CommentIn("k", ":"): "/* key slot */",
    CommentIn(":", "v"): "/* value slot */",
    CommentIn("v", ","): "/* tail slot */",
}

print(jc.full)

Comment model

jsoncDict.comments stores comment positions with CommentIn(...) keys.

• CommentIn(left, right) means a comment between two logical items.
• CommentIn(key) means comments attached to one pair's internal slots.
• Slot comments use a dict with CommentIn("k", ":"), CommentIn(":", "v"), CommentIn("v", ",").
• CommentIn(NONE, first_key) and CommentIn(last_key, NONE) handle boundary comments.

Examples:

jc.comments[CommentIn("a", "b")] = "// between a and b"
jc.comments[CommentIn("b")] = {
    CommentIn("k", ":"): "/* before colon */",
    CommentIn(":", "v"): "/* before value */",
}

Edge cases

Invalid JSONC examples:

// /* this is still single-line comment
so this line is illegal */

/* // this is block comment */ trailing-text-is-illegal

Develop

env

LOG=DEBUG enables debug-level logging in project loggers.

Common setup:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
LOG=DEBUG pytest -q

Internal design

jsonc

• jsoncDict.loads() parses comments with tree-sitter and stores them into comments.
• jsoncDict.body renders the current value with comments restored.
• jsoncDict.full returns header + body + footer.
• CommentIn(key) comments are stored as slot maps, not raw strings, so key/colon/value/comma placement stays explicit.

sdict (common pitfalls)

• sdict wraps both mapping and iterable nodes; nested access may return sdict views, not raw dict/list.
• jsoncDict output depends on comment/data mutation paths; bypassing public APIs can leave internal state inconsistent.
• dfs() warns against mutating yielded data during iteration.
• insert(update, key=...|index=...) is ordering-oriented: it inserts by reordering keys after update.

weakList (common pitfalls)

• Items must support both __hash__ and weak references (__weakref__); built-in int/str/list/dict do not qualify.
• Weak references can disappear when no strong references exist; list length can shrink unexpectedly.
• WeakList(noRepeat=True) is not identical to OrderedWeakSet: repeated append/insert can move item position.

Related projects

json loads()

pypi	commits	issues	about	lack
spyoungtech/json-five			Python JSON5 parser with round-trip preservation of comments	can keep comment in another API style (e.g: BlockComment/wsc_before)
tusharsadhwani/json5kit			A Roundtrip parser and CST for JSON, JSONC and JSON5.
dpranke/pyjson5			A Python implementation of the JSON5 data format
austinyu/ujson5			A fast JSON5 encoder/decoder for Python
qvecs/qjson5			📎 A quick JSON5 implementation written in C, with Python bindings.

other format that support round-trip

• python-poetry/tomlkit | |
• ruamel.yaml