API¶

Configuration Class¶

class skconfig.Configuration(file_locator: Optional[Union[str, ConfigurationLocatorInfo]] = None, subkey=None, macro_precedence_order=('env', 'int'), key_delimiters='/')¶

Class used to provide configuration settings using yaml-based text files.

The configuration extends the yaml syntax so macro values can be encoded in the YAML file. The macro values can either reference other keys elsewhere in the file or environment variables. The intent is to allow users to reference common configuration elements, such as base directories, in one key entry or environment variable.

Attributes:

filename: Returns the filename of the last file read in or written to.
values: Returns direct access to the dictionary of current values used for the configuration settings.

Methods

`as_array`(keyname, **kwargs)	Returns the key value as a numpy array.
`as_float`(keyname)	Returns the key value as a floating point number
`as_int`(keyname)	Returns the key value as an integer
`as_pathname`(keyname)	Returns the key value as a pathname.
`as_string`(keyname)	Returns the key value as a string
`load`(file_locator[, subkey])	Loads the configuration from a yaml file.
`locatorinfo_to_filename`(file_locator)	Finds the filename given by the locator.
`save_registry`(file_locator[, values, ...])	Writes the current configuration (or values) to the yaml file given by the file locator parameter.
`set_key_delimiters`(delimiters)	Sets the list of one character, delimiters used when splitting strings into lists of keys.
`set_macros_precedence_order`(precedence)	Lets the user set the precedence order for processing the expansion of macros.
`set_values`(values)	Sets the internal configuration values to the dictionary passed in by the user.
`subkey`(subkeyname)	Loads a subkey configuration from the current configuration.

__init__(file_locator: Optional[Union[str, ConfigurationLocatorInfo]] = None, subkey=None, macro_precedence_order=('env', 'int'), key_delimiters='/')¶

Initializes and loads yaml based configuration

Parameters:

file_locator: str, :ref:`configurationlocatorinfo`: The information required to locate the yaml file. If it is a string then it is assumed to be the pathname of the file. If it is an instance of ConfigurationLocatorInfo then it is expanded to form a filename. The default value is None, which is useful for creating empty configurations that can be used to save user defined dictionaries.
subkey: str: This is used to load a top-level subkey of the YAML file, if it is loaded. Default is None in which all levels are loaded.
macro_precedence_order: Sequence[str]: The one or two element tuple that describes the order of processing keys during macro expanison. See set_macros_precedence_order() for a complete description. Default is ('env', 'int')
key_delimiters: Sequence[str]: The list of delimiters used to delimit keys when indexing variables in the yaml file. See set_key_delimiters() for a complete description. The default is ('/')

as_array(keyname: Union[str, int], **kwargs) → ndarray¶

Returns the key value as a numpy array. This option only makes sense for configuration values that are sequences or some form.

Parameters:

keyname: str: The configuration key to be looked up.
**kwargs: Dict[str,Any]: any keyword arguments are passed into the call to np.array() and can be used to control the type of array created.

Returns:

np.ndarray: The sequence is converted to a numpy array

as_float(keyname: Union[str, int]) → float¶: Returns the key value as a floating point number

as_int(keyname: Union[str, int]) → int¶: Returns the key value as an integer

as_pathname(keyname: Union[str, int]) → str¶: Returns the key value as a pathname. The string returned from the yaml file is passed through a call to os.path.normpath.

as_string(keyname: Union[str, int]) → str¶: Returns the key value as a string

property filename: str¶: Returns the filename of the last file read in or written to. It will be None if the user supplied the values with a call to set_values().

load(file_locator: Union[str, ConfigurationLocatorInfo], subkey=None) → Dict[str, Any]¶

Loads the configuration from a yaml file. It will search all the given locations until it finds the requested yaml file.

Parameters:

file_locator: str, ConfigurationLocatorInfo: The information required to locate the yaml file. If it is a string then it is assumed to be the pathname of the file. If it is an instance of ConfigurationLocatorInfo then that is expanded to a filename
subkey: str: An optional key that will select one value from the top level key entries in the yaml file.

Returns:

Dict[str,Any]: The dictionary of values read in from the YAML file. None if there was an error loading the YAML file.

locatorinfo_to_filename(file_locator: Union[str, ConfigurationLocatorInfo]) → str¶: Finds the filename given by the locator.

