Usage#

rconf offers a rconf.load() and a rconf.loads() function in line with json and tomllib, as well as a rconf.loadu() function (URLs and local paths) and a rconf.loadc() function (rconf.Value).

They all decode documents applying references and patches.

They are convenience methods for a globally installed rconf.Loader, and the same functions exist as rconf.Loader member methods.

The default global rconf.Loader includes

JSON and TOML configuration language handlers (rconf.decode.BaseHandler) and
the default URL handlers that come with urllib.request (urllib.request.BaseHandler for scheme file, http, https, ftp and data).

Depending on the scheme, the language is defined based on the Media Type or the file extension [1].

The architecture is inspired by urllib, and its urllib.request.BaseHandler and urllib.request.OpenerDirector.

Load URL#

rconf.loadu() is the easiest to use, and takes

a file path [2] or URL, optionally with a language-specific pointer as fragment.

The URL components can be overridden with

an optional explicit media_type or file extension,
an optional base_url to resolve relative references,
an optional fragment pointer ptr to replace the URL fragment.

kwargs are forwarded to json.load() or tomllib.load() if relevant.

Example#

Listing 1 Example rconf.loadu() usage.#

import json

import rconf

config = rconf.loadu("https://github.com/manifest.json#/icons/0/src")

# or explicitly
config_explicit = rconf.loadu(
    "https://github.com/manifest.json",
    ptr="/icons/0/src",
    media_type=".json",
)

print(json.dumps(config, indent=4))

assert config == config_explicit

results in

"https://github.githubassets.com/assets/apple-touch-icon-114x114-09ce42d3ca4b.png"

Load file or string#

rconf.load() and rconf.loads() load a configuration document from a binary file or string respectively.

An additional optional argument url can set either an assumed URL or a base_url for the document, and the same media_type and ptr as for rconf.loadu() are available.

Example#

Listing 2 Example rconf.loads() usage.#

import json

import rconf

doc = """
{
"$ref": "https://github.com/manifest.json#/icons/0",
"/name": "GitHub icon"
}
"""

config = rconf.loads(doc)
print(json.dumps(config, indent=4))

results in

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

Additional configuration languages and URL handlers#

To create a rconf.Loader with these and other handlers, rconf.build_loader() can be used. To use a loader globally, pass it to rconf.install_loader().

rconf.build_loader() takes

one or more rconf.decode.BaseHandler or urllib.request.BaseHandler arguments
explicit opener (urllib.request.OpenerDirector) and/or decoder (rconf.decode.DecoderDirector) arguments.

Example#

Listing 3 Adding a rconf.decode.BaseHandler for INI files,
and a urllib.request.BaseHandler for scheme ppr
(PprHandler).#

import json

import ppr_handler

import rconf

loader = rconf.build_loader(
    rconf.decode.INIHandler(("text/ini", ".ini")),
    ppr_handler.PprHandler(),
)
rconf.install_loader(loader)

doc = """
[DEFAULT]
some = one

[output_media_type]
$ref = ppr://rconf/scripts/rconf.toml#dump
"""

config = rconf.loads(doc, media_type=".ini")
print(json.dumps(config, indent=4))

results in

{
    "output_media_type": {
        "output_media_type": "json",
        "some": "one"
    }
}

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 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.

Listing 4 argcomplete for the impatient.#

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

Example#

Listing 5 Example rconf usage.#

rconf dump https://github.com/manifest.json#/icons/0

rconf dump https://github.com/manifest.json -m json -M str -p /icons/0

results in

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

Example with configuration file#

In the same way additional handlers can be loaded in an rconf.Loader, rconf supports listing handlers in a configuration file.

The following configuration file

sets the fallback media type to INI files,
adds a rconf.decode.BaseHandler for INI files with TOML pointers,
adds a urllib.request.BaseHandler for scheme ppr (PprHandler) and
enables dumping to TOML using tomli_w.

Listing 6 Example rconf configuration file.#

# Options for `rconf dump`
[dump]
output_media_type = "toml"

# How to load: rconf.build_loader arguments
[dump.loader]
fallback = "ini"

# INIHandler with TOMLPointer
[[dump.loader.handlers]]
class        = "rconf.decode.INIHandler"
media_types  = [["text/ini", ".ini"]]
pointer_type = "rconf.TOMLPointer"

# PprHandler for ppr:// URLs, requires pip install ppr-handler
[[dump.loader.handlers]]
class = "ppr_handler.PprHandler"

# How to dump: stringify the rconf.Value
# TOML; requires pip install tomli-w
[dump.dumpers.toml]
callable = "tomli_w.dumps"

It can then be used to get config.dump from an inline INI file:

Listing 7 Example rconf using a configuration file.#

folder=`dirname -- "$0"`

rconf -c ${folder}/config.toml dump -p config.dump - << 'EOF'
[config]
$ref = ppr://rconf/scripts/rconf.toml

EOF

which results in

output_media_type = "json"