gitws.appconfig module

Application Configuration Handling.

This module implements the needed classes to handle persistent application settings. The core part of the configuration system is the AppConfig class, which allows easy access to options spread across several configuration files. In addition, that class also allows to read and write dedicated config files.

class gitws.appconfig.AppConfig(system_config_dir: Optional[str] = None, user_config_dir: Optional[str] = None, workspace_config_dir: Optional[str] = None, use_config_from_env: bool = True)[source]

Bases: object

Application wide configuration.

This class holds the application wide configuration and also provides means to modify it.

In the simplest case, default construct this class to gain access to the options defined in the various configuration files:

config = AppConfig()
options = config.options
# Now we can use the values defined in the options

Alternatively, the two methods load and save can be used to load and save configuration files explicitly.

By default, three configuration files will be loaded and merged:

  • A system wide configuration file.

  • A configuration file specific for the current user.

  • And a configuration file for the current workspace.

In case the current directory is not within a workspace (and no path to a workspace has been explicitly set in the constructor), the workspace configuration file is skipped. In any case, the configurations are merged in that order, i.e. options from the system configuration file have the lowest priority, while the ones from the workspace have highest priority.

On top, the class will also evaluate environment variables named GIT_WS_* and allow overriding configuration values that way. For example, the manifest_path option can be explicitly overridden by setting the GIT_WS_MANIFEST_PATH environment variable.

Keyword Arguments:

  • system_config_dir – The path to where the system configuration file is stored. If not set, a platform specific system configuration path will be used.

  • user_config_dir – The path to where the user configuration file is stored. If not set, a platform specific user configuration path will be used.

  • workspace_config_dir – The path to where the workspace configuration file is stored. If not set, the path will be looked up by searching from the current directory upwards for a workspace configuration folder. If none is found, no workspace configuration will be used.

  • use_config_from_env – If set to False, reading of environment variables to override configuration values will be skipped.

edit(location: AppConfigLocation) → Iterator[AppConfigData][source]

Edit a configuration file.

This method can be used to conveniently edit a configuration file:

with app_config.edit(AppConfigLocation.WORKSPACE) as cfg:
    cfg.color_ui = False

It basically combines load and save into a single method call which can be used with a with statement.

get_config_file_path(location: AppConfigLocation) → Path[source]

Given a storage location, return the path to the config file.

Raises:

InvalidConfigurationLocationError – The location given is invalid.

load(location: AppConfigLocation) → AppConfigData[source]

Load the configuration from the specified location.

This method will load the configuration values from the given location. Note that only that location’s config file values will be included. For productive use, rather read the merged values via the options property.

The main purpose of this method is to obtain a copy of the current configuration values from a specific configuration file, modify them and then write them back via save.

Parameters:

location – The location to load the configuration from.

Raises:
property options: AppConfigData

Access the merged application configuration.

This property holds the merged configuration options of the application. It is computed by loading the system, user and - if we are within a workspace - workspace configuration as well as - if enabled - the configurations read from environment variables and merging them together in that order.

# Create a configuration object:
config = AppConfig()

# Now, we can use the options to access the configured values:
if config.options.color_ui:
    # Print using color
else:
    # Print without additional styling

Note that the value is computed on first access, meaning that accessing this property can potentially raise an exception. See the documentation of the load method to learn which exceptions are expected.

Also note that the value is cached between accesses. Once the AppConfig object is created and this property is read once, its value will be reused between calls. An exception is when modifying configuration values using save. In this case, the currently merged configurations are discarded and re-read on the next access of this property.

save(config: AppConfigData, location: AppConfigLocation)[source]

Save the configuration back to disk.

This saves the given configuration back to a file on disk. Use it together with the load method to modify configuration values on disk:

config = AppConfig()

# Load configuration values from disk:
values = config.load(AppConfigLocation.WORKSPACE)

# Request not to color output
values.color_ui = False

# Request using the default manifest by unsetting whatever is in workspace config
values.manifest_path = None

# Save values back:
config.save(AppConfigLocation.WORKSPACE)
Parameters:

  • config – The configuration options to be saved to disk.

  • location – The location where to store.

Raises:
class gitws.appconfig.AppConfigLocation(value)[source]

Bases: str, Enum

The location where configuration options are stored.

This enum encodes the different locations where the application stores information.

SYSTEM = 'system'

System wide configuration.

Use this to refer to configuration options for the entire system.

USER = 'user'

User configuration.

Use this to refer to configuration specific to the current user.

WORKSPACE = 'workspace'

Workspace configuration.

Use this to refer to configuration specific to the current workspace (if any). By default, the workspace configuration is looked for in the GIT_WS_PATH path within the workspace we are located in. The workspace location is retrieved by using Workspace.find_path.