classconfig package

Submodules

classconfig.base module

Created on 17.02.23 Base classes for configuration.

author:

Martin Dočekal

class classconfig.base.AttributeTransformer

Bases: ABC

Transformer of user input to programming form.

class classconfig.base.ConfigurableAttribute(desc: str | None = None, name: str | None = None, voluntary: bool = False, hidden: bool = False)

Bases: ABC

Base class for configurable attribute that can be used for initialization from config file. Also, it can provide information to create a config file.

property member_name: str

name of the member that is used for this attribute

Type:

return

class classconfig.base.Validator

Bases: ABC

Base class for attributes validators

classconfig.classes module

Created on 17.02.23 Module with utils for working with classes itself.

author:

Martin Dočekal

class classconfig.classes.ConfigurableDataclassMixin

Bases: object

Mixin that marks dataclass as configurable class.

DESC_METADATA = 'desc'

classconfig.classes.dataclass_field_2_configurable_attribute(field, desc_metadata: str = 'desc', voluntary: bool = True) → ConfigurableAttribute

Converts dataclass field to configurable attribute.

Parameters:

• field – dataclass field

• desc_metadata – metadata key for description

• voluntary – if True the attribute is voluntary

Returns:

configurable attribute

classconfig.classes.get_configurable_attributes(c: Type, dataclass_mixin: bool = True, use_dataclass_fields: bool = False, desc_metadata: str | None = None) → Dict[str, ConfigurableAttribute]

For given class returns all configurable attributes. Also obtains these from parents recursively.

Parameters:

• c – class to search the annotations

• dataclass_mixin – By default when a dataclass inherits from ConfigurableDataclassMixin all fields are considered configurable. If you want to disable this behavior set this to False.

• use_dataclass_fields – if True dataclass fields are considered as configurable attributes

• desc_metadata – metadata key for description

Returns:

dict with name as key, and the configurable attribute as value

classconfig.classes.is_configurable(cls: Type, dataclass_mixin: bool = True) → bool

Checks if given class is configurable.

Parameters:

• cls – class to check

• dataclass_mixin – By default when a dataclass inherits from ConfigurableDataclassMixin all fields are considered configurable. If you want to disable this behavior set this to False.

Returns:

True if class is configurable, False otherwise

classconfig.classes.sub_cls_from_its_name(parent_cls: Type[T], name: str, abstract_ok: bool = False) → Type[T]

Searches all subclasses of given classes (also the class itself) and returns class with given name.

Parameters:

• parent_cls – parent class whose subclasses should be searched

• name – name of searched subclass

• abstract_ok – if True also abstract classes will be returned

Returns:

subclass of given name

Raise:

ValueError when name with given subclass doesn’t exist

classconfig.classes.subclasses(cls_type: Type[T], abstract_ok: bool = False, configurable_only: bool = False) → List[Type[T]]

Returns all subclasses of given class.

Parameters:

• cls_type – parent class

• abstract_ok – if True also abstract classes will be returned

• configurable_only – if True only classes that are configurable will be returned configurable class is such that has at least one configurable attribute

Returns:

all subclasses of given class

classconfig.configurable module

” Created on 10.08.22

Module for configurable attributes.

author:

Martin Dočekal

class classconfig.configurable.Config(cls_type: Type, file_override_user_defaults: Dict | None = None, omit: Dict[str, AbstractSet | Dict] | None = None, path_to: str | None = None, allow_extra: bool = True)

Bases: object

Class for loading/generating configuration for a class.

static bool_arg_convertor(value: str) → bool

Converts string to bool.

Parameters:

value – string to convert

Returns:

bool value

classmethod config_from_object(o: Any) → Config

Creates configuration with user default values from given object.

Parameters:

o – object with values

Returns:

configuration

classmethod configurable_values_from_object(o: Any) → Dict

Creates dictionary with values associated for configurable attributes from given object.

Parameters:

o – object with values

Returns:

dictionary with user default values

create_arg_parser() → ArgumentParser

It will create argument parser from value attributes on top level.

Returns:

argument parser

generate_md_documentation(lvl: int = 0) → str

Generates markdown documentation for configuration.

Parameters:

lvl – current markdown level

Returns:

markdown documentation

generate_yaml_config(comments: bool = True) → CommentedMap

Converts configuration into YAML.

Parameters:

comments – true inserts comments

Returns:

configuration in YAML format

generate_yaml_for_configurable_factory(attribute_name: str, attribute: ConfigurableFactory, comments: bool) → CommentedMap

Generates yaml for configurable factory.

Parameters:

• attribute_name – name of attribute

• attribute – attribute

• comments – true inserts comments

Returns:

yaml

generate_yaml_for_configurable_subclass_factory(attribute_name: str, attribute: ConfigurableSubclassFactory, comments: bool) → CommentedMap

