API Reference

This page documents the public API of confwire.

class confwire.Config(cfg_dict=None, cfg_text=None, filename=None)

Bases: object

A facility for config and config files.

It supports common file formats as configs: python/json/yaml. The interface is the same as a dict object and also allows access config values as attributes.

Example

>>> cfg = Config(dict(a=1, b=dict(b1=[0, 1])))
>>> cfg.a
1
>>> cfg.b
{'b1': [0, 1]}
>>> cfg.b.b1
[0, 1]
>>> cfg = Config.fromfile('tests/data/config/a.py')
>>> cfg.filename
"/home/kchen/projects/mmcv/tests/data/config/a.py"
>>> cfg.item4
'test'
>>> cfg
"Config [path: /home/kchen/projects/mmcv/tests/data/config/a.py]: "
"{'item1': [1, 2], 'item2': {'a': 0}, 'item3': True, 'item4': 'test'}"

static auto_argparser(description=None)

Generate argparser from config file automatically (experimental)

dump(file=None)

Dumps config into a file or returns a string representation of the config.

If a file argument is given, saves the config to that file using the format defined by the file argument extension.

Otherwise, returns a string representing the config. The formatting of this returned string is defined by the extension of self.filename. If self.filename is not defined, returns a string representation of a dict (lowercased and using ‘ for strings).

Examples

>>> cfg_dict = dict(item1=[1, 2], item2=dict(a=0),
...     item3=True, item4='test')
>>> cfg = Config(cfg_dict=cfg_dict)
>>> dump_file = "a.py"
>>> cfg.dump(dump_file)

Parameters:

file (str, optional) – Path of the output file where the config will be dumped. Defaults to None.

property filename

static fromfile(filename, use_predefined_variables=True, import_custom_modules=True)

static fromstring(cfg_str, file_format)

Generate config from config str.

Parameters:

• cfg_str (str) – Config str.

• file_format (str) – Config file format corresponding to the config str. Only py/yml/yaml/json type are supported now!

Returns:

Config obj.

Return type:

Config

merge_from_dict(options, allow_list_keys=True)

Merge list into cfg_dict.

Merge the dict parsed by MultipleKVAction into this cfg.

Examples

>>> options = {'model.backbone.depth': 50,
...            'model.backbone.with_cp':True}
>>> cfg = Config(dict(model=dict(backbone=dict(type='ResNet'))))
>>> cfg.merge_from_dict(options)
>>> cfg_dict = super(Config, self).__getattribute__('_cfg_dict')
>>> assert cfg_dict == dict(
...     model=dict(backbone=dict(depth=50, with_cp=True)))

>>> # Merge list element
>>> cfg = Config(dict(pipeline=[
...     dict(type='LoadImage'), dict(type='LoadAnnotations')]))
>>> options = dict(pipeline={'0': dict(type='SelfLoadImage')})
>>> cfg.merge_from_dict(options, allow_list_keys=True)
>>> cfg_dict = super(Config, self).__getattribute__('_cfg_dict')
>>> assert cfg_dict == dict(pipeline=[
...     dict(type='SelfLoadImage'), dict(type='LoadAnnotations')])

Parameters:

• options (dict) – dict of configs to merge from.

• allow_list_keys (bool) – If True, int string keys (e.g. ‘0’, ‘1’) are allowed in options and will replace the element of the corresponding index in the config if the config is a list. Default: True.

property pretty_text

property text

confwire.build_from_config(config_dict: dict, base_package: str | None = None, blocked_types=None)

Recursively build an object from a configuration dictionary.

config_dict must contain a "type" key holding a dotted import path to the callable to build, either absolute (e.g. "pkg.module.Class") or relative (e.g. ".module.Class", resolved against base_package). All other keys are passed as keyword arguments to that callable. Any value that is itself a dict is walked via build_value() so nested objects (at any depth) are built before being passed to their parent.

Parameters:

• config_dict (dict) – The configuration to build from. If it has no "type" key, it is returned unchanged (treated as a plain data dict rather than an object description).

• base_package (str, optional) – Base package to resolve a relative "type" path against. Required only when "type" starts with a dot. Default: None.

• blocked_types (set, optional) – Dotted type paths that must never be built (e.g. "os.system"). Defaults to DEFAULT_BLOCKED_TYPES when not provided.

