egse.env

cgse-common

This code is part of the cgse-common package.

egse.env ¶

This module provides functionality to work with and check your environment variables.

The module provides functions to get/set the location of the data storage, the configuration data, and the log files. The locations are determined from the environment variables that are set for the project.

Two important and mandatory environment variables are PROJECT and SITE_ID. The PROJECT environment variable is used to construct the names of the other environment variables that are specific to the project. The SITE_ID environment variable is used in the value that is returned for some the of project specific environment variables.

Mandatory environment variables:

PROJECT: the name of the project, e.g. PLATO, ARIEL. [shall be UPPER case]
SITE_ID: the site identifier, e.g. the lab name or organisation acronym. [shall be UPPER case]

The following environment variables are used by the project:

<PROJECT>_DATA_STORAGE_LOCATION: the root of the data storage location.
<PROJECT>_CONF_DATA_LOCATION: the location of the configuration data.
<PROJECT>_CONF_REPO_LOCATION: the location of the configuration data GitHub repository.
<PROJECT>_LOG_FILE_LOCATION: the location of the log files.
<PROJECT>_LOCAL_SETTINGS: the YAML file that contains site specific local settings.

Do not use the environment variables directly in your code, but use the functions provided by this module to get the locations and settings.

get_data_storage_location(): returns the full path of the data storage location.
get_conf_data_location(): returns the full path of the location of the configuration data.
get_conf_repo_location(): returns the full path of the location of the configuration data repository.
get_log_file_location(): returns the full path of the location of the log files.
get_local_settings(): returns the fully qualified filename of the local settings YAML file.

Warning

These environment variables shall not be changed outside the processes that use them and also not using the os.environ within the code. For the known environment variables, use the dedicated 'setters' that are provided by this module. If there is a need to change the environment variables, e.g. in unit tests, make sure to call the egse.env.initialize() to reset the proper state.

Functions:

Name	Description
`env_var`	Context manager to run some code that need alternate settings for environment variables.
`get_conf_data_location`	Returns the full path of the location of the configuration data for the site id.
`get_conf_data_location_env_name`	Returns the name of the environment variable for the project.
`get_conf_repo_location`	Returns the fully qualified name of the location of the repository with
`get_conf_repo_location_env_name`	Returns the name of the environment variable for the project.
`get_data_storage_location`	Returns the full path of the data storage location for the given site_id.
`get_data_storage_location_env_name`	Returns the name of the environment variable for the project.
`get_local_settings_env_name`	Returns the name of the environment variable for the project.
`get_local_settings_path`	Returns the fully qualified filename of the local settings YAML file. When the local settings environment
`get_log_file_location`	Returns the full path of the location of the log files. The log file location is read from the environment
`get_log_file_location_env_name`	Returns the name of the environment variable for the project.
`get_project_name`	Get the PROJECT name. Return None when the PROJECT is not set.
`get_site_id`	Get the SITE_ID. Return None if the SITE_ID is not set.
`set_conf_data_location`	Sets the environment variable and the internal representation to the given value.
`set_conf_repo_location`	Sets the environment variable and the internal representation to the given value.
`set_data_storage_location`	Sets the environment variable and the internal representation to the given value.
`set_local_settings`	Sets the environment variable and the internal representation to the given value.
`set_log_file_location`	Sets the environment variable and the internal representation to the given value.

NoValue ¶

Represents a no value object, an environment variable that was not set.

The truth value of this object is always False, and it is equal to any other NoValue object.

env_var ¶

env_var(**kwargs)

Context manager to run some code that need alternate settings for environment variables. This will automatically initialize the CGSE environment upon entry and re-initialize upon exit.

Note

This context manager is different from the one in egse.system because of the CGSE environment changes.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	dictionary with environment variables that are needed	`{}`

Example

from egse.env import env_var
with env_var(PLATO_DATA_STORAGE_LOCATION="/Users/rik/data"):
    # do stuff that needs these alternate setting
    ...

