Configuration

This module enables access to get and set FIREWHEEL’s configuration.

firewheel.config.config

This is a convenient way to access FIREWHEEL’s configuration dictionary.

Type:

dict

Examples

This module could be leveraged either by using config to directly access the configuration:

>>> from firewheel.config import config
>>> print(config["logging"]["firewheel_log"])
firewheel.log

Alternatively, users can leverage the Config:

>>> from firewheel.config import Config
>>> fw_config = Config()
>>> print(fw_config.config["logging"]["firewheel_log"])
firewheel.log

This module enables access to get and set FIREWHEEL’s configuration.

firewheel.config._config.config

This is a convenient way to access FIREWHEEL’s configuration dictionary.

Type:

dict

Examples

This module could be leveraged either by using config to directly access the configuration:

>>> from firewheel.config import config
>>> print(config["logging"]["firewheel_log"])
firewheel.log

Alternatively, users can leverage the Config:

>>> from firewheel.config import Config
>>> fw_config = Config()
>>> print(fw_config.config["logging"]["firewheel_log"])
firewheel.log
class firewheel.config._config.Config(config_path: str = '', writable: bool = False)[source]

Provide an interface to firewheel.yaml.

This class enables programmatic interaction with FIREWHEEL’s configuration. through various getters and setters. Aside from manually editing firewheel.yaml, this Class should be the single programmatic interface to those settings.

This class (or config) can be accessed asynchronously by any FIREWHEEL module. This can cause issues if there are multiple simultaneous writers. However, almost all FIREWHEEL code relies on reading values from the configuration. Additionally, we try to prevent this by restricting write access to functions which specifically request it. This prevents accidental writes to the config.

Note

We recommend limiting the setting of configuration variables and saving the configuration to only the CLI config command.

__init__(config_path: str = '', writable: bool = False) → None[source]

Initialize the FIREWHEEL configuration.

This should read the configuration for firewheel.yaml to enable access for various FIREWHEEL modules.

Parameters:

  • config_path (str) – A specific path to locate the configuration file. If this is not provided, it is assumed that the default file location (./firewheel.yaml) is used.

  • writable (bool) – Enable users to overwrite the configuration file if this is True. Defaults to False.

Raises:

RuntimeError – If the configuration file is malformed.

config

A dictionary representation of FIREWHEEL’s configuration.

Type:

dict

config_path

The path of the configuration file.

Type:

str, pathlib.Path

__writable

Indicates whether the current Class instantiation can write the existing config to firewheel.yaml. This should be used with caution to ensure that in-memory copies of the config are up-to-date.

Type:

bool

_config_template_path = PosixPath('/home/runner/work/firewheel/firewheel/src/firewheel/config/config-template.yaml')
_default_config_path = PosixPath('/home/runner/work/firewheel/firewheel/src/firewheel/firewheel.yaml')
_load_config_file() → None[source]
_update_minimega_config_value(minimega_config, default_minimega_config_path, minimega_config_parameter, firewheel_config_parameter, description=None)[source]
check_cluster() → None[source]

Synchronize the number of nodes in the cluster with the minimega mesh degree.

This method verifies that the self.config["minimega"]["degree"] matches the total number of nodes in the cluster. If there is a mismatch it is assumed that the cluster config is correct and the minimega degree will be updated accordingly.

Additionally, this method verifies that there is only ONE control node. If there are more (or less), it prints a warning.

check_config() → None[source]

Check various configuration values to ensure correct formatting.

This method call a series of other methods in an effort to correct potential formatting errors. It current calls:

check_minimega_config() → None[source]

Synchronize the minimega configuration with the values in the FIREWHEEL config.

This method verifies that the self.config["minimega"]["base_dir"] and self.config["minimega"]["files_dir"] matches the values in /opt/minimega/misc/daemon/minimega.conf. If there is a mismatch it is assumed that the FIREWHEEL config is correct and the minimega configuration will be updated accordingly.

convert_logging() → None[source]

Convert logging arguments to uppercase if they are a str.

This method checks the type of self.config["logging"]["level"] and verifies that it is an integer. If it is not, it then converts to uppercase and checks that it is the string representation of the common Python Logging Levels. If no logging level is found, this config value is created and set to INFO.

Raises:

TypeError – If the value is not a integer nor one of {“DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”}.