Returns:

The instance constructed from config_dict, or config_dict itself (copied) when it has no "type" key.

Return type:

Any

Raises:

• PermissionError – If "type" matches an entry in the blocklist.

• ImportError – If "type" is a relative path and no base_package was supplied.

• ModuleNotFoundError – If the module in "type" cannot be found.

• AttributeError – If the module exists but the class/attribute does not.

Examples

>>> build_from_config(
...     {"type": "botocore.config.Config", "region_name": "us-east-1"}
... )
<botocore.config.Config object at ...>

confwire.config

class confwire.config.Config(cfg_dict=None, cfg_text=None, filename=None)

Bases: object

A facility for config and config files.

It supports common file formats as configs: python/json/yaml. The interface is the same as a dict object and also allows access config values as attributes.

Example

>>> cfg = Config(dict(a=1, b=dict(b1=[0, 1])))
>>> cfg.a
1
>>> cfg.b
{'b1': [0, 1]}
>>> cfg.b.b1
[0, 1]
>>> cfg = Config.fromfile('tests/data/config/a.py')
>>> cfg.filename
"/home/kchen/projects/mmcv/tests/data/config/a.py"
>>> cfg.item4
'test'
>>> cfg
"Config [path: /home/kchen/projects/mmcv/tests/data/config/a.py]: "
"{'item1': [1, 2], 'item2': {'a': 0}, 'item3': True, 'item4': 'test'}"

static auto_argparser(description=None)

Generate argparser from config file automatically (experimental)

dump(file=None)

Dumps config into a file or returns a string representation of the config.

If a file argument is given, saves the config to that file using the format defined by the file argument extension.

Otherwise, returns a string representing the config. The formatting of this returned string is defined by the extension of self.filename. If self.filename is not defined, returns a string representation of a dict (lowercased and using ‘ for strings).

Examples

>>> cfg_dict = dict(item1=[1, 2], item2=dict(a=0),
...     item3=True, item4='test')
>>> cfg = Config(cfg_dict=cfg_dict)
>>> dump_file = "a.py"
>>> cfg.dump(dump_file)

Parameters:

file (str, optional) – Path of the output file where the config will be dumped. Defaults to None.

property filename

static fromfile(filename, use_predefined_variables=True, import_custom_modules=True)

static fromstring(cfg_str, file_format)

Generate config from config str.

Parameters:

• cfg_str (str) – Config str.

• file_format (str) – Config file format corresponding to the config str. Only py/yml/yaml/json type are supported now!

Returns:

Config obj.

Return type:

Config

merge_from_dict(options, allow_list_keys=True)

Merge list into cfg_dict.

Merge the dict parsed by MultipleKVAction into this cfg.

Examples

>>> options = {'model.backbone.depth': 50,
...            'model.backbone.with_cp':True}
>>> cfg = Config(dict(model=dict(backbone=dict(type='ResNet'))))
>>> cfg.merge_from_dict(options)
>>> cfg_dict = super(Config, self).__getattribute__('_cfg_dict')
>>> assert cfg_dict == dict(
...     model=dict(backbone=dict(depth=50, with_cp=True)))

>>> # Merge list element
>>> cfg = Config(dict(pipeline=[
...     dict(type='LoadImage'), dict(type='LoadAnnotations')]))
>>> options = dict(pipeline={'0': dict(type='SelfLoadImage')})
>>> cfg.merge_from_dict(options, allow_list_keys=True)
>>> cfg_dict = super(Config, self).__getattribute__('_cfg_dict')
>>> assert cfg_dict == dict(pipeline=[
...     dict(type='SelfLoadImage'), dict(type='LoadAnnotations')])

Parameters:

• options (dict) – dict of configs to merge from.

• allow_list_keys (bool) – If True, int string keys (e.g. ‘0’, ‘1’) are allowed in options and will replace the element of the corresponding index in the config if the config is a list. Default: True.

property pretty_text

property text

class confwire.config.ConfigDict(*args, **kwargs)

Bases: Dict

class confwire.config.DictAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: Action

argparse action to split an argument into KEY=VALUE form on the first = and append to a dictionary. List options can be passed as comma separated values, i.e ‘KEY=V1,V2,V3’, or with explicit brackets, i.e. ‘KEY=[V1,V2,V3]’. It also support nested brackets to build list/tuple values. e.g. ‘KEY=[(V1,V2),(V3,V4)]’

