multiconf package

class multiconf.McInvalidValue(*values)

Bases: Enum

Special values which may be assigned to attributes.

MC_NO_VALUE

This is the initial value for attribute until it receives a value for an Env. This will only be observed when iterating over the env values of an attribute and the ConfigItem was excluded from some Envs. See attr_env_items(). You should never set an attribute to this value.

MC_REQUIRED

This is used as the default value for attributes in __init__ when there is no reasonable default. Multiconf will verify that a real value is assigned to the attribute during the config instantiation.

MC_TODO

This can be used in the configuration as a temporary place holder for values which are currently unknown. There are various options to make multiconf report on MC_TODO values.

class multiconf.McTodoHandling(*values)

Bases: Enum

Specify how to handle MC_TODO values in the configuration.

SILENT

Do not report MC_TODO

WARNING

Print a warning about each MC_TODO value.

ERROR

Print an error message about each MC_TODO value and raise an Exception.

multiconf.caller_file_line(up_level=2)

Return the file and line of the caller of the function calling this function (depending on up_level)

class multiconf.ConfigItem(*init_args, **init_kwargs)

Base class for config items.

attr_env_items(attr_name, ignored_exceptions=())

Iterate through the attribute (env, value) for the all defined envs.

If ConfigExcludedAttributeError, ConfigExcludedKeyError or any exception specified in ignored_exceptions is raised then McInvalidValue.MC_NO_VALUE is returned.

Parameters:

• attr_name (str) – The attribute name.

• ignored_exceptions (type or sequence(type)) – Additional exception classes to ignore. This can be necessary when attr_name references a @property method which may raise an arbitrary error when called for an env where some of it’s dependencies may not be setup correctly.

Yields:

env (Env), value (any) –

The (env, attribute value) for each env or MC_NO_VALUE if there is no value for a specific

env (e.g. the item is excluded). If an exception was raised for all envs the last exception will propagate.

attr_env_values(attr_name, ignored_exceptions=())

Iterate through the attribute value for the all defined envs.

See attr_env_items() for common behaviour.

Yields:

value (any) – The attribute value for each env.

env_loop()

Iterator over all defined envs.

Sets current env and yields it. This is most useful for cross env applications where the config has been instantiated with MC_NO_ENV.

E.g.:

  class item(ConfigItem):
      def __init__(self, aa):
          super().__init__()
          self.aa = aa
          self.aa_alternate = MC_REQUIRED

      @property
      def aa_special(self):
          return self.aa_alternate + self.aa

  @mc_config(ef)
  def config(root):
      with item(aa=1) as it:
          it.setattr('aa_alternate', default=1, prod=7)

  cr = config(MC_NO_ENV)

  exp_envs = [pp, prod]
  exp_values = [2, 8]
  for index, env in enumerate(cr.item.env_loop()):
      print(cr.item.aa)
      print(cr.item.aa_special)

prints: 1 2 1 8

Yields:

env (Env) – The env which was set as the current env.

find_attribute(name)

Find first occurrence of attribute or child item ‘name’, by searching backwards towards root_conf, starting with self.

find_attribute_or_none(name)

Find first occurrence of attribute or child item ‘name’, by searching backwards towards root_conf, starting with self.

find_contained_in(named_as)

Find first parent container named as ‘named_as’, by searching backwards towards root_conf, starting with parent container

find_contained_in_or_none(named_as)

Find first parent container named as ‘named_as’, by searching backwards towards root_conf, starting with parent container

getattr(attr_name, env)

Get the attribute value for the specified env.

Parameters:

• attr_name (str) – The attribute name.

• env (Env) – The env to get the value for.

items(with_types=None, with_excluded=False)

Iterate all nested items of types specified and possibly excluded items.

Parameters:

• with_types – Types to include in iteration. The default value is what should be used in configuration code. Other types should only be included for debugging.

• with_excluded – Include excluded objects. The default is what should be used in configuration code. True should only be used for debugging.

Yields:

item (any type specified in ‘with_types’) – The nested items.

items_with_builders_and_excluded(with_builders=True, with_excluded=True)

Iterate all nested items, incl. builders and excluded.

Yields:

item (ConfigItem or RepeatableDict) – Nested items.

json(compact=False, sort_attributes=False, property_methods=True, builders=False, default_items=False, skipkeys=True, warn_nesting=None, show_all_envs=False, depth=None, persistent_ids=False)

Create json representation of configuration.

The mc_json_filter and mc_json_fallback arguments to mc_config() also influence the output.

Parameters:

• compact (bool) – Set compact to true if dumping for easier human readable output, false for machine readable output.

• sort_attributes (bool) – Sort attributes by name. Sort dir() entries by name.