Generates yaml for configurable subclass factory.

Parameters:

• attribute_name – name of attribute

• attribute – attribute

• comments – true inserts comments

Returns:

yaml

generate_yaml_for_configurable_value(attribute_name: str, attribute: ConfigurableValue) → any

Generates yaml for configurable value.

Parameters:

• attribute_name – name of attribute

• attribute – attribute

Returns:

the value for config file

generate_yaml_for_list_of_configurable_factories(attribute: ListOfConfigurableSubclassFactoryAttributes, comments: bool) → CommentedSeq

Generates yaml for list of configurable factories.

Parameters:

• attribute_name – name of attribute

• attribute – attribute

• comments – true inserts comments

Returns:

yaml

get_values_from_arguments() → Dict[str, str]

Gets key values from arguments.

Returns:

values from arguments

load(path_to: str | PathLike | None = None, use_program_arguments: bool = True) → LoadedConfig[str, Any]

Loads configuration from file and arguments.

Parameters:

• path_to –

  Path to YAML file with configuration. if None, then it is loaded from default path

  if default path is None, then it tries to load confiuration from default values

• use_program_arguments – true uses program arguments

Returns:

loaded configuration

load_itself() → LoadedConfig[str, Any]

Loads configuration from default.

Returns:

loaded configuration

static pass_omit(omit: Dict[str, AbstractSet | Dict] | None, attribute_name: str, attribute: ConfigurableAttribute) → Dict[str, AbstractSet | Dict] | None

Omit that should be passed to deeper attributes.

Parameters:

• omit – current omit

• attribute_name – name of deeper attribute

• attribute – deeper attribute

Returns:

omit that should be passed to deeper attributes

save(file_path: str | PathLike[str] | TextIO, comments: bool = True) → None

Saves configuration into file.

Parameters:

• file_path – path to file

• comments – true inserts comments

to_md(file_path: str | PathLike[str] | TextIO) → None

Creates markdown documentation for configuration.

Parameters:

file_path – path to file

trans_and_val(config: Dict[str, Any], path_to: str | None) → LoadedConfig[str, Any]

Transforms and validates values in configuration.

Parameters:

• config – config for transformation and validation

• path_to – Path to file with configuration. is used by some transformation

Returns:

Transformed and validated configuration

trans_and_val_configurable_factory(attribute_name: str, attribute: ConfigurableFactory, value: Any, path_to: str | None) → LoadedConfig[str, Any] | None

Transforms and validates values in configuration for configurable factory attribute.

Parameters:

• attribute_name – name of attribute

• attribute – the configurable factory attribute

• value – loaded configuration value

• path_to – path to configuration file

Returns:

transformed and validated configuration

Raise:

ConfigError when there is a problem with the value

trans_and_val_configurable_subclass_factory(attribute_name: str, attribute: ConfigurableSubclassFactory, value: Any, path_to: str | None) → Dict[str, Any] | None

Transforms and validates values in configuration for configurable subclass factory attribute.

Parameters:

• attribute_name – name of attribute

• attribute – the configurable factory attribute

• value – loaded configuration value

• path_to – path to configuration file

Returns:

transformed and validated configuration

Raise:

ConfigError when there is a problem with the value

trans_and_val_configurable_value(attribute: ConfigurableValue, value: Any, path_to: str | None) → Any | None

Transforms and validates values in configuration for configurable value attribute.

Parameters:

• attribute – the configurable factory attribute

• value – loaded configuration value

• path_to – path to configuration file

Returns:

transformed and validated configuration

Raise:

ConfigError when there is a problem with the value

trans_and_val_list_of_configurable_subclass_factory(attribute_name: str, attribute: ListOfConfigurableSubclassFactoryAttributes, value: Any, path_to: str | None) → List[Dict[str, Any]] | None

Transforms and validates values in configuration for list of configurable subclass factory attribute.

Parameters:

• attribute_name – name of attribute

• attribute – the configurable factory attribute

• value – loaded configuration value

• path_to – path to configuration file

Returns:

transformed and validated configuration

Raise:

ConfigError when there is a problem with the value

exception classconfig.configurable.ConfigError(msg: str, attribute: List[str] | None)

Bases: Exception

Exception for configuration related issues.

class classconfig.configurable.ConfigurableFactory(cls_type: Type[T], desc: str | None = None, name: str | None = None, delay_init: bool = False, voluntary: bool = False, file_override_user_defaults: Dict | None = None, omit: Dict[str, AbstractSet | Dict] | None = None)

Bases: ConfigurableAttribute, Generic[T]

Factory for all classes that could be initialized with configuration.

create(config: LoadedConfig[str, Any], omit: Dict[str, AbstractSet | Dict] | None = None) → T | DelayedFactory[T]

