anyconfig.api

Public APIs of anyconfig module.

Changed in version 0.10.2:

  • Re-structured APIs and split into sub modules

  • Added type hints

Changed in version 0.9.9:

Added in version 0.9.8:

  • Added new API load_plugins to [re-]load plugins

Added 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.

Added 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.

Added in version 0.8.2:

  • Added new API, version to provide version information.

Added 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.

Added 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.

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.

Added in version 0.2:

  • Export factory method (create) of anyconfig.mergeabledict.MergeableDict

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

Save data to out in specified or detected format.

Parameters:

  • data (Union[None, int, float, bool, str, Mapping[str, Any]]) – A mapping object may have configurations data to dump

  • out (Union[str, Path, IO, IOInfo]) – An output file path, a file, a file-like object, pathlib.Path object represents the file or a namedtuple ‘anyconfig.ioinfo.IOInfo’ object represents output to dump some data to.

  • ac_parser (Union[str, TypeVar(ParserT, bound= Parser), Type[TypeVar(ParserT, bound= Parser)], None]) – Forced parser type or parser object

  • options – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

Return type:

None

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

Return a str representation of data in specified format.

Parameters:

  • data (Union[None, int, float, bool, str, Mapping[str, Any]]) – Config data object to dump

  • ac_parser (Union[str, TypeVar(ParserT, bound= Parser), Type[TypeVar(ParserT, bound= Parser)], None]) – Forced parser type or ID or parser object

  • options – see dump()

Return type:

str

Returns:

Backend-specific string representation for the given data

Raises:

ValueError, UnknownProcessorTypeError

anyconfig.api.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 (Optional[Dict[str, Any]]) – 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 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

    • 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, Mapping[str, Any]]

Returns:

Mapping object

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.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 (Optional[Dict[str, Any]]) – 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 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, Mapping[str, Any]]

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 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 – 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 – 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 collections.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)

Load data from a str, content.

Parameters:

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

  • ac_parser – Forced parser type or ID 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 collections.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.open(path, mode=None, ac_parser=None, **options)

Open given file path with appropriate open flag.

Parameters:

  • path (Union[str, Path, IO, IOInfo]) – Configuration file path

  • mode (Optional[str]) – 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.

Return type:

IO

Returns:

A file object or None on any errors

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.version()

Version info.

Return type:

List[str]

Returns:

A list of version info, [major, minor, release[, e.g. [0, 8, 2]

exception anyconfig.api.UnknownFileTypeError(arg=None)

Bases: BaseError

Raise if not parsers were found for given file path.

exception anyconfig.api.UnknownParserTypeError(arg=None)

Bases: BaseError

Raise if no parsers were found for given type.

exception anyconfig.api.UnknownProcessorTypeError(arg=None)

Bases: UnknownParserTypeError

Raise if no processors were found for given type.

exception anyconfig.api.ValidationError(arg=None)

Bases: BaseError

Raise if validation failed.

anyconfig.api.merge(self, other, ac_merge='merge_dicts', **options)

Update (merge) a mapping object self with other.

other may be a mapping object or an iterable yields (key, value) tuples based on merge strategy ‘ac_merge’.

Parameters:

  • others – a list of dict[-like] objects or (key, value) tuples

  • another – optional keyword arguments to update self more

  • ac_merge (str) – Merge strategy to choose

Return type:

None

anyconfig.api.get(dic, path, seps=('/', '.'), idx_reg=re.compile('(?:0|[1-9][0-9]*)'))

Getter for nested dicts.

Parameters:

  • dic (Dict[str, Any]) – a dict[-like] object

  • path (str) – Path expression to point object wanted

  • seps (Tuple[str, ...]) – Separator char candidates

Return type:

Tuple[Any, str]

Returns:

A tuple of (result_object, error_message)

anyconfig.api.set_(dic, path, val, seps=('/', '.'))

Setter for nested dicts.

Parameters:

  • dic (Dict[str, Any]) – a dict[-like] object support recursive merge operations

  • path (str) – Path expression to point object wanted

  • seps (Tuple[str, ...]) – Separator char candidates

Return type:

None

class anyconfig.api.IOInfo(src: Path | IO, type: str, path: str, extension: str)

Bases: NamedTuple

Equivalent to collections.namedtuple.

src: Union[Path, IO]

Alias for field number 0

type: str

Alias for field number 1

path: str

Alias for field number 2

extension: str

Alias for field number 3

anyconfig.api.ioinfo_make(obj)

Make and return a datatypes.IOInfo object from obj.

Return type:

IOInfo

anyconfig.api.ioinfo_makes(obj, marker='*')

Make and return a list of datatypes.IOInfo objects.

Return type:

List[IOInfo]

anyconfig.api.load_plugins()

[Re-]Load pluggable processors.

Return type:

None

anyconfig.api.list_types()

List supported processor types.

Return type:

List[str]

anyconfig.api.list_by_cid()

List processors by each cid.

Return type:

List[Tuple[str, List[TypeVar(ParserT, bound= Parser)]]]

anyconfig.api.list_by_type()

List processor by eacch type.

Return type:

List[Tuple[str, List[TypeVar(ParserT, bound= Parser)]]]

anyconfig.api.list_by_extension()

List processor by file extension supported.

Return type:

List[Tuple[str, List[TypeVar(ParserT, bound= Parser)]]]

anyconfig.api.findall(obj=None, forced_type=None)

Find out processor objects can process data from given obj.

obj may be a file path, file or file-like object, pathlib.Path object or an ‘anyconfig.ioinfo.IOInfo’ (namedtuple) object.

Parameters:

  • obj (Union[str, Path, IO, IOInfo, None]) – a file path, file or file-like object, pathlib.Path object, an ‘anyconfig.ioinfo.IOInfo’ (namedtuple) object, or None

  • forced_type (Optional[str]) – Forced type or id of the processor

Return type:

List[TypeVar(ParserT, bound= Parser)]

Returns:

A list of instances of processor classes to process ‘obj’

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.find(obj=None, forced_type=None)

Very similar to the above findall().

However it returns a processor object instead of a list of processor objects.

Parameters:

  • obj (Union[str, Path, IO, IOInfo, None]) – a file path, file or file-like object, pathlib.Path object, an ‘anyconfig.ioinfo.IOInfo’ (namedtuple) object, or None

  • forced_type (Union[str, TypeVar(ParserT, bound= Parser), Type[TypeVar(ParserT, bound= Parser)], None]) – Forced type or id of the processor

Return type:

TypeVar(ParserT, bound= Parser)

Returns:

An instance of processor class of highest priority to process ‘obj’

Raises:

ValueError, UnknownProcessorTypeError, UnknownFileTypeError

anyconfig.api.try_query(data, jexp=None, **options)

Provide a dummy implementation of anyconfig.query.try_query().

Return type:

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

anyconfig.api.validate(data, schema, ac_schema_safe=True, ac_schema_errors=False, **options)

Provide a dummy function does not validate at all in actual.

Return type:

Tuple[bool, Union[str, List[str]]]

anyconfig.api.is_valid(data, schema, ac_schema_safe=True, ac_schema_errors=False, **options)

Provide a dummy function never raise exceptions.

Return type:

bool

anyconfig.api.gen_schema(data, **options)

Provide a dummy function generates an empty dict in actual.

Return type:

Mapping[str, Any]