confattr.config module
- class confattr.config.Config(key: str, default: T, *, type: AbstractFormatter[T] | None = None, unit: str | None = None, allowed_values: Sequence[T] | dict[str, T] | None = None, help: str | dict[T, str] | None = None, parent: DictConfig[Any, T] | None = 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
type¶ – How to parse, format and complete a value. Usually this is determined automatically based on
default
. But ifdefault
is an empty list the item type cannot be determined automatically so that this argument must be passed explicitly. This also gives the possibility to format a standard type differently e.g. asHex
. It is not permissible to reuse the same object for different settings, otherwiseAbstractFormatter.set_config_key()
will throw an exception.unit¶ – The unit of an int or float value (only if type is None)
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. (Only if type is None.)help¶ – A description of this setting
parent¶ – Applies only if this is part of a
DictConfig
T
can be one of: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 attributehelp
or by adding it toPrimitive.help_dict
. If that class has a str attributetype_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
TypeError – if
default
is an empty list/set because the first element is used to infer the data type to which a value given in a config file is convertedTypeError – if this setting is a number or a list of numbers and
unit
is not given
- default_config_id = 'general'
- get_value(config_id: ConfigId | None) T
- Returns:
This getter is only to have a common interface for
Config
andMultiConfig
- 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 thekey
attribute. The value is theConfig
instance. NewConfig
instances add themselves automatically in their constructor.
- set_value(config_id: ConfigId | None, value: T) None
This method is just to provide a common interface for
Config
andMultiConfig
. If you know that you are dealing with a normalConfig
you can setvalue
directly.
- type: AbstractFormatter[T]
Information about data type, unit and allowed values for
value
and methods how to parse, format and complete it.
- value: T
The value of this setting.
- class confattr.config.ConfigId
An identifier to specify which value of a
MultiConfig
orMultiDictConfig
should be used for a certain object.alias of
str
- class confattr.config.DictConfig(key_prefix: str, default_values: dict[T_KEY, T], *, type: CopyableAbstractFormatter[T] | None = None, ignore_keys: Container[T_KEY] = {}, unit: str | None = None, allowed_values: Sequence[T] | dict[str, T] | None = None, help: str | 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 inConfig
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 thekey
by which the setting is identified in the config filedefault_values¶ – The content of this container. A
Config
instance is created for each of these values (except if the key is contained inignore_keys
). Seeformat_key()
.type¶ – How to parse, format and complete a value. Usually this is determined automatically based on
default_values
. But if you want more control you can implement your own class and pass it to this parameter.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 (only if type is None)
allowed_values¶ – The possible values these settings can have. Values read from a config file or an environment variable are checked against this. The
default_values
are not checked. (Only if type is None.)help¶ – A help for all items
- 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
- class confattr.config.InstanceSpecificDictMultiConfig(mdc: 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 normaldict
.
- class confattr.config.MultiConfig(key: str, default: T, *, type: AbstractFormatter[T] | None = None, unit: str | None = None, allowed_values: Sequence[T] | dict[str, T] | None = None, help: str | dict[T, str] | None = None, parent: MultiDictConfig[Any, T] | None = None, check_config_id: Callable[[MultiConfig[T], ConfigId], None] | None = None)
Bases:
Config
[T
]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 aconfig_id
attribute of the owning object if an instance of this class is accessed as an instance attribute. If there is no value for theconfig_id
invalues
value
is returned instead. If the owning instance does not have aconfig_id
attribute anAttributeError
is raised.In the config file a group can be opened with
[config-id]
. Then all followingset
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
type¶ – How to parse, format and complete a value. Usually this is determined automatically based on
default
. But ifdefault
is an empty list the item type cannot be determined automatically so that this argument must be passed explicitly. This also gives the possibility to format a standard type differently e.g. asHex
. It is not permissible to reuse the same object for different settings, otherwiseAbstractFormatter.set_config_key()
will throw an exception.unit¶ – The unit of an int or float value (only if type is None)
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. (Only if type is None.)parent¶ – Applies only if this is part of a
MultiDictConfig
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 aParseException
if the config id is invalid.
- check_config_id: Callable[[MultiConfig[T], ConfigId], None] | None
The callable which has been passed to the constructor as
check_config_id
- 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()
.
- classmethod reset() None
Clear
config_ids
and clearvalues
for all instances inConfig.instances
- set_value(config_id: ConfigId | None, value: T) None
Check
config_id
by callingcheck_config_id()
and set the value for the object(s) identified byconfig_id
.If you know that
config_id
is valid you can also change the items ofvalues
directly. That is especially useful in test automation withpytest.MonkeyPatch.setitem()
.If you want to set the default value you can also set
value
directly.
- 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], *, type: CopyableAbstractFormatter[T] | None = None, ignore_keys: Container[T_KEY] = {}, unit: str | None = None, allowed_values: Sequence[T] | dict[str, T] | None = None, help: str | 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
usingMultiConfig
instead of normalConfig
. However, in order to return different values depending on theconfig_id
of the owning instance, it implements the descriptor protocol to return anInstanceSpecificDictMultiConfig
if it is accessed as an instance attribute.- Parameters:
key_prefix¶ – A common prefix which is used by
format_key()
to generate thekey
by which the setting is identified in the config filedefault_values¶ – The content of this container. A
Config
instance is created for each of these values (except if the key is contained inignore_keys
). Seeformat_key()
.type¶ – How to parse, format and complete a value. Usually this is determined automatically based on
default_values
. But if you want more control you can implement your own class and pass it to this parameter.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 (only if type is None)
allowed_values¶ – The possible values these settings can have. Values read from a config file or an environment variable are checked against this. The
default_values
are not checked. (Only if type is None.)help¶ – A help for all items
check_config_id¶ – Is passed through to
MultiConfig
- Raises:
ValueError – if a key is not unique