mode module

Low-level classes for mode handling.

For the core concepts of mode handling see the control module.

Controls should use the high-level Mode methods of Control.

Classes

class ctlbase.mode.ModeDirHelper

Static functions for dealing with mode directories, i.e. directories where modes are tracked.

static find(dirName, isUseCallerName=True, isUseScriptName=True)

Tries to find a mode directory with the given parameters.

An eligible mode directory must be writable to the current user.

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

Parameters:

• dirName (str | True) – The mode directory name. It may include a relative or absolute path specification. True for auto-discovery.

• isUseCallerName (bool) – If True, the caller’s normalized module name is used as a directory name, as returned by getName(). Only relevant if dirName is True.

• isUseScriptName (bool) – If True, the current script’s normalized module name is used as a directory name, based on sys.argv[0]. Only relevant if dirName is True. isUseCallerName takes precedence.

Returns:

The absolute real path of the directory if found.

Return type:

str

Raises:

FileNotFoundError – If the directory could not be found or is not writable for the current user.

class ctlbase.mode.FileModeHandler(dirPath=None)

A mode handler using text files for persistence.

__init__(dirPath=None)

Creates a new mode handler operating in a specific directory.

Parameters:

dirPath (str) – The path to the mode directory. It may be specified as described under dirName.Normally, a directory in a tmpfs is sufficient. If modes should survive system reboots, choose a directory on a persistent file system.

activatePending()

Activates the pending mode by renaming the pending mode file with the most current modification time.

Also removes the files of expired pending modes.

Raises:

RuntimeError – If there is no pending mode that could be activated.

Returns:

The activate mode.

Return type:

str

getActive()

Retrieves the active mode by reading the active mode file.

Returns:

The active mode if set, otherwise none (str).

Return type:

str

getPending()

Retrieves the pending mode by identifying and reading the pending mode file with the most current modification time.

Also removes the files of expired pending modes.

Returns:

The pending mode if set, otherwise none (str).

Return type:

str

setActive(mode, group=None)

Sets the active mode by creating an active mode file or overwriting an existing one.

If group is not None, the group ownership is only set if the current user is the owner of the mode directory and file, respectively. Otherwise, the ownership is left unmodified.

Parameters:

• mode (str) – The mode to set. Passing an empty str or none is equivalent to calling unsetActive().

• group (str | None) – The group ownership to be set on the mode directory and file. Accepts a group name or numerical group ID (gid).

Raises:

ValueError – If the given group does not exist.

Returns:

True if the mode was set, False if it was unset.

Return type:

bool

setPending(mode, timeout_s=-1, group=None)

Sets the pending mode by creating a new pending mode file.

If group is not None, the group ownership is only set if the current user is the owner of the mode directory and file, respectively. Otherwise, the ownership is left unmodified.

Parameters:

• mode (str) – The mode to set. Passing an empty str or none is equivalent to calling unsetPending().

• timeout_s (int | None) – The mode timeout in seconds. If -1, the value of TIMEOUT_DEFAULT_S is assumed. Passing 0 is equivalent to calling unsetPending().

• group (str | None) – The group ownership to be set on the mode directory and file. Accepts a group name or numerical group ID (gid).

Raises:

ValueError – If the given group does not exist.

Returns:

True if the mode was set, False if it was unset.

Return type:

bool

unsetActive()

Unsets the active mode by deleting the active mode file if it exists.

Removes the mode directory if no files are left.

unsetPending()

Unsets the pending mode by deleting all existing pending mode files.

Removes the mode directory altogether if no files are left.

Constants and defaults

ctlbase.mode.TIMEOUT_DEFAULT_S = 30

Default timeout for a pending mode in seconds.

ctlbase.mode.BASE_DIR_PATH_DEFAULT = '/tmp'

Default base directory under which mode directories are created.