Low-level utilities (util)

Submodules:

click	Command-line utilities.
importlib	Load model and project code from message_data.
logging	Logging utilities.

Commonly used:

as_codes(data)	Convert data to a list of Code objects.
load_package_data(*parts[, suffix])	Load a message_ix_models package data file and return its contents.
load_private_data(*parts)	Load a private data file from message_data and return its contents.
package_data_path(*parts)	Construct a path to a file under message_ix_models/data/.
private_data_path(*parts)	Construct a path to a file under data/ in message_data.

message_ix_models.util.PACKAGE_DATA: Dict[str, Any] = {}

Package data already loaded with load_package_data().

message_ix_models.util.PRIVATE_DATA: Dict[str, Any] = {}

Data already loaded with load_private_data().

message_ix_models.util.as_codes(data) → List[sdmx.model.Code]

Convert data to a list of Code objects.

Various inputs are accepted:

• list of str.

• dict, in which keys are Code.id and values are further dict with keys matching other Code attributes.

message_ix_models.util.load_package_data(*parts: str, suffix: Optional[str] = '.yaml') → Mapping

Load a message_ix_models package data file and return its contents.

Data is re-used if already loaded.

Example

The single call:

>>> info = load_package_data("node", "R11")

1. loads the metadata file data/node/R11.yaml, parsing its contents,

2. stores those values at PACKAGE_DATA["node R11"] for use by other code, and

3. returns the loaded values.

Parameters

• parts (iterable of str) – Used to construct a path under message_ix_models/data/.

• suffix (str, optional) – File name suffix, including, the “.”, e.g. .yaml.

Returns

Configuration values that were loaded.

Return type

dict

message_ix_models.util.load_private_data(*parts: str) → Mapping

Load a private data file from message_data and return its contents.

Analogous to load_package_data, but for non-public data.

Parameters

parts (iterable of str) – Used to construct a path under data/ in the message_data repository.

Returns

Configuration values that were loaded.

Return type

dict

Raises

RuntimeError – if message_data is not installed.

message_ix_models.util.package_data_path(*parts) → pathlib.Path

Construct a path to a file under message_ix_models/data/.

message_ix_models.util.private_data_path(*parts) → pathlib.Path

Construct a path to a file under data/ in message_data.

util.click

Command-line utilities.

These are used for building CLIs using click.

message_ix_models.util.click.PARAMS = {'dest': <Option dest>, 'dry_run': <Option dry_run>, 'force': <Option force>, 'output_model': <Option output_model>, 'platform_dest': <Option platform_dest>, 'policy_path': <Option policy_path>, 'quiet': <Option quiet>, 'regions': <Option regions>, 'rep_out_path': <Option rep_out_path>, 'rep_template': <Option rep_template>, 'run_reporting_only': <Option run_reporting_only>, 'ssp': <Argument ssp>, 'verbose': <Option verbose>}

Common command-line parameters (arguments and options). See common_params().

message_ix_models.util.click.common_params(param_names: str)

Decorate a click.command with common parameters param_names.

param_names must be a space-separated string of names appearing in PARAMS, e.g. "ssp force output_model". The decorated function receives keyword arguments with these names:

@click.command()
@common_params("ssp force output_model")
def mycmd(ssp, force, output_model)
    # ...

message_ix_models.util.click.default_path_cb(*default_parts)

Return a callback function for click.Option handling.

If no option value is given, the callback uses Context.get_local_path() and default_parts to provide a path that is relative to local data directory, e.g. the current working directory (see Data, metadata, and configuration).

message_ix_models.util.click.store_context(context, param, value)

Callback that simply stores a value on the Context object.

Use this for parameters that are not used directly in a @click.command() function, but need to be carried by the Context for later use.

util.context

util.importlib

Load model and project code from message_data.

class message_ix_models.util.importlib.MessageDataFinder

Load model and project code from message_data.

util.logging

Logging utilities.

class message_ix_models.util.logging.Formatter(colorama)

Formatter for log records.

Parameters

colorama (module) – If provided, colorama is used to colour log messages printed to stdout.

format(record)

Format record.

Records are formatted like:

model.transport.data.add_par_data  220 rows in 'input'
...add_par_data:  further messages

…with the calling function name (e.g. ‘add_par_data’) coloured for legibility on first occurrence, then dimmed when repeated.

message_ix_models.util.logging.make_formatter()

Return a Formatter instance for the message_ix_models logger.

See also

setup

message_ix_models.util.logging.setup(level='NOTSET', console=True)

Initialize logging.

Parameters

• level (str, optional) – Log level for message_ix_models and message_data.

• console (bool, optional) – If True, print all messages to console using a Formatter.

message_ix_models.util.logging.silence_log()

Context manager to temporarily silence log output.

Examples

>>> with silence_log():
>>>     log.warning("This message is not recorded.")