anyconfig.api

Public APIs of anyconfig module.

Changed in version 0.3: Replaced forced_type optional argument of some public APIs with ac_parser to allow skip of config parser search by passing parser object previously found and instantiated.

Also removed some optional arguments, ignore_missing, merge and marker, from definitions of some public APIs as these may not be changed from default in common use cases.

Changed in version 0.2: Now APIs find_loader(), single_load(), multi_load(), load() and dump() can process a file/file-like object or a list of file/file-like objects instead of a file path or a list of file paths.

New in version 0.2: Export factory method (create) of anyconfig.mergeabledict.MergeableDict

anyconfig.api.set_loglevel(level)

Parameters:level – Log level, e.g. logging.INFO and logging.WARN.

anyconfig.api.find_loader(path_or_stream, parser_or_type=None, is_path_=None)

Find out config parser object appropriate to load from a file of given path or file/file-like object.

Parameters:

• path_or_stream – Configuration file path or file / file-like object
• parser_or_type – Forced configuration parser type or parser object
• is_path – True if given path_or_stream is a file path

Returns:

Config parser instance or None

anyconfig.api.single_load(path_or_stream, ac_parser=None, ac_template=False, ac_context=None, ac_schema=None, **kwargs)

Load single config file.

Parameters:

• path_or_stream – Configuration file path or file / file-like object
• ac_parser – Forced parser type or parser object
• ac_template – Assume configuration file may be a template file and try to compile it AAR if True
• ac_context – A dict presents context to instantiate template
• ac_schema – JSON schema file path to validate given config file
• kwargs –

  Optional keyword arguments for backends:

  • Common backend options:
    • ignore_missing: Ignore and just return empty result if given file (path_or_stream) does not exist.
  • Backend specific options such as {“indent”: 2} for JSON backend

Returns:

Dict-like object (instance of anyconfig.mergeabledict.MergeableDict by default) supports merge operations.

anyconfig.api.multi_load(paths, ac_parser=None, ac_template=False, ac_context=None, ac_schema=None, **kwargs)

Load multiple config files.

The first argument paths may be a list of config file paths or a glob pattern specifying that. That is, if a.yml, b.yml and c.yml are in the dir /etc/foo/conf.d/, the followings give same results:

multi_load(["/etc/foo/conf.d/a.yml", "/etc/foo/conf.d/b.yml",
            "/etc/foo/conf.d/c.yml", ])

multi_load("/etc/foo/conf.d/*.yml")

Parameters:

• paths – List of config file paths or a glob pattern to list paths, or a list of file/file-like objects
• ac_parser – Forced parser type or parser object
• ac_template – Assume configuration file may be a template file and try to compile it AAR if True
• ac_context – A dict presents context to instantiate template
• ac_schema – JSON schema file path to validate given config file
• kwargs –

  Optional keyword arguments:

  • Common options:
    • ac_merge (merge): Specify strategy of how to merge results loaded from multiple configuration files. See the doc of mergeabledict module for more details of strategies. The default is MS_DICTS.
    • ac_marker (marker): Globbing marker to detect paths patterns.
  • Common backend options:
    • ignore_missing: Ignore and just return empty result if given file (path_or_stream) does not exist.
  • Backend specific options such as {“indent”: 2} for JSON backend

Returns:

Dict-like object (instance of anyconfig.mergeabledict.MergeableDict by default) supports merge operations.

anyconfig.api.load(path_specs, ac_parser=None, ac_template=False, ac_context=None, ac_schema=None, **kwargs)

Load single or multiple config files or multiple config files specified in given paths pattern.

Parameters:

• path_specs – Configuration file path or paths or its pattern such as r’/a/b/*.json’ or a list of files/file-like objects
• ac_parser – Forced parser type or parser object
• ac_template – Assume configuration file may be a template file and try to compile it AAR if True
• ac_context – A dict presents context to instantiate template
• ac_schema – JSON schema file path to validate given config file
• kwargs – Optional keyword arguments. See also the description of kwargs in multi_load function.

Returns:

Dict-like object (instance of anyconfig.mergeabledict.MergeableDict by default) supports merge operations.

anyconfig.api.loads(content, ac_parser=None, ac_template=False, ac_context=None, ac_schema=None, **kwargs)

Parameters:

• content – Configuration file’s content
• ac_parser – Forced parser type or parser object
• ac_template – Assume configuration file may be a template file and try to compile it AAR if True
• ac_context – Context dict to instantiate template
• ac_schema – JSON schema content to validate given config file
• kwargs – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend

Returns:

Dict-like object (instance of anyconfig.mergeabledict.MergeableDict by default) supports merge operations.

anyconfig.api.dump(data, path_or_stream, ac_parser=None, **kwargs)

Save data as path_or_stream.

Parameters:

• data – Config data object to dump :: anyconfig.mergeabledict.MergeableDict by default
• path_or_stream – Output file path or file / file-like object
• ac_parser – Forced parser type or parser object
• kwargs – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend

anyconfig.api.dumps(data, ac_parser=None, **kwargs)

Return string representation of data in forced type format.

Parameters:

• data – Config data object to dump :: anyconfig.mergeabledict.MergeableDict by default
• ac_parser – Forced parser type or parser object
• kwargs – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend

Returns:

Backend-specific string representation for the given data