get_conf_data_location ¶

get_conf_data_location(site_id=None)

Returns the full path of the location of the configuration data for the site id.

If the site_id is None, it is determined from the environment variable SITE_ID.

When the ${PROJECT}_CONF_DATA_LOCATION environment variable is not set, the configuration data location will be the ${PROJECT}_DATA_STORAGE_LOCATION + '/conf'.

Parameters:

Name	Type	Description	Default
`site_id`	`str`	the site identifier (to be used instead of the SITE_ID environment variable)	`None`

Returns:

Type	Description
`str`	The full path of location of the configuration data as a string.

Raises:

Type	Description
`ValueError`	when the SITE_ID or the `${PROJECT}_DATA_STORAGE_LOCATION` is not set.

get_conf_data_location_env_name ¶

get_conf_data_location_env_name()

Returns the name of the environment variable for the project.

get_conf_repo_location ¶

get_conf_repo_location()

Returns the fully qualified name of the location of the repository with configuration and calibration data.

Returns None if no environment variable was defined or if the location doesn't exist. In both cases a Warning is issued.

get_conf_repo_location_env_name ¶

get_conf_repo_location_env_name()

Returns the name of the environment variable for the project.

get_data_storage_location ¶

get_data_storage_location(site_id=None)

Returns the full path of the data storage location for the given site_id.

If the site_id is None, it is determined from the environment variable SITE_ID.

If the ${PROJECT}_DATA_STORAGE_LOCATION environment variable does not end with the site_id, the site_id will be appended to the path on return. That means the actual data storage location will always be site specific.

Note

when you specify the site_id as an argument, it takes precedence over the SITE_ID environment variable.

Parameters:

Name	Type	Description	Default
`site_id`	`str`	the site identifier (to be used instead of the SITE_ID environment variable)	`None`

Returns:

Type	Description
`str`	The full path of data storage location as a string.

Raises:

Type	Description
`ValueError`	when the SITE_ID or the ${PROJECT}_DATA_STORAGE_LOCATION is not set.

get_data_storage_location_env_name ¶

get_data_storage_location_env_name()

Returns the name of the environment variable for the project.

get_local_settings_env_name ¶

get_local_settings_env_name()

Returns the name of the environment variable for the project.

get_local_settings_path ¶

get_local_settings_path()

Returns the fully qualified filename of the local settings YAML file. When the local settings environment variable is not defined or is an empty string, None is returned.

Warning

The function will generate a warning when

When the local settings environment variable is not defined, or
when the path defined by the environment variable doesn't exist.

get_log_file_location ¶

get_log_file_location(site_id=None)

Returns the full path of the location of the log files. The log file location is read from the environment variable ${PROJECT}_LOG_FILE_LOCATION. The location shall be independent of any setting that is subject to change.

If the environment variable is not set, a default log file location is created from the data storage location as follows: <PROJECT>_DATA_STORAGE_LOCATION/<SITE_ID>/log.

Parameters:

Name	Type	Description	Default
`site_id`	`str`	the site identifier	`None`

Returns:

Type	Description
`str`	The full path of location of the log files as a string.

Raises:

Type	Description
`ValueError`	when the SITE_ID or the ${PROJECT}_DATA_STORAGE_LOCATION is not set.

get_log_file_location_env_name ¶

get_log_file_location_env_name()

Returns the name of the environment variable for the project.

get_project_name ¶

get_project_name()

Get the PROJECT name. Return None when the PROJECT is not set.

get_site_id ¶

get_site_id()

Get the SITE_ID. Return None if the SITE_ID is not set.

initialize ¶

initialize()

Initialize the environment variables that are required for the CGSE to function properly. This function will print a warning if any of the mandatory environment variables is not set.

This function is automatically called on import and can be called whenever the environment variables have been changed, e.g. in unit tests.

print_env ¶

print_env()

Prints out the mandatory and known environment variables at the time of the function call. The function and lineno is also printed for information.