confwire.config.add_args(parser, cfg, prefix='')

confwire.build

Build Python objects from "type"-tagged configuration dictionaries.

confwire.build.DEFAULT_BLOCKED_TYPES = frozenset({'builtins.eval', 'builtins.exec', 'eval', 'exec', 'os.execv', 'os.execve', 'os.execvp', 'os.execvpe', 'os.popen', 'os.remove', 'os.rmdir', 'os.spawnl', 'os.spawnv', 'os.system', 'os.unlink', 'shutil.rmtree', 'subprocess.Popen', 'subprocess.call', 'subprocess.check_call', 'subprocess.check_output', 'subprocess.run'})

Dotted "type" paths that are never allowed to be built, regardless of caller-supplied blocked_types, since they allow arbitrary code/command execution.

confwire.build.build_from_config(config_dict: dict, base_package: str | None = None, blocked_types=None)

Recursively build an object from a configuration dictionary.

config_dict must contain a "type" key holding a dotted import path to the callable to build, either absolute (e.g. "pkg.module.Class") or relative (e.g. ".module.Class", resolved against base_package). All other keys are passed as keyword arguments to that callable. Any value that is itself a dict is walked via build_value() so nested objects (at any depth) are built before being passed to their parent.

Parameters:

• config_dict (dict) – The configuration to build from. If it has no "type" key, it is returned unchanged (treated as a plain data dict rather than an object description).

• base_package (str, optional) – Base package to resolve a relative "type" path against. Required only when "type" starts with a dot. Default: None.

• blocked_types (set, optional) – Dotted type paths that must never be built (e.g. "os.system"). Defaults to DEFAULT_BLOCKED_TYPES when not provided.

Returns:

The instance constructed from config_dict, or config_dict itself (copied) when it has no "type" key.

Return type:

Any

Raises:

• PermissionError – If "type" matches an entry in the blocklist.

• ImportError – If "type" is a relative path and no base_package was supplied.

• ModuleNotFoundError – If the module in "type" cannot be found.

• AttributeError – If the module exists but the class/attribute does not.

Examples

>>> build_from_config(
...     {"type": "botocore.config.Config", "region_name": "us-east-1"}
... )
<botocore.config.Config object at ...>

confwire.build.build_value(value: Any, base_package: str | None = None, blocked_types: set | None = None)

Recursively build any dict value found while building a config.

Used by build_from_config() to walk keyword-argument values: a dict containing "type" is built via build_from_config(), a plain dict without "type" is walked key by key looking for buildable objects nested inside it, and any other value (str, int, list, etc.) is returned unchanged.

Parameters:

• value (Any) – The value to inspect and, if applicable, build.

• base_package (str) – Base package used to resolve relative "type" paths, forwarded from build_from_config().

• blocked_types (set) – Dotted type paths that must never be built, forwarded from build_from_config().

Returns:

The built object if value (or something nested inside it) describes one, otherwise value unchanged.

Return type:

Any

Examples

>>> build_value({"type": "botocore.config.Config"}, None, None)
<botocore.config.Config object at ...>
>>> build_value({"a": 1}, None, None)
{'a': 1}

confwire.utils

confwire.utils.check_file_exist(filename, msg_tmpl='file "{}" does not exist')

confwire.utils.digit_version(version_str: str, length: int = 4)

Convert a version string into a tuple of integers.

This method is usually used for comparing two versions. For pre-release versions: alpha < beta < rc.

Parameters:

• version_str (str) – The version string.

• length (int) – The maximum number of version levels. Default: 4.

Returns:

The version info in digits (integers).

Return type:

tuple[int]

confwire.utils.import_modules_from_strings(imports, allow_failed_imports=False)

Import modules from the given list of strings.

Parameters:

• imports (list | str | None) – The given module names to be imported.

• allow_failed_imports (bool) – If True, the failed imports will return None. Otherwise, an ImportError is raise. Default: False.

Returns:

The imported modules.

Return type:

list[module] | module | None

Examples

>>> osp, sys = import_modules_from_strings(
...     ['os.path', 'sys'])
>>> import os.path as osp_
>>> import sys as sys_
>>> assert osp == osp_
>>> assert sys == sys_