zensols.config package

Submodules

zensols.config.condyaml

Conditional branching logic configuration.

class zensols.config.condyaml.ConditionalYamlConfig(*args, **kwargs)

Bases: ImportYamlConfig

Conditionally includes configuration based on very basic if/then logic. YAML nodes (defaulting to name condition) are replaced with a single node either under a then node or an else node.

For the then node to be used, the if value must evaluate to something that evaluates to true in Python. For this reason, it is recommended to use boolean constants or eval: syntax.

For example::

condition:

if: ${default:testvar} then:

classify_net_settings:

embedding_layer: ‘glove_50_embedding_layer’ recurrent_settings: ‘recurrent_settings’

else:

classify_net_settings:

embedding_layer: ‘transformer_embedding_layer’ recurrent_settings: ‘recurrent_settings’

__init__(*args, **kwargs)

Initialize with importation configuration. The usage of default_vars in the super class is disabled since this implementation uses a mix of dot and colon (configparser) variable substitution (the later used when imported from an ImportIniConfig.

Parameters:

• config_file – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_section – used as the default section when non given on the get methds such as get_option(); which defaults to defualt

• sections_name – the dot notated path to the variable that has a list of sections

• sections – used as the set of sections for this instance

• import_name – the dot notated path to the variable that has the import entries (see class docs); defaults to import

• parse_values – whether to invoke the Serializer to create in memory Python data, which defaults to false to keep data as string for configuraiton merging

get_tree(name=None)

Get the node in the configuration, which is a nested set dict instances as an object graph.

Parameters:

name (Optional[str]) – the doted notation indicating which node in the tree to retrieve

Return type:

Dict[str, Any]

zensols.config.configbase

Abstract base class for a configuration read from a file.

class zensols.config.configbase.Configurable(default_section=None)

Bases: Dictable

An abstract base class that represents an application specific configuration.

Note that many of the getters are implemented in configparser. However, they are reimplemented here for consistency among parser.

__init__(default_section=None)

Initialize.

Parameters:

default_section (str) – used as the default section when non given on the get methds such as get_option(); which defaults to defualt

as_deep_dict()

Return a deep builtins.dict with the top level with section names as keys and deep (i.e. json:) values as nested dictionaries.

Return type:

Dict[str, Any]

as_one_tier_dict(*args, **kwargs)

Return a flat one-tier builtins.dict with keys in <section>:<option> format.

Return type:

Dict[str, Any]

asdict(*args, **kwargs)

Return the content of the object as a dictionary.

Parameters:

• recurse – if True, recursively create dictionary so some values might be dictionaries themselves

• readable – use human readable and attribute keys when available

• class_name_param – if set, add a class_name_param key with the class’s fully qualified name (includes module name)

Return type:

Dict[str, Any]

Returns:

a JSON’able tree of dictionaries with primitive data

See:

asjson()

See:

_from_dictable()

copy_sections(to_populate, sections=None, robust=False)

Copy all sections from this configuruable to to_populate.

Parameters:

• to_populate (Configurable) – the target configuration object

• sections (Iterable[str]) – the sections to populate or None to copy allow

• robust (bool) – if True, when any exception occurs (namely interplation exceptions), don’t copy and remove the section in the target configuraiton

Return type:

Exception

Returns:

the last exception that occured while trying to copy the properties

get_option(name, section=None)

Return an option from section with name.

Parameters:

• section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

• vars – contains the defaults for missing values of name

Return type:

str

get_option_boolean(name, section=None)

Just like get_option() but parse as a boolean (any case true).

Parameters:

• section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

• vars – contains the defaults for missing values of name

Return type:

bool

get_option_float(name, section=None)

Just like get_option() but parse as a float.

get_option_int(name, section=None)

Just like get_option() but parse as an integer.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

get_option_list(name, section=None)

Just like get_option() but parse as a list using split.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

List[str]

get_option_object(name, section=None)

Just like get_option() but parse as an object per object syntax rules.

See:

Serializer.parse_object()

get_option_path(name, section=None)

Just like get_option() but return a pathlib.Path object of the string.

abstract get_options(section=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, str]

abstract has_option(name, section=None)

Return type:

bool

merge(to_populate)

Copy all data from this configuruable to to_populate, and clobber any overlapping properties in the process.

Parameters:

to_populate (Configurable) – the target configuration object

property options: Dict[str, Any]

All options from the default section.

populate(obj=None, section=None, parse_types=True)

Set attributes in obj with setattr from the all values in section.

Return type:

Union[dict, Settings]

reload()

Reload the configuration from the backing store.

remove_section(section)

Remove a seciton with the given name.

resource_filename(resource_name, module_name=None)

Return a resource based on a file name. This uses the pkg_resources package first to find the resources. If it doesn’t find it, it returns a path on the file system.

Param:

resource_name the file name of the resource to obtain (or name if obtained from an installed module)

Parameters:

module_name (str) – the name of the module to obtain the data, which defaults to __name__

Returns:

a path on the file system or resource of the installed module

property sections: Set[str]

All sections of the configuration file.

set_option(name, value, section=None)

Set an option on this configurable.

Parameters:

• name (str) – the name of the option

• value (str) – the value to set

• section (str) – the section (if applies) to add the option

Raises:

NotImplementedError – if this class does not support this operation

write(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write this instance as either a Writable or as a Dictable. If class attribute _DICTABLE_WRITABLE_DESCENDANTS is set as True, then use the write() method on children instead of writing the generated dictionary. Otherwise, write this instance by first creating a dict recursively using asdict(), then formatting the output.

If the attribute _DICTABLE_WRITE_EXCLUDES is set, those attributes are removed from what is written in the write() method.

Note that this attribute will need to be set in all descendants in the instance hierarchy since writing the object instance graph is done recursively.

Parameters:

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

exception zensols.config.configbase.ConfigurableError

Bases: ConfigurationError

Base class raised for any configuration based errors.

__annotations__ = {}

__module__ = 'zensols.config.configbase'

exception zensols.config.configbase.ConfigurableFileNotFoundError(path, source=None)

Bases: ConfigurableError

Raised when a configuration file is not found for those file based instances of Configurable.

__annotations__ = {}

__init__(path, source=None)

__module__ = 'zensols.config.configbase'

class zensols.config.configbase.TreeConfigurable(default_section=None, default_vars=None, sections_name='sections', sections=None)

Bases: Configurable

A hierarchical configuration. The sections are the root nodes, but each section’s values can be nested dict instances. These values are traversable with a string dot path notation.

__init__(default_section=None, default_vars=None, sections_name='sections', sections=None)

Initialize.

Parameters:

• default_section (str) – used as the default section when non given on the get methds such as get_option(); which defaults to defualt

• default_vars (Dict[str, Any]) – used in place of missing variables duing value interpolation; deprecated: this will go away in a future release

• sections_name (str) – the dot notated path to the variable that has a list of sections

• sections (Set[str]) – used as the set of sections for this instance

asdict(*args, **kwargs)

Return the content of the object as a dictionary.

Parameters:

• recurse – if True, recursively create dictionary so some values might be dictionaries themselves

• readable – use human readable and attribute keys when available

• class_name_param – if set, add a class_name_param key with the class’s fully qualified name (includes module name)

Return type:

Dict[str, Any]

Returns:

a JSON’able tree of dictionaries with primitive data

See:

asjson()

See:

_from_dictable()

property config: Dict[str, Any]

The configuration as a nested set of dict.

See:

invalidate()

get_option(name, section=None)

Return an option using a dot encoded path.

Parameters:

section (str) – ignored

Return type:

str

get_options(name=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, Any]

get_tree(name=None)

Get the node in the configuration, which is a nested set dict instances as an object graph.

Parameters:

name (Optional[str]) – the doted notation indicating which node in the tree to retrieve

Return type:

Dict[str, Any]

has_option(name, section=None)

Return type:

bool

invalidate()

This should be called when the underlying config object graph changes under the nose of this instance.

property options: Dict[str, Any]

All options from the default section.

property root: str | None

The root name of the configuration file, if one exists. If more than one root exists, return the first.

property sections: Set[str]

The sections by finding the section_name based from the root.

write(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write this instance as either a Writable or as a Dictable. If class attribute _DICTABLE_WRITABLE_DESCENDANTS is set as True, then use the write() method on children instead of writing the generated dictionary. Otherwise, write this instance by first creating a dict recursively using asdict(), then formatting the output.

If the attribute _DICTABLE_WRITE_EXCLUDES is set, those attributes are removed from what is written in the write() method.

Note that this attribute will need to be set in all descendants in the instance hierarchy since writing the object instance graph is done recursively.

Parameters:

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

zensols.config.configfac

Creates instances of Configurable.

class zensols.config.configfac.ConfigurableFactory(kwargs=<factory>, type_map=<factory>)

Bases: object

Create instances of Configurable with factory methods. The parameters in kwargs given to the initalizer on instantiation.

This class often is used to create a factory from just a path, which then uses the extension with the EXTENSION_TO_TYPE mapping to select the class. Top level/entry point configuration should use conf as the extension allowing the ImportIni to import other configuration. An example of this is the ConfigurationImporter loading user specific configuration.

If the class uses type = import, the type is prepended with import and then mapped using EXTENSION_TO_TYPE. This allows mixing of different files in one config_files entry and avoids multiple import sections.

See:

.ImportIniConfig

CLASS_NAME: ClassVar[str] = 'class_name'

The section entry for the class to use.

EXTENSION_TO_TYPE: ClassVar[Dict[str, str]] = {'conf': 'ini', 'ini': 'ini', 'json': 'json', 'yml': 'yaml'}

The configuration factory extension to clas name.

SINGLE_CONFIG_FILE: ClassVar[str] = 'config_file'

The section entry for the configuration file.

TYPE_NAME: ClassVar[str] = 'type'

The section entry for the configurable type (eg ini vs yaml).

TYPE_TO_CLASS_PREFIX: ClassVar[Dict[str, str]] = {'condyaml': 'ConditionalYaml', 'import': 'ImportIni', 'importini': 'ImportIni', 'importyaml': 'ImportYaml'}

Mapping from TYPE_NAME option to class prefix.

__init__(kwargs=<factory>, type_map=<factory>)

property extension_to_type: Dict[str, str]

from_class_name(class_name)

Create a configurable from the class name given.

Parameters:

class_name (str) – a fully qualified class name (i.e. zensols.config.IniConfig)

Return type:

Configurable

Returns:

a new instance of a configurable identified by class_name and created with kwargs

from_path(path)

Create a configurable from a path. This updates the kwargs to set config_file to the given path for the duration of this method.

Return type:

Configurable

classmethod from_section(kwargs, section)

Return type:

Configurable

from_type(config_type)

Create a configurable from the configuration type.

Parameters:

config_type (str) – one of the values in EXTENSION_TO_TYPE (i.e. importini)

Return type:

Configurable

Returns:

a new instance of a configurable identified by class_name and created with kwargs

kwargs: Dict[str, Any]

The keyword arguments given to the factory on creation.

type_map: Dict[str, str]

Adds more mappings from extension to configuration factory types.

See:

EXTENSION_TO_TYPE

zensols.config.dictable

Contains a class used to create a tree of dictionaries with only Python primitives handy for creating JSON.

class zensols.config.dictable.DefaultDictable(data)

Bases: Dictable

A convenience utility class that provides access to methods such as write() and asjson() without needing inheritance.

__init__(data)

data: Dict[str, Any]

The data used to be JSON or written.

class zensols.config.dictable.Dictable

Bases: Writable

A class that that generates a dictionary recursively from data classes and primitive data structures.

To override the default behavior of creating a dict from a dataclass, override the _from_dictable() method.

In addition to the fields from the dataclass, if the attribute _DICTABLE_ATTRIBUTES is set, those are added as well (see _get_dictable_attributes()).

See write() for how a dictable writes itself as a sublcass of Writable and usage of class attributes _DICTABLE_WRITABLE_DESCENDANTS and _DICTABLE_WRITE_EXCLUDES.

_get_dictable_attributes()

Return human readable and attribute names.

Return type:

Iterable[Tuple[str, str]]

Returns:

tuples of (<human readable name>, <attribute name>)

_from_dictable(recurse, readable, class_name_param=None)

A subclass can override this method to give create a custom specific dictionary to be returned from the asjson() client access method.

Parameters:

• recurse (bool) – if True, recursively create dictionary so some values might be dictionaries themselves

• readable (bool) – use human readable and attribute keys when available

• class_name_param (str) – if set, add a class_name_param key with the class’s fully qualified name (includes module name)

Return type:

Dict[str, Any]

Returns:

a JSON’able tree of dictionaries with primitive data

See:

asjson()

See:

asdict()

_write_descendants(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write this instance by using the write() method on children instead of writing the generated dictionary.

_writable_dict()

Return a dict that contains what will be output when write() is called.

Return type:

Dict[str, Any]

See:

write()

__init__()

asdict(recurse=True, readable=True, class_name_param=None)

Return the content of the object as a dictionary.

Parameters:

• recurse (bool) – if True, recursively create dictionary so some values might be dictionaries themselves

• readable (bool) – use human readable and attribute keys when available

• class_name_param (str) – if set, add a class_name_param key with the class’s fully qualified name (includes module name)

Return type:

Dict[str, Any]

Returns:

a JSON’able tree of dictionaries with primitive data

See:

asjson()

See:

_from_dictable()

asflatdict(*args, **kwargs)

Like asdict() but flatten in to a data structure suitable for writing to JSON or YAML.

Return type:

Dict[str, Any]

asjson(writer=None, recurse=True, readable=True, **kwargs)

Return a JSON string representing the data in this instance.

Return type:

str

asyaml(writer=None, recurse=True, readable=True, **kwargs)

Return a YAML string representing the data in this instance.

Return type:

str

write(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write this instance as either a Writable or as a Dictable. If class attribute _DICTABLE_WRITABLE_DESCENDANTS is set as True, then use the write() method on children instead of writing the generated dictionary. Otherwise, write this instance by first creating a dict recursively using asdict(), then formatting the output.

If the attribute _DICTABLE_WRITE_EXCLUDES is set, those attributes are removed from what is written in the write() method.

Note that this attribute will need to be set in all descendants in the instance hierarchy since writing the object instance graph is done recursively.

Parameters:

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

zensols.config.dictconfig

Implementation of a dictionary backing configuration.

class zensols.config.dictconfig.DictionaryConfig(config=None, default_section=None, deep=False)

Bases: TreeConfigurable, Dictable

This is a simple implementation of a dictionary backing configuration. The provided configuration is just a two level dictionary. The top level keys are the section and the values are a single depth dictionary with string keys and values.

You can override _get_config() to restructure the dictionary for application specific use cases. One such example is JsonConfig._get_config().

_get_config()

Return type:

Dict[str, Any]

__init__(config=None, default_section=None, deep=False)

Initialize.

Parameters:

• config (Dict[str, Dict[str, Any]]) – configures this instance (see class docs)

• default_section (str) – used as the default section when non given on the get methds such as get_option()

classmethod from_config(source, **kwargs)

Create an instance from another configurable.

Parameters:

• source (Configurable) – contains the source data from which to copy

• kwargs (Dict[str, Any]) – initializer arguments for the new instance

Return type:

DictionaryConfig

Returns:

a new instance of this class with the data copied from source

get_option(name, section=None)

Return an option using a dot encoded path.

Parameters:

section (str) – ignored

Return type:

str

get_options(section=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, str]

has_option(name, section=None)

Return type:

bool

property options: Dict[str, Any]

All options from the default section.

remove_section(section)

Remove a seciton with the given name.

property sections: Set[str]

Return the top level keys of the dictionary as sections (see class doc).

set_option(name, value, section=None)

Set an option on this configurable.

Parameters:

• name (str) – the name of the option

• value (str) – the value to set

• section (str) – the section (if applies) to add the option

Raises:

NotImplementedError – if this class does not support this operation

zensols.config.diff

A class to diff configurations.

Using this module requires the deepdiff package:

pip install deepdiff

class zensols.config.diff.ConfigurableDiffer(config_a, config_b, change_format='{} -> {}')

Bases: DictionaryConfig

A class to diff configurations. Each section of configuration contains properties of the changed options.

__init__(config_a, config_b, change_format='{} -> {}')

Initialize.

Parameters:

• config – configures this instance (see class docs)

• default_section – used as the default section when non given on the get methds such as get_option()

zensols.config.envconfig

An implementation configuration class that holds environment variables.

class zensols.config.envconfig.EnvironmentConfig(section_name='env', map_delimiter=None, skip_delimiter=False, includes=None)

Bases: Configurable

An implementation configuration class that holds environment variables.

This config will need to be added to children to ImportIniConfig if used in the configuration or import sections.

__init__(section_name='env', map_delimiter=None, skip_delimiter=False, includes=None)

Initialize with a string given as described in the class docs.

The string <DOLLAR> used with map_delimiter is the same as $ since adding the dollar in some configuration scenarios has parsing issues. One example is when $$ failes on copying section to an IniConfig.

Parameters:

• section_name (str) – the name of the created section with the environment variables

• map_delimiter (str) – when given, all environment values are replaced with a duplicate; set this to $ when using configparser.ExtendedInterpolation for environment variables such as PS1

• skip_delimiter (bool) – a string, when present, causes the environment variable to be skipped; this is useful for environment variables that cause interpolation errors

• includes (Set[str]) – if given, the set of environment variables to set excluding the rest; include all if None

get_options(section=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, str]

has_option(name, section=None)

Return type:

bool

property sections: Set[str]

All sections of the configuration file.

zensols.config.facbase

Classes that create new instances of classes from application configuration objects and files.

class zensols.config.facbase.ConfigFactory(config, pattern='{name}', default_name='default', class_resolver=None)

Bases: object

Creates new instances of classes and configures them given data in a configuration Configurable instance.

CLASS_NAME = 'class_name'

The class name attribute in the section that identifies the fully qualified instance to create.

CONFIG_ATTRIBUTE = 'config'

The configuration of the parameter given to __init__. If a parameter of this name is on the instance being created it will be set as the instance of the configuration given to the initializer of this factory instance.

CONFIG_FACTORY_ATTRIBUTE = 'config_factory'

The configuration factory of the parameter given to __init__. If a parameter of this name is on the instance being created it will be set as the instance of this configuration factory.

NAME_ATTRIBUTE = 'name'

The name of the parameter given to __init__. If a parameter of this name is on the instance being created it will be set from the name of the section.

__init__(config, pattern='{name}', default_name='default', class_resolver=None)

Initialize a new factory instance.

Parameters:

• config (Configurable) – the configuration used to create the instance; all data from the corresponding section is given to the __init__ method

• pattern (str) – section pattern used to find the values given to the __init__ method

• config_param_name – the __init__ parameter name used for the configuration object given to the factory’s instance method; defaults to config

• config_param_name – the __init__ parameter name used for the instance name given to the factory’s instance method; defaults to name

clone()

Return a copy of this configuration factory that functionally works the same.

Return type:

Any

from_config_string(v)

Create an instance from a string used as option values in the configuration.

Return type:

Any

get_class(name)

Return a class by name.

Parameters:

name (str) – the name of the class (by default) or the key name of the class used to find the class; this is the section name for the ImportConfigFactory

Return type:

Type

instance(name=None, *args, **kwargs)

Create a new instance using key name.

Parameters:

• name (Optional[str]) – the name of the class (by default) or the key name of the class used to find the class; this is the section name for the ImportConfigFactory

• args – given to the __init__ method

• kwargs – given to the __init__ method

classmethod register(instance_class, name=None)

Register a class with the factory. This method assumes the factory instance was created with a (default) DictionaryClassResolver.

Parameters:

• instance_class (Type) – the class to register with the factory (not a string)

• name (str) – the name to use as the key for instance class lookups; defaults to the name of the class

class zensols.config.facbase.FactoryClassImporter(class_name, reload=True)

Bases: ClassImporter

Just like the super class, but if instances of type FactoryStateObserver are notified with a FactoryState.CREATED.

exception zensols.config.facbase.FactoryError(msg, factory=None)

Bases: APIError

Raised when an object can not be instantianted by a ConfigFactory.

__annotations__ = {}

__init__(msg, factory=None)

__module__ = 'zensols.config.facbase'

class zensols.config.facbase.FactoryState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The state updated from an instance of ConfigFactory. Currently the only state is that an object has finished being created.

Future states might inlude when a ImportConfigFactory has created all objects from a configuration shared session.

CREATED = 1

class zensols.config.facbase.FactoryStateObserver

Bases: ABC

An interface that recieves notifications that the factory has created this instance. This is useful for classes such as Writeback.

See:

Writeback

class zensols.config.facbase.ImportClassResolver(reload=False)

Bases: ClassResolver

Resolve a class name from a list of registered class names without the module part. This is used with the register method on ConfigFactory.

See:

ConfigFactory.register()

__init__(reload=False)

create_class_importer(class_name)

find_class(class_name)

Return a class given the name of the class.

Parameters:

class_name (str) – represents the class name, which might or might not have the module as part of that name

zensols.config.importfac

A configuration factory that (re)imports based on class name.

class zensols.config.importfac.ImportConfigFactory(*args, reload=False, shared=True, reload_pattern=None, **kwargs)

Bases: ConfigFactory, Deallocatable

Import a class by the fully qualified class name (includes the module).

This is a convenience class for setting the parent class class_resolver parameter.

__init__(*args, reload=False, shared=True, reload_pattern=None, **kwargs)

Initialize the configuration factory.

Parameters:

• reload (Optional[bool]) – whether or not to reload the module when resolving the class, which is useful for debugging in a REPL

• shared (Optional[bool]) – when True instances are shared and only created once across sections for the life of this ImportConfigFactory instance

• reload_pattern (Union[Pattern, str, None]) – if set, reload classes that have a fully qualified name that match the regular expression regarless of the setting reload

• kwargs – the key word arguments given to the super class

clear()

Clear any shared instances.

clear_instance(name)

Remove a shared (cached) object instance.

Parameters:

name (str) – the section name of the instance to evict and the same string used to create with instance() or new_instance()

Return type:

Any

Returns:

the instance that was removed (if present), otherwise None

clone()

Return a copy of this configuration factory that functionally works the same. However, it does not copy over any resources generated during the life of the factory.

Return type:

Any

deallocate()

Deallocate all resources for this instance.

from_config_string(v)

Create an instance from a string used as option values in the configuration.

Return type:

Any

instance(name=None, *args, **kwargs)

Create a new instance using key name.

Parameters:

• name (Optional[str]) – the name of the class (by default) or the key name of the class used to find the class; this is the section name for the ImportConfigFactory

• args – given to the __init__ method

• kwargs – given to the __init__ method

new_deep_instance(name=None, *args, **kwargs)

Like new_instance() but copy all recursive instances as new objects as well.

new_instance(name=None, *args, **kwargs)

Create a new instance without it being shared. This is done by evicting the existing instance from the shared cache when it is created next time the contained instances are shared.

Parameters:

• name (str) – the name of the class (by default) or the key name of the class used to find the class

• args – given to the __init__ method

• kwargs – given to the __init__ method

See:

instance()

See:

new_deep_instance()

classmethod register_module(mod)

class zensols.config.importfac.ImportConfigFactoryModule(factory)

Bases: object

A module used by ImportConfigFactory to create instances using special formatted string (i.e. instance:). Subclasses implement the object creation based on the formatting of the string.

__init__(factory)

factory: ImportConfigFactory

The parent/owning configuration factory instance.

instance(proto)

Return a new instance from the a prototype input.

Return type:

Any

property name: str

The name of the module and prefix used in the instance formatted string.

post_populate(inst)

Called to populate or replace the created instance after being generated by ImportConfigFactory.

Return type:

Any

class zensols.config.importfac.ModulePrototype(factory, name, config_str)

Bases: Dictable

Contains the prototype information necessary to create an object instance using :class:`.ImportConfigFactoryModule.

__init__(factory, name, config_str)

property config: Any

config_str: str

The string parsed from the parethesis in the prototype string.

factory: ImportConfigFactory

The factory that created this prototype.

name: str

The name of the instance to create, which is usually the application config section name.

property params: Dict[str, Any]

exception zensols.config.importfac.RedefinedInjectionError(msg, factory=None)

Bases: FactoryError

Raised when any attempt to redefine or reuse injections for a class.

__annotations__ = {}

__module__ = 'zensols.config.importfac'

zensols.config.importini

Contains a class for importing child configurations.

class zensols.config.importini.ImportIniConfig(*args, config_section='import', exclude_config_sections=True, children=(), use_interpolation=True, **kwargs)

Bases: IniConfig

A configuration that uses other Configurable classes to load other sections. A special import section is given that indicates what other sections to load as children configuration. Each of those indicated to import are processed in order by:

1. Creating the delegate child Configurable given in the section.

2. Copying all sections from child instance to the parent.

3. Variable interpolation as a function of ConfigParser using ExtendedInterpolation.

The import section has a sections entry as list of sections to load, a references entry indicating which sections to provide as children sections in child loaders, a config_file and ``config_files` entries to load as children directly.

For example:

[import]
references = list: default, package, env
sections = list: imp_obj

[imp_obj]
type = importini
config_file = resource: resources/obj.conf

This configuration loads a resource import INI, which is an implementation of this class, and provides sections default, package and env for any property string interpolation while loading obj.conf.

See the API documentation for more information.

CLEANUPS_NAME = 'cleanups'

CONFIG_FILES = 'config_files'

IMPORT_SECTION = 'import'

REFS_NAME = 'references'

SECTIONS_SECTION = 'sections'

SINGLE_CONFIG_FILE = 'config_file'

TYPE_NAME = 'type'

__init__(*args, config_section='import', exclude_config_sections=True, children=(), use_interpolation=True, **kwargs)

Initialize.

Parameters:

• config_file – the configuration file path to read from

• default_section – default section (defaults to default)

• robust – if True, then don’t raise an error when the configuration file is missing

• config_section (str) – the name of the section that has the configuration (i.e. the sections entry)

• exclude_config_sections (bool) – if True, the import and other configuration sections are removed

• children (Tuple[Configurable, ...]) – additional configurations used both before and after bootstrapping

• use_interpolation (bool) – if True, interpolate variables using ExtendedInterpolation

zensols.config.importyaml

YAML configuration importation like ImportIniConfig.

class zensols.config.importyaml.ImportYamlConfig(config_file=None, default_section=None, sections_name='sections', sections=None, import_name='import', parse_values=False, children=())

Bases: YamlConfig

Like YamlConfig but supports configuration importation like ImportIniConfig. The list of imports is given at import_name (see initializer), and contains the same information as import sections documented in ImportIniConfig.

__init__(config_file=None, default_section=None, sections_name='sections', sections=None, import_name='import', parse_values=False, children=())

Initialize with importation configuration. The usage of default_vars in the super class is disabled since this implementation uses a mix of dot and colon (configparser) variable substitution (the later used when imported from an ImportIniConfig.

Parameters:

• config_file (Union[Path, TextIOBase]) – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_section (str) – used as the default section when non given on the get methds such as get_option(); which defaults to defualt

• sections_name (str) – the dot notated path to the variable that has a list of sections

• sections (Set[str]) – used as the set of sections for this instance

• import_name (str) – the dot notated path to the variable that has the import entries (see class docs); defaults to import

• parse_values (bool) – whether to invoke the Serializer to create in memory Python data, which defaults to false to keep data as string for configuraiton merging

zensols.config.iniconfig

Implementation classes that are used as application configuration containers parsed from files.

class zensols.config.iniconfig.CommandLineConfig(config_file=None, default_section=None, use_interpolation=False)

Bases: IniConfig

A configuration object that allows creation by using command line arguments as defaults when the configuration file is missing.

Sub classes must implement the set_defaults method. All defaults set in this method are then created in the default section of the configuration when created with the static method from_args, which is called with the parsed command line arguments (usually from some instance or instance of subclass SimpleActionCli.

classmethod from_args(config=None, *args, **kwargs)

set_default(name, value, clobber=None)

Set a default value in the default section of the configuration.

abstract set_defaults(*args, **kwargs)

class zensols.config.iniconfig.ExtendedInterpolationConfig(*args, **kwargs)

Bases: IniConfig

Configuration class extends using advanced interpolation with ExtendedInterpolation.

__init__(*args, **kwargs)

Create with a configuration file path.

Parameters:

• config_file – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_section – default section (defaults to default)

• use_interpolation – if True, interpolate variables using ExtendedInterpolation

• robust – if True, then don’t raise an error when the configuration file is missing

class zensols.config.iniconfig.ExtendedInterpolationEnvConfig(*args, remove_vars=None, env=None, env_sec='env', **kwargs)

Bases: ExtendedInterpolationConfig

An IniConfig implementation that creates a section called env with environment variables passed.

__init__(*args, remove_vars=None, env=None, env_sec='env', **kwargs)

Create with a configuration file path.

Parameters:

• config_file – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_section – default section (defaults to default)

• use_interpolation – if True, interpolate variables using ExtendedInterpolation

• robust – if True, then don’t raise an error when the configuration file is missing

class zensols.config.iniconfig.IniConfig(config_file=None, default_section=None, use_interpolation=False)

Bases: Configurable, Primeable

Application configuration utility. This reads from a configuration and returns sets or subsets of options.

__init__(config_file=None, default_section=None, use_interpolation=False)

Create with a configuration file path.

Parameters:

• config_file (Union[Path, TextIOBase]) – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_section (str) – default section (defaults to default)

• use_interpolation (bool) – if True, interpolate variables using ExtendedInterpolation

• robust – if True, then don’t raise an error when the configuration file is missing

derive_from_resource(path, copy_sections=())

Derive a new configuration from the resource file name path.

Parameters:

• path (str) – a resource file (i.e. resources/app.conf)

• copy_sections – a list of sections to copy from this to the derived configuration

Return type:

Configurable

get_option(name, section=None)

Return an option from section with name.

Parameters:

• section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

• vars – contains the defaults for missing values of name

Return type:

str

get_options(section=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, str]

get_raw_str()

“Return the contents of the configuration parser with no interpolated values.

Return type:

str

has_option(name, section=None)

Return type:

bool

property parser: ConfigParser

Load the configuration file.

prime()

reload()

Reload the configuration from the backing store.

remove_section(section)

Remove a seciton with the given name.

property sections: Set[str]

All sections of the INI file.

set_option(name, value, section=None)

Set an option on this configurable.

Parameters:

• name (str) – the name of the option

• value (str) – the value to set

• section (str) – the section (if applies) to add the option

Raises:

NotImplementedError – if this class does not support this operation

class zensols.config.iniconfig.rawconfig(config)

Bases: object

Treat all option fetching on config as raw, or without interpolation. This is usually used when config is the target of section copying with Configuration.copy_sections(),

__init__(config)

zensols.config.jsonconfig

Implementation of the JSON configurable.

class zensols.config.jsonconfig.JsonConfig(config_file, default_section=None, deep=False)

Bases: DictionaryConfig

A configurator that reads JSON as a two level dictionary. The top level keys are the section and the values are a single depth dictionary with string keys and values.

A caveat is if all the values are terminal, in which case the top level singleton section is default_section given in the initializer and the section content is the single dictionary.

__init__(config_file, default_section=None, deep=False)

Initialize.

Parameters:

• config_file (Union[Path, TextIOBase]) – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• config – configures this instance (see class docs)

• default_section (str) – used as the default section when non given on the get methds such as get_option()

zensols.config.keychain

Get passwords from the macOS Keychain.app, and optionally add as a configuraiton.

class zensols.config.keychain.Keychain(account, service='python-passwords')

Bases: object

A wrapper to macOS’s Keychain service using binary /usr/bin/security. This provides a cleartext password for the given service and account.

__init__(account, service='python-passwords')

account: str

The account, which is usually an email address.

static getpassword(account, service)

Get the password for the account and service (see class docs).

Return type:

str

property password

Get the password for the account and service provided as member variables (see class docs).

service: str = 'python-passwords'

the service (grouping in Keychain.app)

class zensols.config.keychain.KeychainConfig(account, user=None, service='python-passwords', default_section='keychain')

Bases: DictionaryConfig

A configuration that adds a user and password based on a macOS Keychain.app entry. The account (user name) and service (a grouping in Keychain.app) is provided and the password is fetched.

Example:

[import]
sections = list: keychain_imp

[keychain_imp]
type = keychain
account = my-user-name
default_section = login

__init__(account, user=None, service='python-passwords', default_section='keychain')

Initialize.

Parameters:

• account (str) – the account (usually an email address) used to fetch in Keychain.app

• user (str) – the name of the user to use in the generated entry, which defaults to acount

• service (str) – the service (grouping in Keychain.app)

• default_section (str) – used as the default section when non given on the get methds such as get_option()

zensols.config.meta

This file contains utility classes for exploring complex instance graphs. This is handy for deeply nested Stash instances.

class zensols.config.meta.ClassExplorer(include_classes, exclude_classes=None, indent=4, attr_truncate_len=80, include_dicts=False, include_private=False, dictify_dataclasses=False)

Bases: Writable

A utility class that recursively reports class metadata in an object graph.

ATTR_META_NAME = 'ATTR_EXP_META'

The attribute name set on classes to find to report their fields. When the value of this is set as a class attribute, each of that object instances’ members are pretty printed. The value is a tuple of string attribute names.

__init__(include_classes, exclude_classes=None, indent=4, attr_truncate_len=80, include_dicts=False, include_private=False, dictify_dataclasses=False)

get_metadata(inst)

Return type:

dict

write(inst, depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write the contents of this instance to writer using indention depth.

Parameters:

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

write_metadata(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, metadata=None)

zensols.config.serial

Simple string based serialization.

class zensols.config.serial.PythonObjectEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

class zensols.config.serial.Serializer(allow_types=<factory>, allow_classes=<factory>)

Bases: object

This class is used to parse values in to Python literals and object instances in configuration files.

BOOL_REGEXP = re.compile('^True|False')

CLASS_REGEXP = re.compile('^class:\\s*(.+)$')

DEFAULT_RESOURCE_MODULE = None

EVAL_REGEXP = re.compile('^(?:eval|dict)(?:\\((.+)\\))?:\\s*(.+)$', re.DOTALL)

FLOAT_REGEXP = re.compile('^[-+]?\\d*\\.\\d+$')

INT_REGEXP = re.compile('^[-+]?[0-9]+$')

JSON_REGEXP = re.compile('^json:\\s*(.+)$', re.DOTALL)

LIST_REGEXP = re.compile('^(list|set|tuple)(?:\\((.+)\\))?:\\s*(.+)$', re.DOTALL)

PATH_REGEXP = re.compile('^path:\\s*(.+)$')

PRIMITIVES = {<class 'NoneType'>, <class 'bool'>, <class 'float'>, <class 'int'>}

RESOURCE_REGEXP = re.compile('^resource(?:\\((.+)\\))?:\\s*(.+)$', re.DOTALL)

SCI_REGEXP = re.compile('^([+-]?(?:0|[1-9]\\d*)(?:\\.\\d*)?(?:[eE][+\\-]?\\d+))$')

STRING_REGEXP = re.compile('^str:\\s*(.+)$', re.DOTALL)

__init__(allow_types=<factory>, allow_classes=<factory>)

allow_classes: Tuple[type, ...]

allow_types: Set[type]

format_option(obj)

Format a Python object in to the string represetation per object syntax rules.

See:

parse_object()

Return type:

str

is_allowed_type(value)

Return type:

bool

parse_list(v)

Parse a comma separated list in to a string list.

Any whitespace is trimmed around the commas.

Return type:

List[str]

parse_object(v)

Parse as a string in to a Python object. The following is done to parse the string in order: :rtype: Any

1. Primitive (i.e. 1.23 is a float, True is a boolean).

2. A pathlib.Path object when prefixed with path:.

3. Evaluate using the Python parser when prefixed eval:.

4. Evaluate as JSON when prefixed with json:.

populate_state(state, obj=None, parse_types=True)

Populate an object with a string dictionary. The keys are used for the output, and the values are parsed in to Python objects using parse_object(). The keys in the input are used as the same keys if obj is a dict. Otherwise, set data as attributes on the object with setattr().

Parameters:

• state (Dict[str, str]) – the data to parse

• obj (Union[dict, object]) – the object to populate

Return type:

Union[dict, object]

resource_filename(resource_name, module_name=None)

Return a resource based on a file name. This uses the pkg_resources package first to find the resources. If the resource module does not exist, it defaults to the relateve file given in module_name. If it finds it, it returns a path on the file system.

Note that when a package is not installed, the resources directory must be in the module system path. This happens automatically when installed, otherwise symbolic links are needed.

Param:

resource_name the file name of the resource to obtain (or name if obtained from an installed module)

Parameters:

module_name (str) – the name of the module to obtain the data, which defaults to DEFAULT_RESOURCE_MODULE, which is set by zensols.cli.simple.SimpleActionCli

Return type:

Path

Returns:

a path on the file system or resource of the installed module

class zensols.config.serial.Settings(**kwargs)

Bases: Dictable

A default object used to populate in Configurable.populate() and ConfigFactory.instance().

__init__(**kwargs)

get(name, default=None)

Return type:

Any

items()

Return type:

Tuple[Tuple[Any, Any], ...]

keys()

Return type:

Iterable[Any]

zensols.config.serial.as_python_object(dct)

zensols.config.strconfig

Implementation classes that are used as application configuration containers parsed from files.

class zensols.config.strconfig.StringConfig(config_str, option_sep=',', default_section=None)

Bases: Configurable

A simple string based configuration. This takes a single comma delimited key/value pair string in the format:

<section>.<name>=<value>[,<section>.<name>=<value>,...]

A dot (.) is used to separate the section from the option instead of a colon (:), as used in more sophisticaed interpolation in the configparser.ExtendedInterpolation. The dot is used for this reason to make other section interpolation easier.

KEY_VAL_REGEX = re.compile('^(?:([^.]+?)\\.)?([^=]+?)=(.+)$')

__init__(config_str, option_sep=',', default_section=None)

Initialize with a string given as described in the class docs.

Parameters:

• config_str (str) – the configuration

• option_sep (str) – the string used to delimit the each key/value pair

• default_section (str) – used as the default section when non given on the get methds such as get_option()

get_options(section=None)

Get all options for a section. If opt_keys is given return only options with those keys.

Parameters:

section (str) – section in the ini file to fetch the value; defaults to constructor’s default_section

Return type:

Dict[str, str]

has_option(name, section=None)

Return type:

bool

property sections: Set[str]

All sections of the configuration file.

zensols.config.treeimpmod

A factory class module to create deep nested dictionaries.

zensols.config.writable

A class that allows human readable information (sometimes debugging) output with a hierarchical structure.

class zensols.config.writable.Writable

Bases: ABC

An interface for classes that have multi-line debuging capability.

classmethod _trunc(s, max_len=None)

Return type:

str

_sp(depth)

Utility method to create a space string.

Return type:

str

_set_indent(indent=None)

Set the indentation for the instance. By default, this value is 4.

Parameters:

indent (int) – the value to set as the indent for this instance, or None to unset it

_write_line(line, depth, writer, max_len=False, repl_newlines=False)

Write a line of text line with the correct indentation per depth to writer.

Parameters:

max_line – truncate to the given length if an int or WRITABLE_MAX_COL if True

Repl_newlines:

whether to replace newlines with spaces

_write_block(lines, depth, writer, limit=None)

Write a block of text with indentation.

Parameters:

limit (int) – the max number of lines in the block to write

_write_wrap(text, depth, writer, width=None, **kwargs)

Like _write_line() but wrap text per width.

Parameters:

• text (str) – the text to word wrap

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

• width (int) – the width of the text before wrapping, which defaults to WRITABLE_MAX_COL

• kwargs – the keyword arguments given to textwarp.wrap()

_write_object(obj, depth, writer)

Write an object based on the class of the instance.

_write_iterable(data, depth, writer, include_index=None)

Write list data with the correct indentation per depth to writer.

Parameters:

include_index (bool) – if True, add an incrementing index for each element in the output

_write_dict(data, depth, writer, inline=False, one_line=False)

Write dictionary data with the correct indentation per depth to writer.

Parameters:

• data (Dict) – the data wto write

• inline (bool) – whether to write values in one line (separate from key)

• one_line (bool) – whether to print all of data on one line

WRITABLE_INCLUDE_INDEX: ClassVar[bool] = False

Whether to include index numbers with levels in sequences.

WRITABLE_INDENT_SPACE: ClassVar[int] = 4

The default number of spaces to indent each level.

WRITABLE_MAX_COL: ClassVar[int] = 80

The default maximum column size before wrapping text.

abstract write(depth=0, writer=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write the contents of this instance to writer using indention depth.

Parameters:

• depth (int) – the starting indentation depth

• writer (TextIOBase) – the writer to dump the content of this writable

write_to_log(logger, level=20, depth=0, split_lines=True)

Just like write() but write the content to a log message.

Parameters:

• logger (Logger) – the logger to write the message containing content of this writable

• level (int) – the logging level given in the logging module

• depth (int) – the starting indentation depth

• split_lines (bool) – if True each line is logged separately

zensols.config.writeback

Observer pattern that write updates back to the configuration.

class zensols.config.writeback.Writeback(name, config_factory)

Bases: FactoryStateObserver, Dictable

Subclass for classes that want to write attribute changes back to a Configurable. This uses an observer pattern that write updates back to the configuration.

When an attribute is set on an instance of this class, it is first set using the normal Python attribute setting. After that, based on a set of criteria, the attribute and value are set on the backing configuration config. The value is clobbered with a string version based on the config’s Serializer instance (either a primitive value string or JSON string).

Implementation Note: During initialization, the __setattr__() is called by the Python interpreter, and before the instance is completely being populated.

Important: The _is_settable() implementation checks for a state (any such as CREATED) to be set on the instance. To change this behavior, you will need to overide this method.

DEFAULT_SKIP_ATTRIBUTES: ClassVar[Set[str]] = {'config', 'config_factory', 'name'}

Default set of attributes to skip when writing back to the configuration on attribute sets.

__init__(name, config_factory)

config_factory: ConfigFactory

The configuration factory that created this instance and used for serialization functions.

name: str

The name of the section given in the configuration.

zensols.config.yaml

Application configuration classes parsed from YAML files.

class zensols.config.yaml.YamlConfig(config_file=None, default_section=None, default_vars=None, delimiter='$', sections_name='sections', sections=None)

Bases: TreeConfigurable

Just like IniConfig but parse configuration from YAML files. Variable substitution works just like ini files, but you can set what delimiter to use and keys are the paths of the data in the hierarchy separated by dots.

See the test cases for examples.

CLASS_VER = 0

__init__(config_file=None, default_section=None, default_vars=None, delimiter='$', sections_name='sections', sections=None)

Initialize this instance. When sections are not set, and the sections are not given in configuration file at location sections_name the root is made a singleton section.

Parameters:

• config_file (Union[str, Path, TextIOBase]) – the configuration file path to read from; if the type is an instance of io.TextIOBase, then read it as a file object

• default_vars (Dict[str, Any]) – used in place of missing variables duing value interpolation; deprecated: this will go away in a future release

• default_section (str) – used as the default section when non given on the get methds such as get_option(); which defaults to defualt

• delimiter (str) – the delimiter used for template replacement with dot syntax, or None for no template replacement

• sections_name (str) – the dot notated path to the variable that has a list of sections

• sections (Set[str]) – used as the set of sections for this instance

Module contents

Contains modules that provide configuration utility.

exception zensols.config.ConfigurationError

Bases: APIError

Thrown for any configuration error in this module.

__annotations__ = {}

__module__ = 'zensols.config'