jsontools module#

Module containing functions that simplifies interactions with data structured as JSON.

JsonContent#

JSON content type.

alias of dict[JsonKey, JsonValue]

JsonKey#

JSON keys are always strings

JsonValue#

JSON values can be anything from JSON domain

alias of Union[int, float, bool, str, None, dict[JsonKey, JsonValue], list[Optional[Union[int, float, bool, str]]], list[dict[JsonKey, JsonValue]]]

Scalar#

Scalar types as they are present in JSON files.

alias of Optional[Union[int, float, bool, str]]

apply_mapping(json_content, obs_new_mapping)[source]#

Searches for keys in obs_new_mapping and replace their values with the results of calling obs_new_mapping value with observed key and value as arguments (in that order).

This function alters json_content in situ.

Parameters:

  • json_content (jsontools.JsonContent) – JSON structured content

  • obs_new_mapping (Mapping[jsontools.JsonKey, Callable[[jsontools.JsonKey, jsontools.JsonValue], jsontools.JsonValue]]) – Dictionary that maps each key with the function that is used for the replacement.

Returns:

JSON configuration is modified inplace.

Return type:

None

convert_keys_to_naming_convention(json_content, from_nc='snake_case', dest_nc='lowerCamelCase')[source]#

Converts JSON with keys written in any supported NamingConvention to any other supported NamingConvention. Use lowerCamelCase for Energyworx API format.

This function alters json_content in situ.

Parameters:

  • json_content (jsontools.JsonContent) – Content of the JSON file that has to be converted.

  • from_nc (jsontools.NamingConvention) – Current naming convention of the keys.

  • dest_nc (jsontools.NamingConvention) – Resulting naming convention of the keys.

Returns:

JSON content with keys converted.

Return type:

None

convert_name_to_naming_convention(name, orig_mode='snake_case', dest_mode='CamelCase')[source]#

Converts between different naming conventions. Currently supports: NamingConvention.

Parameters:

  • name (str) – Name to be converted

  • orig_mode (Literal) – Current naming convention of name (see supported ones). Defaults to ‘snake_case’.

  • dest_mode (Literal) – Desired naming convention for name (see supported ones). Defaults to ‘CamelCase’.

Returns:

Name converted to dest_mode naming convention

Return type:

str

Examples

>>> convert_name_to_naming_convention('hello_world')
'HelloWorld'

>>> convert_name_to_naming_convention('hello_world', dest_mode='lowerCamelCase')
'helloWorld'

>>> convert_name_to_naming_convention('hello_world', dest_mode='Display Name')
'Hello World'

>>> convert_name_to_naming_convention('HelloWorld', 'CamelCase', 'snake_case')
'hello_world'
edit(json_value, matcher, converter, drop=True)[source]#

Add a new field for each key of the obs_keys found in the JSON using obs_new_mapping on the observed key and value to generate the new field key and value.

This function alters json_value in situ.

Parameters:

  • json_value (jsontools.JsonValue) – JSON structured content

  • matcher (Callable[[jsontools.JsonKey, jsontools.JsonValue], bool]) – Function that takes JSON key and value as arguments and returns True if this pair is a match, False otherwise

  • converter (Callable[[jsontools.JsonKey, jsontools.JsonValue], Iterator[tuple[jsontools.JsonKey, jsontools.JsonValue]]]) – Function that takes JSON key and value as arguments and yields JSON key and value pairs to incorporate to JSON content

  • drop (bool) – Flag indicating if matched key-value pair should be removed or not

Returns:

JSON content is modified inplace

Return type:

None

extract_typed_dict(json_content)[source]#
Parameters:

json_content (jsontools.JsonContent) –

Return type:

jsontools.JsonContent

flatten(json_value, prefix='')[source]#

Traverses a nested JSON file returning every key-value pair found, formatting keys by their path, from the shallowest to the deepest levels.

Parameters:

  • json_value (jsontools.JsonValue) – Any JSON structured content

  • prefix (str) –

Yields:

2-Tuples of path to key and its associated value

Return type:

Iterator[tuple[jsontools.JsonKey, jsontools.JsonValue]]

one_or_many(func)[source]#

Decorator to adap functions that modify a JsonContent to allow them take also a list of JsonConfigs.

Parameters:

func (Callable[[JsonContent, Variant], None]) – Function that takes a JsonContent as first argument and modifies it inplace.

Returns:

Function that can take either a JsonContent or a list of JsonContent as first argument. If it is a list, original function is applied to each item.

Return type:

Callable[[JsonContent | list[JsonContent], Variant], None]

search(json_content, *fields, all_=False)[source]#

Looks recursively in a JSON file for given fields. If all_ is True only matches from internal structures that contain all fields are returned.

Parameters:

  • json_content (jsontools.JsonContent) – JSON structured content

  • *fields (str) – All the fields that are going to be extracted from the JSON

  • all – If True only yields when all fields has been found. Otherwise yields when any field has been found

  • all_ (bool) –

Yields:

Dictionaries of found keys and values each time one JSON structure is encountered

Return type:

Iterator[dict[jsontools.JsonKey, list[jsontools.JsonValue]]]

walk_structures(json_value, max_depth=-1)[source]#

Traverses a nested JSON file returning every dictionary found from shallowest to deepest levels.

Parameters:

  • json_value (jsontools.JsonValue) – JSON structured content

  • max_depth (int) – Maximun depth of the structure returned, each time a dictionary is scanned depth level is raised

Yields:

Each JSON structure found in the given JSON, including given, json_value at first place, one by one

Return type:

Iterator[jsontools.JsonContent]