configconfig¶
Load and validate YAML configuration files.
Docs |
|
---|---|
Tests |
|
PyPI |
|
Anaconda |
|
Activity |
|
QA |
|
Other |
Installation¶
python3 -m pip install configconfig --user
First add the required channels
conda config --add channels https://conda.anaconda.org/conda-forge
conda config --add channels https://conda.anaconda.org/domdfcoding
Then install
conda install configconfig
python3 -m pip install git+https://github.com/repo-helper/configconfig@master --user
Contents¶
configconfig.autoconfig
¶
A Sphinx directive for documenting YAML configuration values.
Provides the autoconfig
directive to document configuration
values automatically, the conf
directive to document them manually,
and the conf
role to link to a conf
directive.
Attention
This module has the following additional requirements:
docutils sphinx<3.4.0,>=3.0.3 sphinx-toolbox
These can be installed as follows:
python -m pip install configconfig[sphinx]
Usage¶
-
.. autoconfig::
¶ Directive to automatically document an YAML configuration value.
Takes a single argument, either the fully qualified name of the
ConfigVar
object, or the name of the module if the:category:
option is given.-
:category:
(string)¶ (optional) The category of options to document.
-
-
.. conf::
¶ Directive to document an YAML configuration value.
-
:conf:
¶ Role to add a cross-reference to a
conf
orautoconfig
directive.
API Reference¶
Classes:
|
Sphinx directive to automatically document an YAML configuration value. |
Functions:
|
Parse the content of a |
|
Setup Sphinx Extension. |
-
class
AutoConfigDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
SphinxDirective
Sphinx directive to automatically document an YAML configuration value.
Methods:
document_config_var
(var_obj)Document the given configuration value.
run
()Process the content of the directive.
-
parse_conf_node
(env, text, node)[source]¶ Parse the content of a
conf
directive.- Parameters:
env (
BuildEnvironment
) – The Sphinx build environment.text (
str
) – The content of the directive.node (
desc_signature
) – The docutils node class.
- Return type:
configconfig.configvar
¶
-
class
ConfigVar
(raw_config_vars: Dict[str, Any])[source]¶ Base class for
YAML
configuration values.The class docstring should be the description of the config var, with an example, and the name of the class should be the variable name.
Alternatively, for a more Pythonic naming approach, the variable name can be set with the
name
class variable.Example:
class platforms(ConfigVar): """ A case-insensitive list of platforms to perform tests for. Example: .. code-block:: yaml platforms: - Windows - Linux These values determine the GitHub test workflows to enable, and the Trove classifiers used on PyPI. """ dtype = List[Literal["Windows", "macOS", "Linux"]] default: List[str] = ["Windows", "macOS", "Linux"] category: str = "packaging"
Attributes:
The category the
ConfigVar
is listed under in the documentation.The default value of the configuration value if it is optional.
The allowed type or types in the
YAML
configuration file.Flag to indicate whether the configuration value is required.
The variable type passed to Jinja2.
Methods:
get
([raw_config_vars])Returns the value of this
ConfigVar
.Returns the reStructuredText documentation for the
ConfigVar
.validate
([raw_config_vars])Validate the value obtained from the
YAML
file and coerce into the appropriate return type.validator
(value)Function to call to validate the values.
-
default
= ''¶ Type:
Union
[Callable
[[Dict
[str
,Any
]],Any
],Any
]The default value of the configuration value if it is optional. Defaults to
''
if unset.May also be set to a callable which returns a dynamic or mutable default value.
-
classmethod
make_documentation
()[source]¶ Returns the reStructuredText documentation for the
ConfigVar
.- Return type:
-
required
= False¶ Type:
bool
Flag to indicate whether the configuration value is required. Default
False
.
-
rtype
= typing.Any¶ Type:
Type
The variable type passed to Jinja2. If
None
dtype
is used. Ignored fordtype=bool
.
-
classmethod
validate
(raw_config_vars=None)[source]¶ Validate the value obtained from the
YAML
file and coerce into the appropriate return type.
-
classmethod
validator
(value)[source]¶ Function to call to validate the values.
The callable must have a single required argument (the value).
Should raise
ValueError
if values are invalid, and return the values if they are valid.May change the values (e.g. make lowercase) before returning.
- Return type:
-
configconfig.metaclass
¶
-
class
ConfigVarMeta
(name: str, bases, dct: Dict)[source]¶ Bases:
type
Metaclass for configuration values.
Methods:
__call__
(raw_config_vars)Alias for
ConfigVar.get
.__repr__
()Return a string representation of the
ConfigVarMeta
class.get_schema_entry
([schema])Returns the JSON schema entry for this configuration value.
-
__call__
(raw_config_vars)[source]¶ Alias for
ConfigVar.get
.Returns the value of the
ConfigVar
.- Parameters:
raw_config_vars (
Dict
[str
,Any
]) – Dictionary to obtain the value from.- Return type:
See the
ConfigVar.rtype
attribute.
-
__repr__
()[source]¶ Return a string representation of the
ConfigVarMeta
class.- Return type:
-
configconfig.parser
¶
-
class
Parser
(allow_unknown_keys=False)[source]¶ Base class for YAML configuration parsers.
Custom parsing steps for each configuration variable can be implemented with methods in the form:
def visit_<configuration value name>( self, raw_config_vars: Dict[str, Any], ) -> Any: ...
The method must return the value to set the configuration variable to, or raise an error in the case of invalid input.
A final custom parsing step, useful when several values must be set at once, may be implemented in the
custom_parsing
method:def custom_parsing( self, raw_config_vars: Mapping[str, Any], parsed_config_vars: MutableMapping[str, Any], filename: PathPlus, ) -> MutableMapping[str, Any]: ...
This takes the mapping of raw configuration variables, the mapping of parsed variables (those set with the
visit_<configuration value name>
method), and the configuration file name. The method must return theparsed_config_vars
.Methods:
custom_parsing
(raw_config_vars, …)Custom parsing step.
run
(filename)Parse configuration from the given file.
configconfig.testing
¶
Helpers for testing ConfigVar
.
Attention
This module has the following additional requirement:
pytest
This can be installed as follows:
python -m pip install configconfig[testing]
New in version 0.2.0.
Classes:
Test for boolean configuration values which default to |
|
Test for boolean configuration values which default to |
|
Base class for tests of |
|
|
Test for dictionary configuration values. |
Test for configuration values which represent directories. |
|
|
Test for |
|
Test for list configuration values. |
Mixin to add tests for |
|
Mixin to add tests for |
|
Mixin to add tests for |
|
Test for string configuration values which are optional. |
|
Test for string configuration values which are required. |
-
class
NotIntTest
[source]¶ Bases:
ConfigVarTest
Mixin to add tests for
ConfigVar
s that can’t be integers.-
test_error_int
()[source]¶ Checks that the
ConfigVar
raises aValueError
when passed anint
.
-
-
class
NotBoolTest
[source]¶ Bases:
ConfigVarTest
Mixin to add tests for
ConfigVar
s that can’t be boolean values.-
test_error_bool
()[source]¶ Checks that the
ConfigVar
raises aValueError
when passed abool
.
-
-
class
NotStrTest
[source]¶ Bases:
ConfigVarTest
Mixin to add tests for
ConfigVar
s that can’t be strings.-
test_error_str
()[source]¶ Checks that the
ConfigVar
raises aValueError
when passed astr
.
-
-
class
ListTest
[source]¶ Bases:
NotStrTest
,NotBoolTest
,NotIntTest
,ConfigVarTest
Test for list configuration values.
Attributes:
The default value that should be returned when no valid is given.
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A value that is valid and should be returned unchanged.
Methods:
Checks that the
ConfigVar
can correctly parse variouslist
values.-
default_value
= []¶ -
The default value that should be returned when no valid is given.
-
-
class
DirectoryTest
[source]¶ Bases:
NotBoolTest
,NotIntTest
,ConfigVarTest
Test for configuration values which represent directories.
Attributes:
The default value that should be returned when no valid is given.
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A value that is valid and should be returned unchanged.
Methods:
Checks that the
ConfigVar
raises aValueError
when passed astr
.Checks that the
ConfigVar
raises aValueError
when passed astr
.Checks that the
ConfigVar
can correctly parse various directory values.-
different_key_value
= {'username': 'domdfcoding'}¶ -
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
-
test_error_list_int
()[source]¶ Checks that the
ConfigVar
raises aValueError
when passed astr
.
-
test_error_list_str
()[source]¶ Checks that the
ConfigVar
raises aValueError
when passed astr
.
-
-
class
BoolTrueTest
[source]¶ Bases:
ConfigVarTest
Test for boolean configuration values which default to
True
.Attributes:
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A list of values which should be considered
False
by theConfigVar
.A list of values which should be considered
True
by theConfigVar
.A list of values which should are of the wrong type.
Methods:
-
different_key_value
= {'username': 'domdfcoding'}¶ -
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
-
-
class
BoolFalseTest
[source]¶ Bases:
BoolTrueTest
Test for boolean configuration values which default to
False
.Attributes:
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A list of values which should be considered
False
by theConfigVar
.A list of values which should be considered
True
by theConfigVar
.Methods:
-
different_key_value
= {'username': 'domdfcoding'}¶ -
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
-
-
class
RequiredStringTest
[source]¶ Bases:
ConfigVarTest
Test for string configuration values which are required.
Methods:
Attributes:
A value that is valid and should be returned unchanged.
A list of values which should are of the wrong type.
-
class
OptionalStringTest
[source]¶ Bases:
RequiredStringTest
Test for string configuration values which are optional.
Attributes:
The default value that should be returned when no valid is given.
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A list of values which should are of the wrong type.
Methods:
-
class
EnumTest
[source]¶ Bases:
RequiredStringTest
Test for
Enum
configuration values.Attributes:
The default value that should be returned when no valid is given.
A list of values which are of the correct type but are invalid.
Methods:
-
class
DictTest
[source]¶ Bases:
NotStrTest
,NotBoolTest
,NotIntTest
,ConfigVarTest
Test for dictionary configuration values.
Attributes:
The default value that should be returned when no valid is given.
A dictionary containing one or more keys that are not the keys used by the
ConfigVar
A value that is valid and should be returned unchanged.
Methods:
-
default_value
= {}¶ -
The default value that should be returned when no valid is given.
-
configconfig.utils
¶
Utility functions.
Functions:
|
Returns a tuple of permitted values for a |
|
Returns either the configuration value, the default, or raises an error if the value is required but wasn’t supplied. |
|
Get the YAML type that corresponds to the given Python type. |
|
Create a |
|
Check if the type of |
|
Get the type for the JSON schema that corresponds to the given Python type. |
-
get_literal_values
(literal)[source]¶ Returns a tuple of permitted values for a
typing.Literal
.New in version 0.3.0.
-
optional_getter
(raw_config_vars, cls, required)[source]¶ Returns either the configuration value, the default, or raises an error if the value is required but wasn’t supplied.
-
make_schema
(*configuration_variables)[source]¶ Create a
JSON
schema from a list ofConfigVar
classes.
-
check_union
(obj, dtype)[source]¶ Check if the type of
obj
is one of the types in atyping.Union
,typing.List
etc.
configconfig.validator
¶
Validate values obtained from the YAML
file and coerce into the appropriate return types.
Classes:
|
Methods are named |
Functions:
|
Validate the given datafiles against the given schema. |
-
class
Validator
(config_var)[source]¶ Bases:
object
Methods are named
visit_<type>
.Methods:
Called when the desired type has no visitor.
validate
([raw_config_vars])Validate the configuration value.
visit_bool
(raw_config_vars)Used to validate and convert
bool
values.visit_dict
(raw_config_vars)Used to validate and convert
dict
values.visit_float
(raw_config_vars)Used to validate and convert
float
values.visit_int
(raw_config_vars)Used to validate and convert
int
values.visit_list
(raw_config_vars)Used to validate and convert
list
values.visit_literal
(raw_config_vars)Used to validate and convert
typing.Literal
values.visit_str
(raw_config_vars)Used to validate and convert
str
values.visit_union
(raw_config_vars)Used to validate and convert
typing.Union
values.
Downloading source code¶
The configconfig
source code is available on GitHub,
and can be accessed from the following URL: https://github.com/repo-helper/configconfig
If you have git
installed, you can clone the repository with the following command:
git clone https://github.com/repo-helper/configconfig
Cloning into 'configconfig'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

Downloading a ‘zip’ file of the source code¶
Building from source¶
The recommended way to build configconfig
is to use tox:
tox -e build
The source and wheel distributions will be in the directory dist
.
If you wish, you may also use pep517.build or another PEP 517-compatible build tool.
License¶
configconfig
is licensed under the MIT License
A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.
Permissions | Conditions | Limitations |
---|---|---|
|
|
Copyright (c) 2020 Dominic Davis-Foster
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
View the Function Index or browse the Source Code.