configuration

A collection of classes and functions for dealing with configuration data. There are two main types of configuration data: the dict configuration itself, and the ConfigSpec.

The configuration is represented by Dict(str, Any), where the string key represents the config point’s name, pointing to a value that may be of any type.

The ConfgSpec is a collection of ConfigPoints. Each ConfigPoint consists of a name and description of the valid values that it may have. There are several different types of COnfigPoints available.

class configuration.BooleanConfigPoint(name: str, default: bool)

A ConfigPoint that allows True/False values.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to look up the configured value.

  • default – The default value

validate(value) → Validation

Validates the given value with this ConfigPoint. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

class configuration.ChoiceConfigPoint(name: str, choices: List, default)

A ConfigPoint that requires selection from a limited number of choices. The default value must exist in the given choices.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • choices – A List of all of the valid choices for this ConfigPoint

  • default – The default value

validate(value) → Validation

Validates the given value with this ConfigPoint. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

class configuration.ConfigFile

A class containing functions for dealing with configuration files.

static config_filename(cls)

Returns the filename for the config file for the given class.

static delete_config(cls)

Deletes the config file, effectively resetting to defaults.

static load_config(cls, config_spec: ConfigSpec)

If this class has config points, this method validates and returns the ConfigSettings object representing the class’s config file. Otherwise an empty ConfigSettings object is returned.

static save_config(cls, data: dict)

Take config as a dict and save to this class’s config file.

Note

Be mindful of how often _save_config() is called because writing to disk too often can slow down the performance of your script. Only call save state when state has changed and consider adding a time since last save check to reduce save frequency.

class configuration.ConfigPoint(name: str, type: str, default)

Base class for defining ConfigPoint types.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • type – The name of this ConfigPoint’s type

  • default – The default value

validate(value) → Validation

Validates the given value with this ConfigPoint. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

class configuration.ConfigSettings(d)

Collects the configuration settings into an object with attributes instead of a dict with keys

validate_key(key)

Ensures that a dict key is a valid attribute name

@param key The string to check @return True if the key is valid. Otherwise an exception is raised

@exception ValueError if the key contains invalid characters; only letters, numbers, hyphens, and underscores

are permitted. They key cannot be length 0, nor can it begin with a number

class configuration.ConfigSpec(config_points: List[ConfigPoint])

A container for ConfigPoints representing the set of configuration options for a specific script.

default_config()

Returns the default configuration for this spec.

validate(configuration) → Validation

Validates the given configuration with this spec. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

class configuration.FloatConfigPoint(name: str, minimum: float, maximum: float, default: float)

A ConfigPoint that requires the selection from a range of floats. The default value must lie within the specified range

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • minimum – The minimum allowed value

  • maximum – The maximum allowed value

  • default – The default value

validate(value) → Validation

Validates the given value with this ConfigPoint. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

class configuration.IntegerConfigPoint(name: str, minimum: int, maximum: int, default: int)

A ConfigPoint that requires selection from a range of integers. The default value must lie within the specified range

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • minimum – The minimum allowed value

  • maximum – The maximum allowed value

  • default – The default value

validate(value) → Validation

Validates the given value with this ConfigPoint. Returns a Validation containing the validation result, as well as an error message containing the reason for a validation failure.

configuration.VALID = Validation(is_valid=True, message='Valid.')

The default successful validation.

class configuration.Validation(is_valid, message)

A class containing configuration validation results.

Parameters

  • is_valid – True if the validation was successful, False otherwise.

  • message – If is_valid is false this filed will contain a explanation message.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

is_valid

Alias for field number 0

message

Alias for field number 1

configuration.boolean(name: str, default: bool) → BooleanConfigPoint

A helper function to simplify the creation of BooleanConfigPoints.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • default – The default value

configuration.choice(name: str, choices: List, default) → ChoiceConfigPoint

A helper function to simplify the creation of ChoiceConfigPoints. Requires selection from a limited number of choices. The default value must exist in the given choices.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • choices – A List of all of the valid choices for this ConfigPoint

  • default – The default value

configuration.floatingPoint(name: str, minimum: float, maximum: float, default: float) → FloatConfigPoint

A helper function to simplify the creation of FloatConfigPoints. Requires selection from a range of floats. The default value must exist in the given range.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • minumum – The minumum allowed value

  • maximum – The maximum allowed value

  • default – The default value

configuration.integer(name: str, minimum: int, maximum: int, default: int) → IntegerConfigPoint

A helper function to simplify the creation of IntegerConfigPoints. Requires selection from a range of integers. The default value must exist in the given range.

Parameters

  • name – The name of this ConfigPoint, will be used by scripts to lookup the configured value.

  • minimum – The minimum allowed value

  • maximum – The maximum allowed value

  • default – The default value