Handling user configuration

The envprobe.settings package implements classes that deal with handling configuration that is specific to the user, or a particular shell.

Configuration files are put under the modifying persistent configuration directory of the user, as given by the following function.

get_configuration_directory()

Returns the location where Envprobe’s user-specific configuration files are stored.

This method uses $XDG_CONFIG_HOME as per FreeDesktop specifications, if exists. Otherwise, the .config directory under the user’s HOME will be used.

Abstract configuration files

The ConfigurationFile class allows accessing a key-value mapping (dict) of configuration objects that is saved to the user’s file system to a JSON file.

class ConfigurationFile(file_path, default_content=None, read_only=False, file_mode=384, directory_mode=448)

A glorified dict that is backed into a JSON file and locked on access.

This class embeds file locking logic to ensure atomic access to the backing file is given.

Initialise a configuration file.

Parameters

  • file_path (str) – The path of the backing file of the configuration storage.

  • default_content (dict, optional) – The contents of the configuration if the backing file does not exist.

  • read_only (bool, optional) – Whether the configuration is opened read-only. Creating the configuration read-only will prevent any changes from being applied from Python code, and will also prevent the backing file from writing.

  • file_mode (int, optional) – If the backing file does not exist, it will be created with the mode flags given. Defaults to owner read, write, no execute permission, or permissions for group and world.

  • directory_mode (int, optional) – If the directory where the backing file should be put does not exist, it will be created with the mode flags given. Defaults to owner read, write, list, no permission for group and world.

__contains__(key)

Returns if the data in memory contains key.

__delitem__(key)

Deletes the key.

__enter__()

Acquires the backing file, read its contents, and return a context where the ConfigurationFile can be used.

Returns

The self instance.

Return type

ConfigurationFile

Note

This method should be used instead of load() and save() if a changing access to the contents is expected, as the context keeps the lock on the file active throughout.

__exit__(exc_type, exc_value, traceback)

Saves the changes to the current file (if not read-only) and releases the lock.

__getitem__(key)

Retrieves the element for key.

__iter__()

Returns an iterator over the data loaded to memory.

__len__()

Returns the number of keys in memory.

__setitem__(key, value)

Sets the element for key to value.

property changed

Returns whether the data in memory changed since the last save or load.

get(key, default=None)

Returns the data in memory for key, or if no key found, default.

load()

Load the contents of the backing file into memory.

Warning

After the file’s contents are loaded into memory, the lock is released, meaning that subsequent changes in the file might be overwritten if save() is called with the current contents!

If you intend to change the configuration and save it, use ConfigurationFile as a context manager instead.

save()

Save the contents of memory to the backing file.

Raises

io.UnsupportedOperation – Raised if the file was opened read_only, but save is called.

Warning

The file’s contents are overwritten by this method after acquiring the lock, destroying potential changes that might have been written before. The lock is released afterwards immediately.

If you intend to change the configuration in one go, use ConfigurationFile as a context manager instead.