jsonc-sdict 0.1.20260302

keep comment(round-trip) when read & write jsonc/json5, signal dict with recording extra context(parent/keypath)

jsonc_sdict 即典

maybe is the only solution support round-trip(keep comments both for read&write) for jsonc/hjson, with easy api design.

bundled sdict = deepmerge + deepdiff + benedict

bundled weakList & OrderedWeakList because cpython has not implemented.

[!WARNING] some code was written by AI, and I'm re-writing/cleanup code in the future.

Usage

jc = jsonc(my_dict)
# or jsonc(json.loads(my_str), my_str)
# jc.update(hjson.loads(jc.body)) # if my_str
jc["//unique-keyname"] = "my comment but at end of body"
jc.insert_comment({
    "/*\\nunique-keyname-1": "my multi-\\nline comments\\n"
    "//\\nunique-keyname-2": "my line-above comments"
    "//your data key overlap with comment-keyname rule?" + DATA: ["treat as data, not comment"] # rare edge case
    }, "existedKey"
)
jc.body = hjson.dumps(jc)
f.write(jc.body)

comment keyname rule

TODO: english version

{
    '//0<SEED>': ' "": null, # dict内的顺序与真实的注释出现位置一致
    '0': 0,
    '//1<SEED>': ' 0', # 行内注释，在dict内的排序需要在真实数据的后面。
    '//2<SEED>': ' "1": 1,/* 1 */\n', # 行上注释，则末尾应该有个\n
    '/*,3<SEED>': ' 2 ', # 不应为`/*`，而应为`/*,`，其中prefix[0:1]=="/*"，而prefix[2]==","代表这个多行注释应该`放到一个逗号前面`的意思; 多行注释按`向下查找的栈`规则，所以需要放到真实数据 "2": 2的前面。
    '2': 2,
    '/*\n4<SEED>': ' 👻 ', # `/*\n`代表多行注释的末尾是一个换行符，也相当于多行版本的行上注释
    '/*,5<SEED>': ' 3\n  4\n  * 5\n  ', # 不应为`/*`，而应为`/*,`
    '3': 3,
    '/*v6<SEED>': ' 6 ', # `/*v` 代表多行注释应该出现在实际的value槽位之前
    '6//': 6,
    '/*k7<SEED>': ' 7 ', # `/*k` 代表多行注释应该出现在实际的key槽位之前
    '7': 7,
    '/*\n8<SEED>': ' 8 ', # `/*\n`代表多行注释应该在**下方**kv数据的末尾，然后是换行符(这一点不要与 "//...": "...\n"行上注释末尾必须是\n 的规则混淆了)
    '8': 8,
    '//9<SEED>': ' "9": 9',
    '/-node<SEED>': jsonc({'just ignore these': 'i am in node comment'}),
    'node': jsonc({'do not ignore me': 'i am real data!'}),
}

同理，/*:代表多行注释应该出现在冒号前面，key槽位的后面。

json loads() substitute

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