pyzenkit.jsonconf module

This module provides tools for manipulating JSON configuration files:

  • Simple writing of formated JSON configuration files

  • Simple reading of any JSON configuration files

  • Merging multiple JSON configuration files or configuration directories

  • Support for single line comments in JSON files (#, //)

  • Support for semi-automated JSON schema validation

Usage example

Example usage is implemented directly within this module, please refer to source code. To view the result of demonstration please execute the module directly with Python3 interpretter.

exception pyzenkit.jsonconf.JSONSchemaException(errstr, errlist)[source]

Bases: Exception

Exception describing JSON schema problems.

This exception will be thrown, when JSON schema validation fails.

pyzenkit.jsonconf.config_load(config_file, schema=None, silent=False)[source]

Load configuration from given JSON configuration file with optional JSON schema validation.

Parameters

  • config_file (str) – Name of the source JSON config file to be loaded.

  • schema – Schema can be either bool, str, or dict. If the schema is boolean, generate the name of the schema file from the name of configuration file by appending .schema suffix. If the schema parameter is string and it is the name of existing directory, look for appropriate schema file in that directory. If the schema parameter is string and it is the name of existing file, load the schema definitions from that file. If the schema is dict, treat it as a JSON schema structure and directly perform validation.

  • silent (bool) – Optional flag for suppressing exceptions on missing file, defaults to False.

Raises

TypeError – if the schema has invalid data type.

Returns

Loaded data structure.

Return type

dict

pyzenkit.jsonconf.config_load_dir(config_dir, schema=None, extension='.json.conf', silent=False)[source]

Load configuration from all JSON configuration files found within given configuration directory with optional JSON schema validation. Merges all loaded configurations into single dict, so the order of files matters and it is possible to overwrite previously defined keys.

Warning

The merge is done using dict.update() method and occurs only at highest level.

Parameters

  • config_dir (str) – Names of the configuration directory.

  • schema – Schema can be either bool, str, or dict. If the schema is boolean, generate the name of the schema file from the name of configuration file by appending .schema suffix. If the schema parameter is string and it is the name of existing directory, look for appropriate schema file in that directory. If the schema parameter is string and it is the name of existing file, load the schema definitions from that file. If the schema is dict, treat it as a JSON schema structure and directly perform validation.

  • extension (str) – Config file name extension for lookup function.

  • silent (bool) – Optional flag for suppressing exceptions on missing file, defaults to False.

Raises

TypeError – if the schema has invalid data type.

Returns

Loaded data structure.

Return type

dict

pyzenkit.jsonconf.config_load_n(config_files, schema=None, silent=False)[source]

Load configuration from multiple JSON configuration files with optional JSON schema validation. Merges all loaded configurations into single dict, so the order of files matters and it is possible to overwrite previously defined keys.

Warning

The merge is done using dict.update() method and occurs only at highest level.

Parameters

  • config_files (str) – List of names of the source JSON config files to be loaded.

  • schema – Schema can be either bool, str, or dict. If the schema is boolean, generate the name of the schema file from the name of configuration file by appending .schema suffix. If the schema parameter is string and it is the name of existing directory, look for appropriate schema file in that directory. If the schema parameter is string and it is the name of existing file, load the schema definitions from that file. If the schema is dict, treat it as a JSON schema structure and directly perform validation.

  • silent (bool) – Optional flag for suppressing exceptions on missing file, defaults to False.

Raises

TypeError – if the schema has invalid data type.

Returns

Loaded data structure.

Return type

dict

pyzenkit.jsonconf.config_validate(data, schema)[source]

Perform json schema validation of given object, raise JSONSchemaException in case of any validation error.

Parameters

  • data (dict) – Data structure to be validated.

  • schema (dict) – JSON schema to validate against.

Raises

  • TypeError – if the schema has invalid data type.

  • JSONSchemaException – if the schema validation fails.

Returns

Always returns True on success.

Return type

bool

pyzenkit.jsonconf.json_default(obj)[source]

Fallback method for serializing unknown objects into JSON.

pyzenkit.jsonconf.json_dump(data, **kwargs)[source]

Dump given data structure into JSON string. The kwargs are directly passed to underlying json.dumps(), so the available options are the same. However, following option will receive default values when not set:

  • sort_keys - Will be set to True by default.

  • indent - Will be set to 4 by sefault.

  • default - Will be set to _json_default by default.

Parameters

  • data – Data structure to be stored.

  • kwargs – Optional additional arguments as keywords.

Returns

Data structure as JSON string.

Return type

str

pyzenkit.jsonconf.json_load(json_file, silent=False)[source]

Load contents of given JSON configuration file.

The JSON syntax is enhanced with support for single line comments (‘#’,’//’), but the parsing is really simple and the comment must be at the beginning of the line (except for whitespaces).

Parameters

  • json_file (str) – Name of the source JSON file.

  • silent (bool) – Optional flag for suppressing exceptions on missing file, defaults to False.

Returns

Loaded data structure.

Return type

dict

pyzenkit.jsonconf.json_save(json_file, data, **kwargs)[source]

Save data structure into given JSON configuration file. The kwargs are directly passed to underlying json.dumps(), so the available options are the same. However, following option will receive default values when not set:

  • sort_keys - Will be set to True by default.

  • indent - Will be set to 4 by sefault.

  • default - Will be set to _json_default by default.

Parameters

  • json_file (str) – Name of the target JSON file.

  • data – Data structure to be stored.

  • kwargs – Optional additional arguments as keywords.

Returns

Always returns True.

Return type

bool

pyzenkit.jsonconf.sortkey(key)[source]

Helper method for sorting JSON paths.

Treat keys as lowercase, prefer keys with less path segments.

Parameters

key (str) – Key to be sorted.

Returns

Key in sortable format.

Return type

tuple