jsoncgx

An overpowered JSON-with-comments parser with inplace edition


Keywords
json, jsonc, with, comments, editor
Licenses
GPL-3.0/GPL-3.0+
Install
pip install jsoncgx==1.1

Documentation

jsoncgx: An overpowered JSON-with-comments parser with inplace edition

Cool, a JSONC parser for Python. How do I load my file into a dict?

I'll stop you right here. If you're only looking at simply deserialising JSONC files, this library is not for you.

jsoncgx is developped with 3 intentions:

  1. Supporting C-style // and C++-style /**/ comments. This part is typical, there are lots of other libraries offering this functionality.
  2. Offering more flexibility with the JSON syntax that your usual straight-to-Python-types parser. Namely, the JSON format allows to have multiple name:value pairs with the same name in the same object, but that is not supported by Python's dicts.
  3. Inplace edition, that is, being able to replace a chunk of a given JSONC file without messing up its indentation or comments. Typically, libraries only offer indentation imitation, that is, deserialisation makes guesses about the indentation, and serialisation reproduces it.

Installation

This library is available on PyPI:

pip install --user jsoncgx

Comparison / Quickstart / Demo

Standard Python module

jsoncgx

Loading JSON data
>>> import json
>>> data = json.loads('{ "answer": 42 }')
>>> data["answer"]
42
>>> import jsoncgx
>>> editor = jsoncgx.loads('{ "answer": 42 }')
>>> editor.root["answer"][0]
42
Editing JSON data
>>> data["answer"] = "spam"
>>> json.dumps(data)
'{"answer": "spam"}'
>>> editor.root.editreplacevalue(0, "spam")
>>> editor.dumps()
'{ "answer": "spam" }'
Working with JSON files
>>> with open("in.json") as f:
...   data = json.load(f)
...
>>> with open("out.json", "w") as f:
...   json.dump(data, f)
...
>>> editor = json.loadf("in.json")
>>> editor.dumpf("out.json")

Or use jsoncgx.load() and jsoncgx.JSONEditor.dump() with a file handle, like the standard module.

Non unique name
>>> data = json.loads(
...     '{ "answer": 42, "answer": "spam" }')
>>> data["answer"]
'spam'
>>> editor = jsoncgx.loads(
...     '{ "answer": 42, "answer": "spam" }')
>>> editor.root["answer"][0]
42
>>> editor.root["answer"][1]
'spam'
Comments
>>> data = json.loads(
...     '{ "answer": /* eggs and */ 42 }')
Traceback (most recent call last):
...
json.decoder.JSONDecodeError: ...
>>> editor = jsoncgx.loads(
...     '{ "answer": /* eggs and */ 42 }')
>>> editor.root.editreplacevalue(0, "spam")
>>> editor.dumps()
'{ "answer": /* eggs and */ "spam" }'

What syntax does this parse exactly?

ECMA-404 with the following additional lexical elements:

  • regex //[^\n]*\n, that is, the Unicode scalar sequence:
    • U+002F,
    • U+002F,
    • any amount of any scalars except U+000A,
    • U+000A.
  • lazy regex /\*.*\*/, that is, the Unicode scalar sequence:
    • U+002F,
    • U+002A,
    • any amount of any scalars except the sequence U+002A U+002F
    • U+002A,
    • U+002F.

Those elements are considered like whitespace.

Architecture

jsoncgx architecture

Changelog

V1.1:

  • JSONNumber, JSONString, JSONBool, and JSONNull have been replaced with JSONBuiltin, for easier integration.
  • edit*() methods that accepted JSONValue now also accept int, float, str, bool, and None. They are automatically turned into JSONBuiltin.