rconf 0.0.5

Extensible Python package to resolve references and apply patches in JSON and TOML configurations

What

Extensible Python package to resolve references and apply patches in JSON and TOML configurations.

It uses Python’s json module and tomllib module to decode, handles local and remote reference URLs using urllib, and resolves document fragments specified through pointers, optionally applying patches.

• References follow the JSON Reference draft.

• Reference patches are based on RFC 6902, extended with shorthand notations, an assign and a merge operation.

• JSON pointers follow RFC 6901.

• TOML pointers are TOML keys extended with array indices.

It can be used as a drop-in replacement for

• json.load and tomllib.load (rconf.load),

• json.loads and tomllib.loads (rconf.loads),

with an additional rconf.loadu to load URLs and local paths and rconf.loadc to load a Python dict. These functions all resolve references and apply patches.

Why

rconf allows a developer to

• not care about configuration location (URLs) and

• not care about configuration format (decoders),

and a user to

• reduce duplication by allowing URLs,

• reduce duplication by allowing references,

• reduce duplication by allowing patches and

• mix and match formats already in use.

How

Installation

RConf is pip-installable:

$ pip install rconf

Load a URL (with fragment pointer)

This snippet loads a document from a URL, and resolves the pointer in its fragment:

import json
import rconf

config = rconf.loadu("https://github.com/manifest.json#/icons/0")
print(json.dumps(config, indent=4))

{
    "sizes": "114x114",
    "src": "https://github.githubassets.com/apple-touch-icon-114x114.png"
}

or, with an explicit pointer,

import json
import rconf

config = rconf.loadu(
    "https://raw.githubusercontent.com/pypa/build/main/pyproject.toml",
    ptr="project.description",
)
print(json.dumps(config, indent=4))

"A simple, correct Python build frontend"

Load and patch a string

The string (config) contains a JSON document with a reference ($ref) and a patch assignment for /name.

import json
import rconf

config = rconf.loads("""
{
    "github-icon": {
        "$ref": "https://github.com/manifest.json#/icons/0",
        "/name": "GitHub icon"
    }
}
""")
print(json.dumps(config, indent=4))

{
    "github-icon": {
        "sizes": "114x114",
        "src": "https://github.githubassets.com/apple-touch-icon-114x114.png",
        "name": "GitHub icon"
    }
}

Mix and patch

Formats can be mixed, like this JSON document referencing a TOML document, patched with a $patch array using both the full and shorthand notations.

import json
import rconf

config = rconf.loads("""
{
    "$ref": "data:application/toml;base64,W3Byb2plY3RdCnRpdGxlID0gIlByb2plY3QgdGl0bGUiCmRlc2NyaXB0aW9uID0gIlByb2plY3QgZGVzY3JpcHRpb24iCnJlYWRtZSA9ICJyZWFkbWUubWQiCg==",
    "$patch": [
        {"op": "move", "path": "/project/name", "from": "/project/title"},
        ["-", "/project/readme"],
        ["+", "/project/dynamic", ["version"]]
    ]
}
""")
print(json.dumps(config, indent=4))

{
    "project": {
        "description": "Project description",
        "name": "Project title",
        "dynamic": [
            "version"
        ]
    }
}

Command Line Interface

rconf is added as a CLI tool, to translate JSON and TOML files with (or without) references and patches, and works with URLs or file paths.

$ rconf dump https://github.com/manifest.json#/icons/0
{
    "sizes": "114x114",
    "src": "https://github.githubassets.com/apple-touch-icon-114x114.png"
}

rconf dump behavior can be modified with a configuration file. rconf config can show or create an example.

Those using bash/zsh can activate auto completion, provided by argcomplete.

$ pip install rconf[sh]
$ activate-global-python-argcomplete --user

Definitions

Definitions can be found on the definitions page.

Usage

A more thorough description can be found on the usage page, with details in the reference.