Creates instance of given class.

Parameters:

• config – configuration for initialization

• omit – omit these attributes when creating if not None the delay_init will be used

Returns:

initialized class or factory for delayed initialization if delay_init is active

static merge_omits(omit_a: Dict[str, Dict] | None, omit_b: Dict[str, Dict] | None) → Dict[str, Dict] | None

Merges two omit dictionaries.

Parameters:

• omit_a – first omit dictionary

• omit_b – second omit dictionary will update the first one (NOT in place)

Returns:

merged omit dictionary

static should_omit(var_name: str, omit: Dict[str, AbstractSet | Dict] | None) → bool

Checks if given variable should be omitted from configuration file.

Parameters:

• var_name – name of variable to check

• omit – omit these attributes from configuration file as it is expected that they will be provided

Returns:

True if the variable should be omitted

class classconfig.configurable.ConfigurableMixin(**kargs)

Bases: object

Mixin that performs initialization of all configurables and calls __post_init__ after (if it exists). The validation is not performed here.

class classconfig.configurable.ConfigurableSubclassFactory(parent_cls_type: Type[T], desc: str | None = None, name: str | None = None, user_default: Any | None = None, delay_init: bool = False, voluntary: bool = False, file_override_user_defaults: Dict | None = None, omit: Dict[str, AbstractSet | Dict] | None = None)

Bases: ConfigurableAttribute, Generic[T]

Factory that enables to create any configurable class that is subclass of given parent class.

create(config: LoadedConfig[str, Any], omit: Dict[str, AbstractSet | Dict] | None = None) → T | DelayedFactory[T]

Creates instance of given class.

Parameters:

• config –

  configuration for initialization It expects dictionary with:

  cls: defining class name config: defining class configuration

• omit – omit these attributes when creating if not None the delay_init will be used

Returns:

initialized class or factory for delayed initialization of delay_init is active

class classconfig.configurable.ConfigurableValue(desc: str | None = None, name: str | None = None, user_default: Any | None = None, validator: Callable[[Any], bool] | None = None, transform: Callable[[Any], Any] | None = None, voluntary: bool = False)

Bases: ConfigurableAttribute, Generic[C]

Defines configurable value that itself doesn’t need configuration.

class classconfig.configurable.CreatableMixin

Bases: object

Mixin for creating class from configuration.

classmethod create(config: str | PathLike[str] | Dict[str, Any] | LoadedConfig[str, Any], path_to_config: str | None = None, allow_extra: bool = True) → T

Creates instance of given class.

Parameters:

• config –

  configuration for initialization it might be:

  • string | Path: path to YAML file with configuration

  • dictionary with configuration

  • LoadedConfig object

• path_to_config – path to configuration file if given, it might be used for transformation of relative paths

• allow_extra – if True extra attributes in configuration are allowed

Returns:

initialized class

Raises:

ValueError – when the config type is invalid

class classconfig.configurable.DelayedFactory(cls_type: Type[T], args: Dict, recursive: bool = True, propagate_recursion: bool = True)

Bases: Generic[T]

Factory for delayer initialization.

create(**additional_args) → T

Creates instance of given class.

Parameters:

additional_args – additional arguments that will be used together with the already loaded ones

Returns:

initialized class

class classconfig.configurable.ListOfConfigurableSubclassFactoryAttributes(configurable_subclass_factory: ConfigurableSubclassFactory, desc: str | None = None, name: str | None = None, user_defaults: List[Type] | None = None, voluntary: bool = False)

Bases: ConfigurableAttribute, Generic[T]

create(config: Sequence[LoadedConfig[str, Any]], omit: Sequence[Dict[str, AbstractSet | Dict] | None] | None = None) → List[T | DelayedFactory[T]]

Creates instance of given class.

Parameters:

• config – configuration for initialization It expects list with configuration for each item

• omit – omit these attributes when creating if not None the delay_init will be used

Returns:

initialized class or factory for delayed initialization of delay_init is active

class classconfig.configurable.LoadedConfig

Bases: dict

Loaded validated and transformed configuration.

property parent_config: LoadedConfig | None

Returns parent configuration. Parent configuration is a configuration that has this configuration as its part. Is none when it was not set, or it is root.

property untransformed: Dict[str, Any] | None

Returns untransformed configuration.

class classconfig.configurable.UsedConfig(from_top_lvl: bool = False)

Bases: ConfigurableAttribute

Configurable attribute that is used to store used configuration. It is not visible for user in config file.

classconfig.transforms module

Created on 26.04.23

Module with transformers for configuration attributes.

author:

Martin Dočekal

class classconfig.transforms.CPUWorkersTransformer

Bases: AttributeTransformer

Converts the number of cpu workers from user format to a program one.

