anyconfig.api._load

Provides the API to load objects from given files.

anyconfig.api._load.try_to_load_schema(**options)

Try to load a schema object for validation.

Parameters:

options (Any) –

Optional keyword arguments such as

• 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

• ac_schema: JSON schema file path to validate configuration files

Return type:

dict[str, Any] | None

Returns:

Mapping object or None means some errors

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

Load from single input input\_.

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_ (Union[str, Path, IO, IOInfo]) – File path or file or file-like object or pathlib.Path object represents the file or a namedtuple ‘anyconfig.ioinfo.IOInfo’ object represents some input to load some data from

• ac_parser (Union[str, Parser, None]) – Forced parser type or parser object itself

• ac_template (bool) – Assume configuration file may be a template file and try to compile it AAR if True

• ac_context (dict[str, Any] | None) – A dict presents context to instantiate template

• options (Any) –

  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 collections.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 anyconfig.backend.base.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

    • ac_parse_value: Parse given string as a value in some loaders if True

  • 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

Return type:

Union[None, int, float, bool, str, dict[str, Any]]

Returns:

Mapping object

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

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

Load data from multiple inputs inputs.

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.ioinfo.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 (Union[Iterable[Union[str, Path, IO, IOInfo]], str, Path, IO, IOInfo]) – 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.ioinfo.IOInfo’ object represents some inputs to load some data from

• ac_parser (Union[str, Parser, None]) – Forced parser type or parser object

• ac_template (bool) – Assume configuration file may be a template file and try to compile it AAR if True

• ac_context (dict[str, Any] | None) – Mapping object presents context to instantiate template

• options (Any) –

  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 dicts for more details of strategies. The default is dicts.MS_DICTS.

  • 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

Return type:

Union[None, int, float, bool, str, dict[str, Any]]

Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

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

Load from a file or files specified as path_specs.

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.ioinfo.IOInfo’ object represents some inputs.

Parameters:

• path_specs (Union[Iterable[Union[str, Path, IO, IOInfo]], str, Path, IO, IOInfo]) – 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.ioinfo.IOInfo’ object represents some inputs to load some data from.

• ac_parser (str | None) – Forced parser type or parser object

• ac_dict (Callable | None) – 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 collections.OrderedDict if ac_ordered is True and selected backend can keep the order of items in mapping objects.

• ac_template (bool) – Assume configuration file may be a template file and try to compile it AAR if True

• ac_context (dict[str, Any] | None) – A dict presents context to instantiate template

• options (Any) – Optional keyword arguments. See also the description of ‘options’ in single_load() and multi_load()

Return type:

Union[None, int, float, bool, str, dict[str, Any]]

Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api._load.loads(content, ac_parser=None, *, ac_dict=None, ac_template=False, ac_context=None, **options)

Load data from a str, content.

Parameters:

• content (str) – Configuration file’s content (a string)

• ac_parser (Union[str, Parser, None]) – Forced parser type or ID or parser object

• ac_dict (Callable | None) – 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 collections.OrderedDict if ac_ordered is True and selected backend can keep the order of items in mapping objects.

• ac_template (str | bool) – Assume configuration file may be a template file and try to compile it AAR if True

• ac_context (dict[str, Any] | None) – Context dict to instantiate template

• options (Any) – Optional keyword arguments. See also the description of ‘options’ in single_load() function.

Return type:

Union[None, int, float, bool, str, dict[str, Any]]

Returns:

Mapping object or any query result might be primitive objects

Raises:

ValueError, UnknownProcessorTypeError