confattr.config module

Bases: Generic[T_co]

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_co 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: Sequence[T_co] | 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: type[Any] | None = None) → str

format_allowed_values_or_type(t: type[Any] | None = None) → str

format_any_value(value: Any) → str

format_type(t: type[Any] | None = None) → str

format_value(config_id: ConfigId | None) → str

help: str | dict[+T_co, 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: ConfigId | None, value: str) → None

parse_value(value: str) → T_co

parse_value_part(t: type[T], value: str) → T

Raises:: ValueError – if value is invalid

unit: str | None: The unit of value if value is a number.

value: T_co: The value of this setting.

wants_to_be_exported() → bool

Bases: Config[T_co]

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_co 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: The value of this setting.

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

Bases: Generic[T_KEY, T]

A container for several settings which belong together. It can be indexed like a normal dict but internally the items are stored in Config instances.

In contrast to a Config instance it does not make a difference whether an instance of this class is accessed as a type or instance attribute.

Parameters:

key_prefix¶ – A common prefix which is used by format_key() to generate the key by which the setting is identified in the config file
default_values¶ – The content of this container. A Config instance is created for each of these values (except if the key is contained in ignore_keys). See format_key().
ignore_keys¶ – All items which have one of these keys are not stored in a Config instance, i.e. cannot be set in the config file.
unit¶ – The unit of all items
help¶ – A help for all items
allowed_values¶ – The values which the items can have

Raises:

ValueError – if a key is not unique

format_key(key: T_KEY) → str

Generate a key by which the setting can be identified in the config file based on the dict key by which the value is accessed in the python code.

Returns:: key_prefix + dot + key

iter_keys() → Iterator[str]: Iterate over the keys by which the settings can be identified in the config file

new_config(key: str, default: T, *, unit: str | None, help: str | dict[T, str] | None) → Config[T]: Create a new Config instance to be used internally

class confattr.config.InstanceSpecificDictMultiConfig(dmc: MultiDictConfig[T_KEY, T], config_id: ConfigId)

Bases: Generic[T_KEY, T]

An intermediate instance which is returned when accsessing a MultiDictConfig as an instance attribute. Can be indexed like a normal dict.

class confattr.config.MultiConfig(key: str, default: T_co, *, unit: str | None = None, help: str | dict[+T_co, str] | None = None, parent: MultiDictConfig[Any, T_co] | None = None, allowed_values: Sequence[T_co] | None = None, check_config_id: Callable[[MultiConfig[T_co], ConfigId], None] | None = None)

Bases: Config[T_co]

A setting which can have different values for different objects.

This class implements the descriptor protocol to return one of the values in values depending on a config_id attribute of the owning object if an instance of this class is accessed as an instance attribute. If there is no value for the config_id in values value is returned instead. If the owning instance does not have a config_id attribute an AttributeError is raised.

In the config file a group can be opened with [config-id]. Then all following set commands set the value for the specified config id.

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 MultiDictConfig
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.
check_config_id¶ – Is called every time a value is set in the config file (except if the config id is default_config_id—that is always allowed). The callback should raise a ParseException if the config id is invalid.

allowed_values: Sequence[T_co] | 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] = []: A list of all config ids for which a value has been set in any instance of this class (regardless of via code or in a config file and regardless of whether the value has been deleted later on). This list is cleared by reset().

format_value(config_id: ConfigId | None) → str

help: str | dict[+T_co, str] | None: A description of this setting or a description for each allowed value.

parse_and_set_value(config_id: ConfigId | None, value: str) → None

classmethod reset() → None: Clear config_ids and clear values for all instances in Config.instances

unit: str | None: The unit of value if value is a number.

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

values: dict[confattr.config.ConfigId, +T_co]: 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: str | None = None, help: str | None = None, allowed_values: Sequence[T] | None = None, check_config_id: Callable[[MultiConfig[T], ConfigId], None] | None = None)

Bases: DictConfig[T_KEY, T]

A container for several settings which can have different values for different objects.

This is essentially a DictConfig using MultiConfig instead of normal Config. However, in order to return different values depending on the config_id of the owning instance, it implements the descriptor protocol to return an InstanceSpecificDictMultiConfig if it is accessed as an instance attribute.

Parameters:

key_prefix¶ – A common prefix which is used by format_key() to generate the key by which the setting is identified in the config file
default_values¶ – The content of this container. A Config instance is created for each of these values (except if the key is contained in ignore_keys). See format_key().
ignore_keys¶ – All items which have one of these keys are not stored in a Config instance, i.e. cannot be set in the config file.
unit¶ – The unit of all items
help¶ – A help for all items
allowed_values¶ – The values which the items can have
check_config_id¶ – Is passed through to MultiConfig

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]: Create a new Config instance to be used internally