lezargus.library.configuration module#

Controls the inputting of configuration files.

This also serves to bring all of the configuration parameters into a more accessible space which other parts of Lezargus can use.

Note these configuration constant parameters are all accessed using capital letters regardless of the configuration file’s labels. Because of this, the names must also obey a stricter set of Python variable naming conventions. Namely, capital letter names and only alphanumeric characters.

There are constant parameters which are stored here which are not otherwise changeable by the configuration file.

lezargus.library.configuration._convert_default_configuration_file(section: str = 'ALL') hint.Iterator[str][source]#

Create a temporary configuration YAML file, returning the path.

See py:func:_convert_default_configuration_yaml for more information.

Parameters:
  • section (str, default) – The section label. We limit the YAML file to the section label subset. By default, we use ALL, the full file.

  • Yeilds

  • ------

  • filename (str) – The filename of the default YAML file, we create it internally then delete it afterwards.

lezargus.library.configuration._convert_default_configuration_yaml(section: str = 'ALL') list[str][source]#

Create a temporary configuration YAML, returning the file lines.

The configuration file by default is a Python file to satisfy the type checker. However, most people will be using YAML files as it is safer. We convert the default configuration file to a YAML file, temporarily within the context manager, to manipulate, and provide to the user.

The configuration file is split into sections based on the section tags. If a section label is provided, we only provide the configuration within the tags.

Parameters:

section (str, default) – The section label. We limit the YAML file to the section label subset. By default, we use ALL, the full file.

Returns:

yaml_lines – The file lines of the configuration YAML file.

Return type:

str

lezargus.library.configuration.apply_configuration(configuration: dict) None[source]#

Apply the configuration, input structured as a dictionary.

Note configuration files should be flat, there should be no nested configuration parameters.

Parameters:

configuration (dict) – The configuration dictionary we are going to apply.

Return type:

None

lezargus.library.configuration.assign_configuration(key: str, value: float | str) None[source]#

Assign the configuration in lezargus.config.

Parameters:
  • key (str) – The configuration key value. If the key value does not exist in the main configuration, then an error is raised as it generally indicates a consistency error.

  • value (int | float | str) – The value of the configuration to be set. Must be a simple type as configuration files should have pretty primitive types.

Return type:

None

lezargus.library.configuration.create_configuration_file(filename: str, section: str = 'ALL', overwrite: bool = False) None[source]#

Create a copy of the default configuration file to the given location.

Parameters:
  • filename (str) – The filename of the new configuration file to be saved, with the extension. An error will be provided if the extension is not a correct extension.

  • section (str) – The section label for us to reduce the scope of the configuration file we will be writing.

  • overwrite (bool, default = False) – If the file already exists, overwrite it. If False, it would raise an error instead.

Return type:

None

lezargus.library.configuration.get_default_configuration(section: str = 'ALL') dict[source]#

Get the default configuration dictionary.

Parameters:

section (str) – The section label for us to reduce the scope of the default configuration provided

Returns:

default_configuration – The total default configuration dictionary.

Return type:

dict

lezargus.library.configuration.load_configuration_file(filename: str) None[source]#

Load a configuration file, then apply it.

Reads a configuration file, the applies it to the current configuration. Note configuration files should be flat, there should be no nested configuration parameters.

Parameters:

filename (str) – The filename of the configuration file, with the extension. Will raise if the filename is not the correct extension, just as a quick check.

Return type:

None

lezargus.library.configuration.read_configuration_file(filename: str) dict[source]#

Read the configuration file and output a dictionary of parameters.

Note configuration files should be flat, there should be no nested configuration parameters.

Parameters:

filename (str) – The filename of the configuration file, with the extension. Will raise if the filename is not the correct extension, just as a quick check.

Returns:

configuration – The dictionary which contains all of the configuration parameters within it.

Return type:

dict

lezargus.library.configuration.sanitize_configuration(configuration: dict) dict[source]#

Sanitize the configuration, conforming it to the Lezargus standards.

Sometimes configurations input by users do not exactly follow the expectations of Lezargus, so, here, we sanitize it as much as we can. Should some level of sanitation fail, then we inform the user.

Parameters:

configuration (dict) – The configuration we are going to sanitize.

Returns:

sanitized_configuration – The configuration, after sanitization.

Return type:

dict

lezargus.library.configuration.sanitize_configuration_key(key: str) str[source]#

Sanitize only the configuration key name.

The key sanitization makes sure that the key follows the below criteria:

  • The key contains only letters and single underscores as word demarcations.

  • The key is all uppercase and is unique across all variations of cases.

Parameters:

key (str) – The configuration key to sanitize.

Returns:

sanitized_key – The key, sanitized.

Return type:

str

lezargus.library.configuration.sanitize_configuration_value(value: hint.Any) int | float | str[source]#

Sanitize only the configuration value to a string.

Value sanitization ensures just three properties:

  • The value in question can be serialized to and from a numeric or string.

  • The value is not a dictionary.

  • The value string can fit on one line.

We need to require strings because that is the format yaml ensures.

Parameters:

value (str) – The configuration value to sanitize.

Returns:

sanitized_value – The value, sanitized.

Return type:

int, float, or str

lezargus.library.configuration.save_configuration_file(filename: str, section: str = 'ALL', overwrite: bool = False) None[source]#

Save the current live configuration to a configuration file.

This function saves the current configuration to a configuration file. The entire configuration file is provided by default to replicate the current settings, but a section tag may be provided.

Parameters:
  • filename (str) – The filename of the configuration file to be saved, with the extension. An error will be provided if the extension is not a correct extension.

  • section (str) – The section label for us to reduce the scope of the configuration file we will be saving.

  • overwrite (bool, default = False) – If the file already exists, overwrite it. If False, it would raise an error instead.

Return type:

None

lezargus.library.configuration.write_configuration_file(filename: str, configuration: dict[str, hint.Any] | None = None, section: str = 'ALL', overwrite: bool = False) None[source]#

Write a configuration file based on provided configuration.

Note configuration files should be flat, there should be no nested configuration parameters. Moreover, we only write configurations present as default or as overwritten by the provided configuration, within the section tag as provided. This function does not account for current live configurations.

Parameters:
  • filename (str) – The filename of the configuration file to be saved, with the extension. An error will be provided if the extension is not a correct extension.

  • configuration (dict, default = None) – The configuration which we will save, along with any defaults present in the main configuration file. If None, only defaults are saved.

  • section (str) – The section label for us to reduce the scope of the configuration file we will be writing.

  • overwrite (bool) – If True, we overwrite the configuration file if already present.

Return type:

None