confattr.config module — confattr v1.6.0 documentation

# 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 if `default` 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. as `Hex`. It is not permissible to reuse the same object for different settings, otherwise `AbstractFormatter.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:

    - `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 adding it to `Primitive.help_dict`. 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

    - 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 converted

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

    - TimingError – if this setting is defined after creating a `ConfigFile` object without passing a list or set of settings to `config_instances`

  default_config_id = 'general'
  get_value(config_id: ConfigId | None) → T
    Returns:

      `value`

    This getter is only to have a common interface for `Config` and `MultiConfig`

  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.

  is_value_valid() → bool
    Returns:

      true unless the value of an `ExplicitConfig` instance has not been set yet

  classmethod iter_instances() → Iterator[Config[Any] | DictConfig[Any, Any]]

    Yield the instances in `instances` but merge `DictConfig` items to a single `DictConfig` instance so that they can be sorted differently.

  property key: str

    The name of this setting which is used in the config file. This must be unique. You can change this attribute but only as long as no `ConfigFile` or `ConfigManager` has been instantiated.

  classmethod pop_key_changer() → Callable[[str], str]

    Undo the last call to `push_key_changer()`.

  classmethod push_key_changer(callback: Callable[[str], str]) → None

    Modify the key of all settings which will be defined after calling this method.

    Call this before an `import` and `pop_key_changer()` after it if you are unhappy with the keys of a third party library. If you import that library in different modules make sure you do this at the import which is executed first.

    Parameters:

      callback – A function which takes the key as argument and returns the modified key.

  set_value(config_id: ConfigId | None, value: T) → None

    This method is just to provide a common interface for `Config` and `MultiConfig`. If you know that you are dealing with a normal `Config` you can set `value` 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.

  wants_to_be_exported() → bool

class confattr.config.ConfigId

  An identifier to specify which value of a `MultiConfig` or `MultiDictConfig` 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, sort: Sort = Sort.NAME)

  Bases: `Generic`[`T_KEY`, `T`]

  A container for several settings which belong together. Except for `__eq__()` and `__ne__()` it behaves like a normal `Mapping` 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()`.

    - 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

    - sort – How to sort the items of this dictionary in the config file/documentation

  Raises:

    ValueError – if a key is not unique

  class Sort(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

    Bases: `Enum`

    ENUM_VALUE = 2
    NAME = 1
    NONE = 3
  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`

  get(key: T_KEY) → T | None
  get(key: T_KEY, default: T_DEFAULT) → T | T_DEFAULT
  items() → Iterator[tuple[T_KEY, T]]
  iter_configs() → Iterator[Config[T]]

    Iterate over the `Config` instances contained in this dict, sorted by the argument passed to `sort` in the constructor

  keys() → Iterator[T_KEY]
  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

  values() → Iterator[T]

class confattr.config.ExplicitConfig(key: str, type: AbstractFormatter[T] | type[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: `Config`[`T`]

  A setting without a default value which requires the user to explicitly set a value in the config file or pass it as command line argument.

  You can use `is_value_valid()` in order to check whether this config has a value or not.

  If you try to use the value before it has been set: If you try to access the config as instance attribute (`object.config`) a `TypeError` is thrown. Otherwise (`config.value`) `None` is returned.

  Parameters:

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

    - type – How to parse, format and complete a value. Any class which can be passed to `Primitive` or an object of a subclass of `AbstractFormatter`.

    - unit – The unit of an int or float value (only if type is not an `AbstractFormatter`)

    - 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 not an `AbstractFormatter`.)

    - help – A description of this setting

    - parent – Applies only if this is part of a `DictConfig`

  is_value_valid() → bool
    Returns:

      true unless the value of an `ExplicitConfig` instance has not been set yet

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 normal `dict`.

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 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

    - type – How to parse, format and complete a value. Usually this is determined automatically based on `default`. But if `default` 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. as `Hex`. It is not permissible to reuse the same object for different settings, otherwise `AbstractFormatter.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 a `ParseException` 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()`.

  get_value(config_id: ConfigId | None) → T
    Returns:

      The corresponding value from `values` if `config_id` is contained or `value` otherwise

  classmethod reset() → None

    Clear `config_ids` and clear `values` for all instances in `Config.instances`

  set_value(config_id: ConfigId | None, value: T) → None

    Check `config_id` by calling `check_config_id()` and set the value for the object(s) identified by `config_id`.

    If you know that `config_id` is valid you can also change the items of `values` directly. That is especially useful in test automation with `pytest.MonkeyPatch.setitem()`.

    If you want to set the default value you can also set `value` directly.

    Parameters:

      - config_id – Identifies the object(s) for which `value` is intended. `None` is equivalent to `default_config_id`.

      - value – The value to be assigned for the object(s) identified by `config_id`.

  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], *, 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` 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()`.

    - 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

  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

exception confattr.config.TimingError

  Bases: `Exception`

  Is raised when trying to instantiate `Config` if a `ConfigFile` has been instantiated before without passing an explicit list or set to `config_instances` or when trying to change a `key` after creating any `ConfigFile` because such changes would otherwise be silently ignored by that `ConfigFile`.

confattr.config.is_mapping_with_enum_keys(m: Mapping[Any, T]) → TypeGuard[Mapping[Enum, T]]