anyconfig.api

Public APIs of anyconfig module.

    New in version 0.9.5:
  • Added pathlib support. Now all of load and dump APIs can process pathlib.Path object basically.

  • ’ignore_missing’ keyword option for load APIs are now marked as deprecated and will be removed soon.

  • Allow to load data other than mapping objects for some backends such as JSON and YAML.

    New in version 0.8.3:
  • Added ac_dict keyword option to pass dict factory (any callable like function or class) to make dict-like object in backend parsers.

  • Added ac_query keyword option to query data with JMESPath expression.

  • Added experimental query api to query data with JMESPath expression.

  • Removed ac_namedtuple keyword option.

  • Export merge().

  • Stop exporting to_container() which was deprecated and removed.

    New in version 0.8.2:
  • Added new API, version to provide version information.

    New in version 0.8.0:
  • Removed set_loglevel API as it does not help much.

  • Added open() API to open files with appropriate open mode.

  • Added custom exception classes, UnknownProcessorTypeError and UnknownFileTypeError to express specific errors.

  • Change behavior of the API find_loader() and others to make them fail firt and raise exceptions (ValueError, UnknownProcessorTypeError or UnknownFileTypeError) as much as possible if wrong parser type for uknown file type was given.

    New in version 0.5.0:
  • Most keyword arguments passed to APIs are now position independent.

  • Added ac_namedtuple parameter to *load and *dump APIs.

    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.

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

anyconfig.api.version()
Returns:A tuple of version info, (major, minor, release), e.g. (0, 8, 2)
anyconfig.api.list_types()
anyconfig.api.find_loader(path, parser_or_type=None)

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

Parameters:
  • path – Configuration file path or file or file-like object or pathlib.Path object if it’s available
  • parser_or_type – Forced configuration parser type or parser object itself
Returns:

An instance of a class inherits Parser or None

anyconfig.api.open(path, mode=None, ac_parser=None, **options)

Open given configuration file with appropriate open flag.

Parameters:
  • path – Configuration file path
  • mode – Can be ‘r’ and ‘rb’ for reading (default) or ‘w’, ‘wb’ for writing. Please note that even if you specify ‘r’ or ‘w’, it will be changed to ‘rb’ or ‘wb’ if selected backend, xml and configobj for example, for given config file prefer that.
  • options – Optional keyword arguments passed to the internal file opening APIs of each backends such like ‘buffering’ optional parameter passed to builtin ‘open’ function.
Returns:

A file object or None on any errors

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.single_load(input_, ac_parser=None, ac_template=False, ac_context=None, **options)

Load single configuration file.

Note

load() is a preferable alternative and this API should be used only if there is a need to emphasize given input input_ is single one.

Parameters:
  • input – File path or file or file-like object or pathlib.Path object represents the file or a namedtuple ~anyconfig.globals.IOInfo object represents some input to load some data from
  • ac_parser – Forced parser type or parser object itself
  • 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
  • options

    Optional keyword arguments such as:

    • Options common in single_load(), multi_load(), load() and loads():
      • ac_dict: callable (function or class) to make mapping objects from loaded data if the selected backend can customize that such as JSON which supports that with ‘object_pairs_hook’ option, or None. If this option was not given or None, dict or OrderedDict will be used to make result as mapping object depends on if ac_ordered (see below) is True and selected backend can keep the order of items loaded. See also _container_factory() of Parser for more implementation details.
      • ac_ordered: True if you want to keep resuls ordered. Please note that order of items may be lost depends on the selected backend.
      • ac_schema: JSON schema file path to validate given config file
      • ac_query: JMESPath expression to query data
    • Common backend options:
      • ac_ignore_missing: Ignore and just return empty result if given file input_ does not exist actually.
    • Backend specific options such as {“indent”: 2} for JSON backend
Returns:

Mapping object

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.multi_load(inputs, ac_parser=None, ac_template=False, ac_context=None, **options)

Load multiple config files.

Note

load() is a preferable alternative and this API should be used only if there is a need to emphasize given inputs are multiple ones.

The first argument inputs may be a list of a file paths or a glob pattern specifying them or a pathlib.Path object represents file[s] or a namedtuple ~anyconfig.globals.IOInfo object represents some inputs to load some data from.

About glob patterns, for example, 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:
  • inputs – A list of file path or a glob pattern such as r’/a/b/*.json’to list of files, file or file-like object or pathlib.Path object represents the file or a namedtuple ~anyconfig.globals.IOInfo object represents some inputs to load some data from
  • 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 – Mapping object presents context to instantiate template
  • options

    Optional keyword arguments:

    • ac_dict, ac_ordered, ac_schema and ac_query are the options common in single_load(), multi_load(), load(): and loads(). See the descriptions of them in single_load().
    • Options specific to this function and load():
      • ac_merge (merge): Specify strategy of how to merge results loaded from multiple configuration files. See the doc of anyconfig.dicts for more details of strategies. The default is anyconfig.dicts.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 does not exist.
    • Backend specific options such as {“indent”: 2} for JSON backend
Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.load(path_specs, ac_parser=None, ac_dict=None, ac_template=False, ac_context=None, **options)

Load single or multiple config files or multiple config files specified in given paths pattern or pathlib.Path object represents config files or a namedtuple ~anyconfig.globals.IOInfo object represents some inputs.

Parameters:
  • path_specs – A list of file path or a glob pattern such as r’/a/b/*.json’to list of files, file or file-like object or pathlib.Path object represents the file or a namedtuple ~anyconfig.globals.IOInfo object represents some inputs to load some data from.
  • ac_parser – Forced parser type or parser object
  • ac_dict – callable (function or class) to make mapping object will be returned as a result or None. If not given or ac_dict is None, default mapping object used to store resutls is dict or OrderedDict if ac_ordered is True and selected backend can keep the order of items in mapping objects.
  • 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
  • options – Optional keyword arguments. See also the description of options in single_load() and multi_load()
Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.loads(content, ac_parser=None, ac_dict=None, ac_template=False, ac_context=None, **options)
Parameters:
  • content – Configuration file’s content (a string)
  • ac_parser – Forced parser type or parser object
  • ac_dict – callable (function or class) to make mapping object will be returned as a result or None. If not given or ac_dict is None, default mapping object used to store resutls is dict or OrderedDict if ac_ordered is True and selected backend can keep the order of items in mapping objects.
  • 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
  • options – Optional keyword arguments. See also the description of options in single_load() function.
Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError

anyconfig.api.dump(data, out, ac_parser=None, **options)

Save data to out.

Parameters:
  • data – A mapping object may have configurations data to dump
  • out – An output file path or a file or a file-like object or a pathlib.Path object represents the file or a namedtuple ~anyconfig.globals.IOInfo object represents output to dump some data to.
  • ac_parser – Forced parser type or parser object
  • options – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend
Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

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

Return string representation of data in forced type format.

Parameters:
  • data – Config data object to dump
  • ac_parser – Forced parser type or parser object
  • options – see dump()
Returns:

Backend-specific string representation for the given data

Raises:

ValueError, UnknownProcessorTypeError

anyconfig.api.query(data, expression, **options)

API just wraps anyconfig.query.query().

Parameters:
  • data – Config data object to query
  • expression – JMESPath expression to query data
  • options – Ignored in current implementation
Returns:

Query result object may be a primitive (int, str, etc.) or dict.