• property_methods (bool or None) – Call @property methods and insert values in output, including a comment that the value is calculated. If property_methods is None the @property method is not called but the name is still output, with the value replace by a fixed message. False completely disables information about @property methods.

• builders (bool) – Include ConfigBuilder items in json.

• default_items (bool) – Include DefaultItems in json.

• skipkeys (bool) – Passed to json.dumps.

• show_all_envs (bool) – Display attribute values for all envs in a single dump. Without this only the values for the current env is displayed.

• depth (int) – The number of levels of child objects to dump. None means all.

• persistent_ids (bool) – Use a persistent value instead of using id(obj) as reference keys. NOTE: This will mostly make it impossible to identify the referenced obj, but it makes it possible to compare json across runs.

mc_init()

This is a user defined callback method.

This is called at the exit from a with statement. May be used for e.g. setting default values based on other properties or cross validation of different properties

mc_post_validate()

This is a user defined callback method.

This method is called once for each item after other initialization has been done for all envs, so cross env checking and cross object/attribute checking is possible. Since it is called once, and not per env, there is no current env and regular attribute access is not possible, instead the item.getattr(name, env) method must be used to get attribute values for different envs.

This makes it possible to implement checks like the following:

assert item.getattr('mem_size', pprd) == item.getattr('mem_size', prod) <= item.getattr('mem_size', tst1)

Note that careful consideration should be taken when using env names explicitly (as above) when implementing a configuration object model, since this will force all configurations to define those envs.

Note that no modifications can be done in this method!

mc_select_envs(include=None, exclude=None, mc_error_info_up_level=2)

Calculate whether item should be included or excluded.

This should be the first statement in the ‘with’ block If item is excluded, then the ‘with’ block, is skipped and no multiconf validations are done for item or contained items.

Parameters:

• include (list[env]) – List of Envs/EngGroups for which to include this item (and contained items)

• exclude (list[env]) – List of Envs/EngGroups for which to exclude this item (and contained items)

• mc_error_info_up_level (int) – Only for use if a class overrides mc_select_envs. You must add 1 each time it is overridden. This is used for calculating the file:line in case of ambiguous include/exclude lists.

The inclusion/exclusion is done on a ‘most specific’ basis -

• If an item is excluded by an EnvGroup specification but included by a more specific EnvGroup (or Env), then it will be included.

• If an item is included by an EnvGroup specification but excluded by a more specific EnvGroup (or Env), then it will be excluded.

mc_validate()

This is a user defined callback method.

This method is called once for each item for each env after other initialization has been and all items are created. May be used for e.g. setting default values based on other properties or cross validation of different properties. It is preferable to use mc_init when possible as mc_init generally results in more precise error messages, and ensures that an item is fully defined when the ‘with’ statement is exited.

classmethod named_as()

Return the named_as property set by the @named_as decorator

property num_invalid_property_usage

Returns number of ‘InvalidUsageException’ s encountered when validating @property methods Returns 0 if ‘mc_config’ was called with validate_properties=False.

num_json_errors()

Returns number of errors encountered when generating json Return 0 if json() has not been called

setattr(attr_name, *, mc_overwrite_property=False, mc_set_unknown=False, mc_force=False, mc_error_info_up_level=2, **env_values)

Set env specific values for an attribute.

Parameters:

• attr_name (str) – The name of the attribute to set.

• mc_overwrite_property (bool=False) – Setting this to True allows overwriting a @property method with env specific values. Any env for which the @property is not overridden will still get the value of the @property method.

• mc_set_unknown (bool=False) – This allows setting a property which was not defined in the __init__ method.

• mc_force (bool=False) – Force the value of the property regardless of the normal multiconf rules for assigning values. This should be used with care, as normal validation is disabled. Using this could be a sign of bad configuration/modelling.

• mc_error_info_up_level (int) – Only for use if a class overrides setattr. You must add 1 each time it is overridden. This is used for calculating the file:line info in case of errors.

• **env_values (dict[env-name]->value) – The env specific values to assign. Arg names must be valid env names from the EnvFactory used to create the configuration.

class multiconf.RepeatableConfigItem(mc_key=None, *init_args, **init_kwargs)

Base class for config items which may be repeated.

RepeatableConfigItems will be stored in a dict using the key ‘mc_key’.

Parameters:

mc_key (hashable) – The key used to lookup the config item.

classmethod named_as()

Return the named_as property set by the @named_as decorator

class multiconf.ConfigBuilder(mc_key='default-builder', *init_args, **init_kwargs)

Base class for ‘builder’ items which can create (a collection of) other items.

abstractmethod mc_build()

Override this in derived classes. This is where child ConfigItems are declared

classmethod named_as()

Try to generate a unique name