confattr.config module

class confattr.config.Config(key: str, default: T, *, help: Optional[Union[str, dict[T, str]]] = None, unit: Optional[str] = None, parent: Optional[DictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)

Bases: Generic[T]

Each instance of this class represents a setting which can be changed in a config file.

This class implements the descriptor protocol to return value if an instance of this class is accessed as an instance attribute. If you want to get this object you need to access it as a class attribute.

Parameters

  • key – The name of this setting in the config file

  • default – The default value of this setting

  • help – A description of this setting

  • unit – The unit of an int or float value

  • parent – Applies only if this is part of a DictConfig

  • allowed_values – The possible values this setting can have. Values read from a config file or an environment variable are checked against this. The default value is not checked.

T can be one of:

  • str

  • int

  • float

  • bool

  • a subclass of enum.Enum (the value used in the config file is the name in lower case letters with hyphens instead of underscores)

  • a class where __str__() returns a string representation which can be passed to the constructor to create an equal object. A help which is written to the config file must be provided as a str in the class attribute help or by calling Set.set_help_for_type(). If that class has a str attribute type_name this is used instead of the class name inside of config file.

  • a list of any of the afore mentioned data types. The list may not be empty when it is passed to this constructor so that the item type can be derived but it can be emptied immediately afterwards. (The type of the items is not dynamically enforced—that’s the job of a static type checker—but the type is mentioned in the help.)

Raises

  • ValueError – if key is not unique

  • ValueError – if default is an empty list because the first element is used to infer the data type to which a value given in a config file is converted

  • TypeError – if this setting is a number or a list of numbers and unit is not given

LIST_SEP = ','
allowed_values: collections.abc.Sequence[confattr.config.T] | None

The values which are allowed for this setting. Trying to set this setting to a different value in the config file is considered an error. If you set this setting in the program the value is not checked.

default_config_id = 'general'
format_allowed_values(t: Optional[type[Any]] = None) → str
format_allowed_values_or_type(t: Optional[type[Any]] = None) → str
format_any_value(value: Any) → str
format_type(t: Optional[type[Any]] = None) → str
format_value(config_id: Optional[ConfigId]) → str
help: str | dict[T, str] | None

A description of this setting or a description for each allowed value.

instances: dict[str, confattr.config.Config[Any]] = {}

A mapping of all Config instances. The key in the mapping is the key attribute. The value is the Config instance. New Config instances add themselves automatically in their constructor.

property key: str

The name of this setting which is used in the config file. This must be unique.

parse_and_set_value(config_id: Optional[ConfigId], value: str) → None
parse_value(value: str) → T
parse_value_part(t: type[T1], value: str) → T1
Raises

ValueError – if value is invalid

unit: str | None

The unit of value if value is a number.

value: T

The value of this setting.

wants_to_be_exported() → bool
class confattr.config.ConfigTrackingChanges(key: str, default: T, *, help: Optional[Union[str, dict[T, str]]] = None, unit: Optional[str] = None, parent: Optional[DictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)

Bases: Config[T]

Parameters

  • key – The name of this setting in the config file

  • default – The default value of this setting

  • help – A description of this setting

  • unit – The unit of an int or float value

  • parent – Applies only if this is part of a DictConfig

  • allowed_values – The possible values this setting can have. Values read from a config file or an environment variable are checked against this. The default value is not checked.

T can be one of:

  • str

  • int

  • float

  • bool

  • a subclass of enum.Enum (the value used in the config file is the name in lower case letters with hyphens instead of underscores)

  • a class where __str__() returns a string representation which can be passed to the constructor to create an equal object. A help which is written to the config file must be provided as a str in the class attribute help or by calling Set.set_help_for_type(). If that class has a str attribute type_name this is used instead of the class name inside of config file.

  • a list of any of the afore mentioned data types. The list may not be empty when it is passed to this constructor so that the item type can be derived but it can be emptied immediately afterwards. (The type of the items is not dynamically enforced—that’s the job of a static type checker—but the type is mentioned in the help.)

Raises

  • ValueError – if key is not unique

  • ValueError – if default is an empty list because the first element is used to infer the data type to which a value given in a config file is converted

  • TypeError – if this setting is a number or a list of numbers and unit is not given

has_changed() → bool
Returns

True if value has been changed since the last call to save_value()

restore_value() → None

Restore value to the value before the last call of save_value().

save_value(new_value: T) → None

Save the current value and assign new_value to value.

property value: T
class confattr.config.DictConfig(key_prefix: str, default_values: dict[T_KEY, T], *, ignore_keys: Container[T_KEY] = {}, unit: Optional[str] = None, help: Optional[str] = None, allowed_values: Optional[Sequence[T]] = None)

Bases: Generic[T_KEY, T]

Parameters

  • key_prefix –

  • default –

  • ignore_keys –

  • unit –

  • help –

Raises

ValueError – if a key is not unique

format_key(key: T_KEY) → str
iter_keys() → Iterator[str]
new_config(key: str, default: T, *, unit: str | None, help: str | dict[T, str] | None) → Config[T]
class confattr.config.InstanceSpecificDictMultiConfig(dmc: MultiDictConfig[T_KEY, T], config_id: ConfigId)

Bases: Generic[T_KEY, T]

class confattr.config.MultiConfig(key: str, default: T, *, unit: Optional[str] = None, help: Optional[Union[str, dict[T, str]]] = None, parent: Optional[MultiDictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)

Bases: Config[T]

Parameters

  • key – The name of this setting in the config file

  • default – The default value of this setting

  • help – A description of this setting

  • unit – The unit of an int or float value

  • parent – Applies only if this is part of a DictConfig

  • allowed_values – The possible values this setting can have. Values read from a config file or an environment variable are checked against this. The default value is not checked.

T can be one of:

  • str

  • int

  • float

  • bool

  • a subclass of enum.Enum (the value used in the config file is the name in lower case letters with hyphens instead of underscores)

  • a class where __str__() returns a string representation which can be passed to the constructor to create an equal object. A help which is written to the config file must be provided as a str in the class attribute help or by calling Set.set_help_for_type(). If that class has a str attribute type_name this is used instead of the class name inside of config file.

  • a list of any of the afore mentioned data types. The list may not be empty when it is passed to this constructor so that the item type can be derived but it can be emptied immediately afterwards. (The type of the items is not dynamically enforced—that’s the job of a static type checker—but the type is mentioned in the help.)

Raises

  • ValueError – if key is not unique

  • ValueError – if default is an empty list because the first element is used to infer the data type to which a value given in a config file is converted

  • TypeError – if this setting is a number or a list of numbers and unit is not given

allowed_values: collections.abc.Sequence[confattr.config.T] | None

The values which are allowed for this setting. Trying to set this setting to a different value in the config file is considered an error. If you set this setting in the program the value is not checked.

config_ids: list[confattr.config.ConfigId] = []
format_value(config_id: Optional[ConfigId]) → str
help: str | dict[T, str] | None

A description of this setting or a description for each allowed value.

parse_and_set_value(config_id: Optional[ConfigId], value: str) → None
classmethod reset() → None
unit: str | None

The unit of value if value is a number.

value: T

Stores the default value which is used if no value for the object is defined in values.

values: dict[confattr.config.ConfigId, T]

Stores the values for specific objects.

class confattr.config.MultiDictConfig(key_prefix: str, default_values: dict[T_KEY, T], *, ignore_keys: Container[T_KEY] = {}, unit: Optional[str] = None, help: Optional[str] = None, allowed_values: Optional[Sequence[T]] = None)

Bases: DictConfig[T_KEY, T]

Parameters

  • key_prefix –

  • default –

  • ignore_keys –

  • unit –

  • help –

Raises

ValueError – if a key is not unique

new_config(key: str, default: T, *, unit: str | None, help: str | dict[T, str] | None) → MultiConfig[T]