save_registry(file_locator: Union[str, ConfigurationLocatorInfo], values: Optional[Dict[str, Any]] = None, make_directories: bool = True)¶

Writes the current configuration (or values) to the yaml file given by the file locator parameter. This will always erase any existing file but it will not create a new file if the configuration (or values) is empty. It will also create any sub-directories if option make_directories is True.

Parameters:

file_locator: str, ConfigurationLocatorInfo: The information required to locate the yaml file. If it is a string then it is assumed to be the pathname of the file. If it is an instance of ConfigurationLocatorInfo then that is expanded to a filename
subkey: str: An optional key that will select one value from the top level key entries in the yaml file.

set_key_delimiters(delimiters: Tuple[str, str])¶

Sets the list of one character, delimiters used when splitting strings into lists of keys. The default set in the constructor is ('.','/'). This option is provided for users who need to use the default delimiters in their keys stored in the yaml file. We recommend users only use this option as a last resort and should be aware that we do not test this option extensively.

Parameters:

delimiters: Lits or Tuple of str: The array of characters used as delimiters within keys. The default value is ('.','/'). These delimiter values cannot be used in any of the key names stored in the YAML file as they will be improperly parsed and delimited. Note that the delimiters can be used without issue in the values associated with the keys.

set_macros_precedence_order(precedence: Tuple[str, str])¶

Lets the user set the precedence order for processing the expansion of macros. The default value set in the constructor is (‘int’, ‘env’), which instructs the class to first look for macro definitions within the keys of the internal (‘int’) yaml file and if unsuccessful, look for definitions in environment (‘env’) variables.

It is sometimes convenient to change the order to (‘env’, ‘int’) so environment variables can be used to override key settings within the yaml file when expanding macros.

It is also possible, but less common, to set precedence to (‘int’,) to disable all checking of environment variables when expanding macros or to (‘env’,) to disable all checking of internal yaml keys when expanding macros.

Parameters:

precedence: Seqauence[str]: A one or two element sequence of strings. Each string must be one of ‘int’ or ‘env’

set_values(values: Dict[str, Any])¶

Sets the internal configuration values to the dictionary passed in by the user. This dictionary does not have to be compliant with YAML requirements but cannot be written to a yaml file if it is not.

Parameters:

values: Dict[str, Any]: The dictionary of configuration values. This is typically derived from a YAML based system but is not strictly required, all keys of the dictionary and any enclosed dictionaries must be strings.

subkey(subkeyname: str) → Configuration¶

Loads a subkey configuration from the current configuration. This mechanism preserves the capability to resolve macro variables.

Parameters:

subkey: str: An string that selects a child dictionary and preserves the capability to expand macros

Returns:

Configuration: The new configuration/dictionary of values.

property values: Dict[str, Any]¶: Returns direct access to the dictionary of current values used for the configuration settings. This value may be None if no values have been successfully set.

ConfigurationLocatorInfo¶

The ConfigurationLocatorInfo object is a namedtuple that describes where a yaml configuration file is stored on the system. The configuratiuon code currently considers two locations where yaml files can be stored,

The user option specifies a folder specific to the current user that stores configuration for all software executed by the current user. This location is shared by all python environments. On Windows, this is typically the folder C:\Users\<xxxx>\AppData\Local. This location is useful for configuration information that can be shared between different python environments. We use the appdirs package to specify this folder.
The python option specifies a folder specific to the current python environment. For example, on windows this might be folder``C:Users<xxxx>anaconda3envs<python_env>``. This is useful when configuration information is specific to a python environment. We use the python folder returned by sys.exec_prefix/share'./

The configuration software does not implement, multi-user, machine wide configuration.

ConfigurationLocatorInfo(packagename=packagename, groupname=groupname, yamlname=filename, location=locationval)¶

The namedtuple used to create a filename as <location>/<groupname>/<packagename>/yamlname

Parameters:

packagename (str) – The <packagename> component used in the filename generation. This is typically the name of the python package that owns the Configuration information, e.g. altius_l1pp
groupname (str) – The <groupname> component used in the filename generation. This is typically the name of the company or group. e.g. usask-arg
yamlname (str) – The <yamlname> component used in the filename generation. This is the name of the yaml file and typically does not include any directory information, e.g. settings.yaml.
location (str) – Specifies how the the <location> component of the filename is generated. The currently supported values are user and python, which are described above.