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,
UnknownParserTypeError
andUnknownFileTypeError
to express specific errors.Change behavior of the API
find_loader()
and others to make them fail firt and raise exceptions (ValueError, UnknownParserTypeError 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.
-
Changed in version 0.2:
Now APIs
find_loader()
,single_load()
,multi_load()
,load()
anddump()
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.
version
()¶ - Returns
A tuple of version info, (major, minor, release), e.g. (0, 8, 2)
-
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, UnknownParserTypeError, 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()
andloads()
: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()
ofParser
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, UnknownParserTypeError, 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()
: andloads()
. See the descriptions of them insingle_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, UnknownParserTypeError, 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()
andmulti_load()
- Returns
Mapping object or any query result might be primitive objects
- Raises
ValueError, UnknownParserTypeError, 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, UnknownParserTypeError
-
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, UnknownParserTypeError, 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, UnknownParserTypeError
-
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.