class classconfig.transforms.EnumTransformer(enum: Type[Enum])

Bases: AttributeTransformer

Transforms string representation of enum to enum.

class classconfig.transforms.RelativePathTransformer(base_path: str | None = None, eval_counters: bool = False, allow_none: bool = False, force_relative_prefix: bool = False)

Bases: AttributeTransformer

Transforms relative paths.

Variables:

base_path – all relative path will be relative to this If this attribute is None when transformed a runtime error is raised.

class classconfig.transforms.SubclassTransformer(parent_cls: Type)

Bases: AttributeTransformer

Transforms string representation of subclass to subclass (also the class itself is allowed and all subclasses recursively).

class classconfig.transforms.TransformIfNotNone(transformer: Callable[[Any], Any])

Bases: AttributeTransformer

Transforms value if it is not None.

class classconfig.transforms.TryTransforms(transforms: Sequence[AttributeTransformer])

Bases: AttributeTransformer

Tries all provided transforms in given order and stops when a transform is not raising an exception.

WARNING: all exceptions are caught

classconfig.validators module

Created on 26.04.23

Module with validators for configuration attributes.

author:

Martin Dočekal

class classconfig.validators.AllValidator(validators: Iterable[Callable[[Any], bool]])

Bases: Validator

Combination of validators.

applies all validators in given order:

v1 -> v2 -> v3

every must by ok

class classconfig.validators.AnyValidator(validators: Iterable[Callable[[Any], Any]])

Bases: Validator

Combination of validators.

applies all validators in given order:

v1 -> v2 -> v3

at least one must be ok

class classconfig.validators.BoolValidator(t: Type | None = None)

Bases: TypeValidator

Assures that the value is a boolean.

TYPE

alias of bool

TYPE_NAME: str | None = 'boolean'

name of type used for exception message, by default is used class name of TYPE

class classconfig.validators.CollectionOfTypesValidator(c: Type[Collection], t: Type, type_name: str | None = None, allow_none: bool = False, value_validator: Callable[[Any], bool] | None = None, allow_empty: bool = False)

Bases: Validator

Class for non-empty Collection of given types attributes.

class classconfig.validators.FilePathValidator(t: Type | None = None)

Bases: StringValidator

Validates that the attribute is string defining valid path to an existing file.

class classconfig.validators.FloatValidator(t: Type | None = None)

Bases: TypeValidator

Assures that the value is a float.

TYPE

alias of float

TYPE_NAME: str | None = 'float'

name of type used for exception message, by default is used class name of TYPE

class classconfig.validators.IntegerValidator(t: Type | None = None)

Bases: TypeValidator

Assures that the value is an integer.

TYPE

alias of int

TYPE_NAME: str | None = 'integer'

name of type used for exception message, by default is used class name of TYPE

class classconfig.validators.IsNoneValidator

Bases: Validator

Assures that the value is none.

class classconfig.validators.ListOfTypesValidator(t: Type, type_name: str | None = None, allow_none: bool = False, value_validator: Callable[[Any], Any] | None = None, allow_empty: bool = False)

Bases: CollectionOfTypesValidator

Class for non-empty list of given types attributes.

class classconfig.validators.MinValueFloatValidator(min_value: float)

Bases: FloatValidator

Assures that the value is a float greater or equal given value.

class classconfig.validators.MinValueIntegerValidator(min_value: int)

Bases: IntegerValidator

Assures that the value is an integer greater or equal given value.

class classconfig.validators.StringValidator(t: Type | None = None)

Bases: TypeValidator

Assures that the value is a string.

TYPE

alias of str

TYPE_NAME: str | None = 'string'

name of type used for exception message, by default is used class name of TYPE

class classconfig.validators.TypeValidator(t: Type | None = None)

Bases: Validator

Assures that the value is of given type.

TYPE

type used as parameter of isinstance method used for check

alias of object

TYPE_NAME: str | None = None

name of type used for exception message, by default is used class name of TYPE

class classconfig.validators.ValueInIntervalFloatValidator(min_value: float = -inf, max_value: float = inf, left_inclusive: bool = True, right_inclusive: bool = True)

Bases: FloatValidator

Assures that the value is a float in given interval.

class classconfig.validators.ValueInIntervalIntegerValidator(min_value: float = -inf, max_value: float = inf)

Bases: IntegerValidator

Assures that the value is an integer in given interval.

classconfig.yaml module

Created on 10.11.22

author:

Martin Dočekal

class classconfig.yaml.YAML(*, typ: List[str] | str | None = None, pure: Any = False, output: Any | None = None, plug_ins: Any | None = None)

Bases: YAML

YAML class that allows to dump into string.

dumps(data, **kw) → str

Module contents

Created on 26.04.23

author:

Martin Dočekal