anyconfig.api
¶
Public APIs of anyconfig module.
-
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_or_stream, parser_or_type=None, is_path_=False)¶ Find out parser object appropriate to load configuration from a file of given path or file or file-like object.
Parameters: - path_or_stream – Configuration file path or file or file-like object
- parser_or_type – Forced configuration parser type or parser object itself
- is_path – Specify True if given path_or_stream is a file path
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
-
anyconfig.api.
single_load
(path_or_stream, 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 file path is single one.Parameters: - path_or_stream – Configuration file path or file or file-like object
- 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
- 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
- Common backend options:
- ignore_missing: Ignore and just return empty result if given file
(
path_or_stream
) does not exist.
- ignore_missing: Ignore and just return empty result if given file
(
- Backend specific options such as {“indent”: 2} for JSON backend
- Options common in
Returns: Mapping object
-
anyconfig.api.
multi_load
(paths, 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 file paths are multiple ones.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 configuration file paths or a glob pattern to list of these paths, or a list of file or 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 – 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.
- ac_merge (merge): Specify strategy of how to merge results loaded
from multiple configuration files. See the doc of
- Common backend options:
- ignore_missing: Ignore and just return empty result if given file
(
path_or_stream
) does not exist.
- ignore_missing: Ignore and just return empty result if given file
(
- Backend specific options such as {“indent”: 2} for JSON backend
- ac_dict, ac_ordered, ac_schema and ac_query are the options common in
Returns: Mapping object or any query result might be primitive objects
-
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.
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_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
-
anyconfig.api.
loads
(content, ac_parser=None, ac_dict=None, ac_template=False, ac_context=None, **options)¶ Parameters: - content – Configuration file’s content
- 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
-
anyconfig.api.
dump
(data, path_or_stream, ac_parser=None, **options)¶ Save data as path_or_stream.
Parameters: - data – A mapping object may have configurations data to dump
- path_or_stream – Output file path or file / file-like object
- ac_parser – Forced parser type or parser object
- options – Backend specific optional arguments, e.g. {“indent”: 2} for JSON loader/dumper backend
-
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
-
anyconfig.api.
query
(data, expression, **options)¶ API just wraps
anyconfig.query.query()
.Parameters: - data – Config data object to query
- options – Ignored in current implementation
Returns: Query result object may be primitive (int, str, etc.) or dict.