简中文档

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
• Use weak-reference ordered containers via weakList/OrderedWeakSet.

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

For local development:

pip install -e ".[dev]"

Quick usage

import hjson
from jsonc_sdict import jsoncDict, Within, NONE

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

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

print(jc.full)

Advanced usage

import hjson
from jsonc_sdict import jsoncDict, Within, NONE

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

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

print(jc.full)

Comment model

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

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

Examples:

jc.comments[Within("a", "b")] = "// between a and b"
jc.comments[Within("b")] = {
    Within("k", ":"): "/* before colon */",
    Within(":", "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.
• Within(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, but in AST-tree style with lots of re-defined concepts (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