generate_config_from_defaults() → None[source]

Generate a configuration file from the default file template.

get_config() → Dict[str, Any][source]

Get the currently instantiated configuration.

Returns:

The current FIREWHEEL configuration.

Return type:

dict

resolve_get(key: str, space_sep: bool = True) → int | str | bool | Dict[str, int | str | bool] | List[int | str | bool][source]

Get the value of a specific key.

This helper method enables getting the value for a specific configuration key. If a nested key is requested it should be represented using periods to indicate the nesting. This function will return the Python object of the key. Alternatively, if the value if a list, the user can return a space separated string.

Parameters:

  • key (str) – The input key to get in dot notation. This means that nested keys should separated using a period. For example, to get self.config["logging"]["level"] the key would be 'logging.level'.

  • space_sep (bool) – Indicate whether to return list values as a space separated string or as a Python list object. Defaults to True.

Returns:

The value of the specified key.

Return type:

Union[str, int, list, dict]

Examples

To get the value of self.config["cluster"]["compute"] as a space separated string users can run:

>>> # Initialize the config
>>> from firewheel.config import Config
>>> fw_config = Config()
>>> # Initialize the config option
>>> fw_config.config["cluster"]["compute"] = ["host1", "host2", "host3"]
>>> fw_config.resolve_get("cluster.compute")
"host1 host 2 host3"

To get the same key as a Python object users can run:

>>> fw_config.resolve_get("cluster.compute", space_sep=False)
["host1", "host2", "host3"]
resolve_key(key: str) → Tuple[int | str | Dict[str, int | str | bool] | List[int | str | bool] | None, str, Dict[str, int | str | bool | Dict[str, int | str | bool] | List[int | str | bool]]][source]

Identify the configuration key based on a period-separated string.

This method is used by resolve_get() and resolve_set() to identify and return a configuration option based on a key which uses periods to separate dictionary levels. We assume that there is only a single level in the Config.config dictionary. This example would be expected:

{
    "logging": {
        "firewheel_log": "firewheel.log",
        ...
    }
}

Whereas this example is INVALID:

{
    "logging": {
        "files": {
            "firewheel": "firewheel.log",
            ...
        }
    }
}
Parameters:

key (str) – The input key to get in dot notation. This means that nested keys should separated using a period. For example, to get self.config["logging"]["level"] the key would be 'logging.level'.

Returns:

Containing the current value of the found key, the key, and a parent dictionary.

Return type:

tuple

Raises:

  • RuntimeError – If there is not a valid leaf_key.

  • AttributeError – Users can not add top-level attributes to the configuration to prevent accidental configuration modification.

resolve_set(key: str, value: str) → int | str | bool | Dict[str, int | str | bool] | List[int | str | bool][source]

Set the value of a specific key to the given value.

This helper method enables setting the value for a specific configuration key. If a nested key is requested, it should be represented using periods to indicate the nesting. This function will return the newly set value using resolve_get().

Note

This only changes the in-memory copy of the configuration and does NOT actually write the configuration to a file. This is to prevent possible issues with multiple writers.

Parameters:

  • key (str) – The input key to set in dot notation. This means that nested keys should separated using a period. For example, to set self.config["logging"]["level"] the key would be 'logging.level'.

  • value (str) – The new value of the key. This method will automatically attempt to convert that value into the correct Python type.

Returns:

The new value of the specified key.

Return type:

Union[str, int, list, dict]

Raises:

ValueError – If the passed in value type cannot be converted into the type of the previous value.

set_config(new_config: Dict[str, int | str | bool | Dict[str, int | str | bool] | List[int | str | bool]]) → None[source]

Set configuration to the value of the passed-in configuration.

Note

This only changes the in-memory copy of the configuration and does NOT actually write the configuration to a file. This is to prevent possible issues with multiple writers.

Parameters:

new_config (dict) – A new FIREWHEEL configuration dictionary.

Todo

  • In the future, it might be better to validate the incoming configuration with a schema. We could use a tool like Yamale to help with this.

write() → None[source]

Write the current config to firewheel.yaml.

If the user has set enabled write-access, then the current configuration i.e. Config.config will be saved to disk by overwriting firewheel.yaml.

Raises:

PermissionError – If the user has not initialized the instance with write access.