config module

Classes for discovering and parsing configuration and other files.

Classes

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

An inspector for the so-called caller, i.e. the Python module topmost in the call stack.

The caller is determined by iterating the call stack, checking the corresponding module file names against a blacklist. By default the list is made up of all the module names in the ctlbase package.

Once the caller is determined, its normalized name is obtained by applying a regex pattern to its module file name, without the path specification.

As an example using the default pattern, a Python module /usr/local/bin/screenctl.py results in the normalized name screen. It can be used as a component in related file names like etc/screen. This in turn facilitates the auto-discovery of related files.

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

Creates a caller inspector with a specific configuration.

Parameters:

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

  • blacklistPatternStr (str | None) – A regex pattern applied to a Python module’s file name. If the pattern matches, the corresponding module skipped in the call hierarchy, i.e. not considered a caller. If None, a pattern matching the module names in the ctlbase package is used.

getName()

Determines the caller and obtains its normalized name.

Returns:

The caller’s normalized name.

Return type:

str

getPath()

Determines the caller and obtains its file path.

Returns:

The caller’s real path including the absolute path and file name.

Return type:

str

class ctlbase.config.FileHelper

Static functions for dealing with files.

class Type(value)

The type of a file.

BIN = 'binary'

An executable file.

CONFIG = 'config'

A configuration file.

TRANSLATION = 'language'

A translation file for a specific language.

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

Tries to find 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.

To avoid the runtime overhead of auto-discovery, provide an absolute path in fileName.

Parameters:

  • fileName (str | True) – The file name of the searched file. It may include a relative or absolute path specification. True for auto-discovery.

  • 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 file path as returned by getPath(). What is more, if fileName is True, the caller’s normalized module name is used as a file name.

  • isStartFromScriptPath (bool) – If True, relative path specifications are treated relative to the current script’s path, based on sys.argv[0]. What is more, if fileName is True, the script’s normalized module name is used as a file name. 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(fileName, 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(fileName, 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(fileName, 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 fileName must only be a file name without a path.

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

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 ctlbase.config.BashHelper

Static functions for dealing with Bash-style configuration files.

That is, Bash-style variable assignments are supported, including interpolation of the following environment variables:

  • $$: 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.

class Array(value)

An enumeration.

class Scalar(value)

An enumeration.

static parseConfig(configName, interpolationDict={})

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

Parameters:

  • configName (str | True) – The configuration file name. It may include a relative or absolute path specification. True for auto-discovering a configuration file based on the caller’s normalized module name as returned by getName(). See find() for the discovery algorithm.

  • 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

Constants and defaults

ctlbase.config.Caller = <ctlbase.config.CallerInspector object>

Singleton for inspecting the caller.

ctlbase.config.TRUE_VALUE_PATTERN = re.compile('^(?:1|yes|true)$', re.IGNORECASE)

Regular expression for str values to be treated as True.

ctlbase.config.FALSE_VALUE_PATTERN = re.compile('^(?:0|no(?:ne)?|false)$', re.IGNORECASE)

Regular expression for str values to be treated as False.