config module

Classes for discovering and parsing configuration and other files.

class ctlbase.config.CallerDiscovery(suffixPatternStr='(?:ctl|)(?:\\.py|\\.pyc|\\.pyo|)$', excludeBasenamePatternStr=None)

Discovers the Python module using this class, referred to as “caller”.

As an example, if a Python module is made up of file curtainctl.py and calls findName(), the method will return curtain as the caller’s normalized module name. It can be used as a component in other file names like etc/curtain to enable auto-discovery of related files.

The following rules are applied by default:

  • The suffixes .py, .pyc and .pyo are stripped from the Python module’s file name if present.

  • A possibly remaining suffix ctl – standing for a CLI utility “controlling” some other resource – is stripped from the file name.

Discovery is done by examining the Python stackframe when a method of this class is called.

As a singleton, this class is supposed to be instantiated once per Python process. This allows to set one configuration and to maintain one cache globally for the entire Python process.

If you do not want to use the default configuration for discovery, set SINGLETON to an instance of CallerDiscovery that has the desired configuration.

__init__(suffixPatternStr='(?:ctl|)(?:\\.py|\\.pyc|\\.pyo|)$', excludeBasenamePatternStr=None)

Initializes a CallerDiscovery instance with a specific configuration.

Parameters:

  • suffixPatternStr (str) – A regex pattern applied to the end of a Python module’s file name (without the path). If it matches, it is removed from the file name to form the caller’s normalized module name.

  • excludeBasenamePatternStr (str) – A regex pattern applied to a Python module’s file name (without the path). If the pattern matches, the corresponding module is skipped in the call hierarchy, i.e. not considered as a caller. Defaults to the module names contained in the ctlbase package. That is, any module within ctlbase calling a method of CallerDiscovery will not be considered as a caller.

static findName()

Discovers the caller of this method and returns its normalized module name.

Discovery and normalization depends on the configuration set for the CallerDiscovery singleton.

static findPath()

Discovers the caller of this method and returns its source file path.

Discovery depends on the configuration set for the CallerDiscovery singleton.

class ctlbase.config.FileDiscovery

Discovers files in a set of well-known directories.

BIN_LOCATIONS = ('.', 'bin', '/usr/bin', '/usr/sbin', '/usr/local/bin')

Well-known directory paths for executable files. May contain both relative and absolute paths.

CONFIG_LOCATIONS = ('etc/default', 'etc', '/etc/default', '/etc')

Well-known directory paths for configuration files. May contain both relative and absolute paths.

TRANSLATION_LOCATIONS = ('locales',)

Well-known directory paths for translation files. May contain both relative and absolute paths.

class Type(value)

The type of a file to discover.

BIN = 'binary'

An executable file on the host system.

CONFIG = 'config'

A configuration file.

TRANSLATION = 'language'

A translation file for a specific language.

static find(filePath, fileType, isStartFromCallerPath=True, isStartFromScriptPath=True)

Tries to discover a file with the given parameters in a set of well-known directories.

The available sets of directories are defined by CONFIG_LOCATIONS, BIN_LOCATIONS and TRANSLATION_LOCATIONS. The actual set is determined by the fileType parameter.

Relative path specifications in those sets are applied up the directory tree until the file is found or the root of the file system is reached. For instance, if the search for a configuration file named file_1.conf starts at the directory /home/myuser/myapp/, the existence of /home/myuser/myapp/etc/default/file_1.conf is checked first, then /home/myuser/etc/default/file_1.conf, then /home/etc/default/file_1.conf and so on.

An eligible target file must be accessible to the current user. That is, it must be readable, or, in the case of an executable file, be executable for the current user.

If you want to avoid the runtime overhead of auto-discovery, provide an absolute path in filePath.

Parameters:

  • filePath (str | True) – The file name of the searched file. It may include a relative or absolute path specification. In the latter case, the given path is resolved to its real path in the file system and returned if and only if it is accessible to the current user. It may be True for discovering a file based on the caller’s normalized module name. See CallerDiscovery for details.

  • fileType (Type) – The type of the file to search for. It determines the set of well-known directories to use.

  • isStartFromCallerPath (bool) – If True, relative path specifications are treated relative to the caller’s source file path as returned by findPath().

  • isStartFromScriptPath (bool) – If True, relative path specifications are treated relative to the current script’s path as returned by sys.argv[0], if applicable. isStartFromCallerPath takes precedence.

Returns:

The absolute real path of the file if found.

Return type:

str

Raises:

FileNotFoundError – If the file could not be found or is inaccessible to the current user.

static findBinary(filePath, isStartFromCallerPath=True, isStartFromScriptPath=True)

Convenience method for finding configuration files.

Corresponds to the BIN type.

The parameters have the same meanings as with find().

static findConfig(filePath, isStartFromCallerPath=True, isStartFromScriptPath=True)

Convenience method for finding configuration files.

Corresponds to the CONFIG type.

The parameters have the same meanings as with find().

static findTranslation(filePath, lng=None, isStartFromCallerPath=True, isStartFromScriptPath=True)

Convenience method for finding configuration files.

Corresponds to the TRANSLATION type.

Parameters:

lng (str) – A two-letter language code for the translation file to find, e.g. de. If given, If filePath must only be a file name without a path.

The other parameters have the same meanings as with find().

class ctlbase.config.BashConfig

Discovers and parses a configuration file with a basic Bash syntax for variable declarations.

In configuration files, the following common environment variables are interpolated:

  • $$: The process ID (PID) of the current process.

  • $EUID: The effective user ID of the user executing the process.

  • HOME: The home directory of the user executing the process.

  • PPID: The process ID of the parent process of the current process.

  • PWD: The current working directory.

  • UID: The user ID of the user executing the process.

Within the configuration file, former variables are interpolated in later variables. As an example, if FILE_INDEX=1 is followed by FILE_NAME=file_$FILE_INDEX.conf, then FILE_NAME is resolved to file_1.conf. Curly brace syntax is supported, i.e. $FILE_INDEX is equivalent to ${FILE_INDEX}.

Regarding data types, values are parsed as follows:

  • Integer literals declared with declare -i are cast to int.

  • String literals enclosed in ' or " are cast to str, including spaces.

  • Array literals starting with ( and ending with ) are cast to list unless …

  • … they contain entries in the form [key]=value. Then they are cast to dict.

static parse(configPath, interpolationDict={})

Discovers a Bash-like configuration file and parses it into a dict if found.

Relative path specifications are treated relative to the caller’s source file path as returned by findPath() and relative to the current script’s path as returned by sys.argv[0], if applicable. The former takes precedence.

Parameters:

  • configPath (str | True) – The file name of the configuration file. It may include a relative or absolute path specification. It may be True for discovering a configuration file based on the caller’s normalized module name. See CallerDiscovery for details.

  • interpolationDict (dict | None) – An additionl dict used for variable interpolation. As an example, if the dict contains a key MY_INDEX, its value will substitute all occurrences of $MY_INDEX and ${MY_INDEX} in the configuration file.

Returns:

A dict containg the Bash-like variables names as keys and their parsed values as values.

Return type:

dict