egse.settings

The Settings class handles user and configuration settings that are provided in a YAML file.

The idea is that settings are grouped by components or any arbitrary grouping that makes sense for the application or for the user. Settings are also modular and provided by each package by means of entry-points. The Settings class can read from different YAML files.

By default, settings are loaded from a file called settings.yaml, but this can be changed in the entry-point definition.

The yaml configuration files are provided as entry points by the packages that specified an entry-point group 'cgse.settings' in the pyproject.toml. The Settings dictionary (attrdict) is constructed from the configuration YAML files from each of the packages. Settings can be overwritten by the next package configuration file. So, make sure the group names in each package configuration file are unique.

The YAML file is read and the configuration parameters for the given group are available as instance variables of the returned class.

The intended use is as follows:

from egse.settings import Settings

dsi_settings = Settings.load("DSI")

if 0x000C <= dsi_settings.RMAP_BASE_ADDRESS <= 0x00FF:
    ...  # do something here
else:
    raise RMAPError("Attempt to access outside the RMAP memory map.")

The above code reads the settings from the default YAML file for a group called DSI. The settings will then be available as variables of the returned class, in this case dsi_settings. The returned class is and behaves also like a dictionary, so you can check if a configuration parameter is defined like this:

if "DSI_FEE_IP_ADDRESS" not in dsi_settings:
    # define the IP address of the DSI

The YAML section for the above code looks like this:

DSI:

    # DSI Specific Settings

    DSI_FEE_IP_ADDRESS  10.33.178.144   # IP address of the DSI EtherSpaceLink interface
    LINK_SPEED:                   100   # SpW link speed used for both up- and downlink

    # RMAP Specific Settings

    RMAP_BASE_ADDRESS:     0x00000000   # The start of the RMAP memory map managed by the FEE
    RMAP_MEMORY_SIZE:            4096   # The size of the RMAP memory map managed by the FEE

When you want to read settings from another YAML file, specify the filename= keyword. If that file is located at a specific location, also use the location= keyword.

my_settings = Settings.load(filename="user.yaml", location="/Users/JohnDoe")

The above code will read the YAML file from the given location and not from the entry-points.

Classes:

Name	Description
`Settings`	The Settings class provides a load() method that loads configuration settings for a group
`SettingsError`	A settings-specific error.

Functions:

Name	Description
`load_global_settings`	Loads the settings that are defined by the given entry_point. The entry-points are defined in the
`load_local_settings`	Loads the local settings file that is defined from the environment variable PROJECT_LOCAL_SETTINGS (where
`load_settings_file`	Loads the YAML configuration file that is located at `path / filename`.
`read_configuration_file`	Read the YAML input configuration file. The configuration file is only read

Settings ¶

The Settings class provides a load() method that loads configuration settings for a group into a dynamically created class as instance variables.

Methods:

Name	Description
`load`	Load the settings for the given group. When no group is provided, the
`to_string`	Returns a simple string representation of the cached configuration of this Settings class.

load `classmethod` ¶

load(
    group_name=None,
    filename="settings.yaml",
    location=None,
    *,
    add_local_settings=True,
    force=False,
)

Load the settings for the given group. When no group is provided, the complete configuration is returned.

The Settings are loaded from entry-points that are defined in each of the packages that provide a Settings file.

If a location is explicitly provided, the Settings will be loaded from that location, using the given filename or the default (which is settings.yaml).

Parameters:

Name	Type	Description	Default
`group_name`	`str`	the name of one of the main groups from the YAML file	`None`
`filename`	`str`	the name of the YAML file to read [default=settings.yaml]	`'settings.yaml'`
`location`	`(str, Path)`	the path to the location of the YAML file	`None`
`force`	`bool`	force reloading the file	`False`
`add_local_settings`	`bool`	update the Settings with site specific local settings	`True`

Returns:

Type	Description
`attrdict`	a dynamically created class with the configuration parameters as instance variables.

Raises:

Type	Description
`SettingsError`	when the group is not defined in the YAML file.

to_string `classmethod` ¶

to_string()

Returns a simple string representation of the cached configuration of this Settings class.

SettingsError ¶

Bases: Exception

A settings-specific error.

load_global_settings ¶

load_global_settings(
    entry_point="cgse.settings", force=False
)

Loads the settings that are defined by the given entry_point. The entry-points are defined in the pyproject.toml files of the packages that export their global settings.

Parameters:

Name	Type	Description	Default
`entry_point`	`str`	the name of the entry-point group [default: 'cgse.settings']	`'cgse.settings'`
`force`	`bool`	force reloading the settings, i.e. ignore the cache	`False`

Returns:

Type	Description
`attrdict`	A dictionary (attrdict) containing a collection of all the settings exported by the packages through the given entry-point.

load_local_settings ¶

load_local_settings(force=False)

Loads the local settings file that is defined from the environment variable PROJECT_LOCAL_SETTINGS (where PROJECT is the name of your project, defined in the environment variable of the same name).

This function might return an empty dictionary when

the local settings YAML file is empty
the local settings environment variable is not defined.

in both cases a warning message is logged.

Raises:

Type	Description
`SettingsError`	when the local settings YAML file is not found. Check the PROJECT_LOCAL_SETTINGS environment variable.

Returns:

Type	Description
`attrdict`	A dictionary (attrdict) with all local settings.

load_settings_file ¶

load_settings_file(path, filename, force=False)

Loads the YAML configuration file that is located at path / filename.

Parameters:

Name	Type	Description	Default
`path`	`PATH`	the folder where the YAML file is located	required
`filename`	`str`	the name of the YAML configuration file	required
`force`	`bool`	force reloading, i.e. don't use the cached information	`False`

Raises:

Type	Description
`SettingsError`	when the configuration file doesn't exist or cannot be found or when there was an error reading the configuration file.

Returns:

Type	Description
`attrdict`	A dictionary (attrdict) with all the settings from the given file.

Note

in case of an empty configuration file, and empty dictionary is returned and a warning message is issued.

read_configuration_file ¶

read_configuration_file(filename, *, force=False)

Read the YAML input configuration file. The configuration file is only read once and memoized as load optimization.

Parameters:

Name	Type	Description	Default
`filename`	`Path`	the fully qualified filename of the YAML file	required
`force`	`bool`	force reloading the file, even when it was memoized	`False`

Raises:

Type	Description
`SettingsError`	when there was an error reading the YAML file.

Returns:

Type	Description
`dict`	a dictionary containing all the configuration settings from the YAML file.

egse.settings

Settings ¶

load classmethod ¶

to_string classmethod ¶

SettingsError ¶

load_global_settings ¶

load_local_settings ¶

load_settings_file ¶

read_configuration_file ¶

load `classmethod` ¶

to_string `classmethod` ¶