import os
import re
import enum
import pathlib
from collections import abc
from . import util
from . import exceptions
REQUIRED = object()
"""A sentinel indicating that there is no default value and an exception
should be raised when the value is missing.
"""
[docs]
class Template(object):
"""A value template for configuration fields.
The template works like a type and instructs Confuse about how to
interpret a deserialized YAML value. This includes type conversions,
providing a default value, and validating for errors. For example, a
filepath type might expand tildes and check that the file exists.
"""
[docs]
def __init__(self, default=REQUIRED):
"""Create a template with a given default value.
If `default` is the sentinel `REQUIRED` (as it is by default),
then an error will be raised when a value is missing. Otherwise,
missing values will instead return `default`.
"""
self.default = default
def __call__(self, view):
"""Invoking a template on a view gets the view's value according
to the template.
"""
return self.value(view, self)
[docs]
def value(self, view, template=None):
"""Get the value for a `ConfigView`.
May raise a `NotFoundError` if the value is missing (and the
template requires it) or a `ConfigValueError` for invalid values.
"""
try:
value, _ = view.first()
return self.convert(value, view)
except exceptions.NotFoundError:
pass
# Get default value, or raise if required.
return self.get_default_value(view.name)
[docs]
def get_default_value(self, key_name='default'):
"""Get the default value to return when the value is missing.
May raise a `NotFoundError` if the value is required.
"""
if not hasattr(self, 'default') or self.default is REQUIRED:
# The value is required. A missing value is an error.
raise exceptions.NotFoundError(u"{} not found".format(key_name))
# The value is not required.
return self.default
[docs]
def convert(self, value, view):
"""Convert the YAML-deserialized value to a value of the desired
type.
Subclasses should override this to provide useful conversions.
May raise a `ConfigValueError` when the configuration is wrong.
"""
# Default implementation does no conversion.
return value
[docs]
def fail(self, message, view, type_error=False):
"""Raise an exception indicating that a value cannot be
accepted.
`type_error` indicates whether the error is due to a type
mismatch rather than a malformed value. In this case, a more
specific exception is raised.
"""
exc_class = (
exceptions.ConfigTypeError if type_error
else exceptions.ConfigValueError)
raise exc_class(u'{0}: {1}'.format(view.name, message))
def __repr__(self):
return '{0}({1})'.format(
type(self).__name__,
'' if self.default is REQUIRED else repr(self.default),
)
[docs]
class Integer(Template):
"""An integer configuration value template.
"""
[docs]
def convert(self, value, view):
"""Check that the value is an integer. Floats are rounded.
"""
if isinstance(value, int):
return value
elif isinstance(value, float):
return int(value)
else:
self.fail(u'must be a number', view, True)
[docs]
class Number(Template):
"""A numeric type: either an integer or a floating-point number.
"""
[docs]
def convert(self, value, view):
"""Check that the value is an int or a float.
"""
if isinstance(value, (int, float)):
return value
else:
self.fail(
u'must be numeric, not {0}'.format(type(value).__name__),
view,
True
)
[docs]
class MappingTemplate(Template):
"""A template that uses a dictionary to specify other types for the
values for a set of keys and produce a validated `AttrDict`.
"""
[docs]
def __init__(self, mapping):
"""Create a template according to a dict (mapping). The
mapping's values should themselves either be Types or
convertible to Types.
"""
subtemplates = {}
for key, typ in mapping.items():
subtemplates[key] = as_template(typ)
self.subtemplates = subtemplates
[docs]
def value(self, view, template=None):
"""Get a dict with the same keys as the template and values
validated according to the value types.
"""
out = AttrDict()
for key, typ in self.subtemplates.items():
out[key] = typ.value(view[key], self)
return out
def __repr__(self):
return 'MappingTemplate({0})'.format(repr(self.subtemplates))
[docs]
class Sequence(Template):
"""A template used to validate lists of similar items,
based on a given subtemplate.
"""
[docs]
def __init__(self, subtemplate):
"""Create a template for a list with items validated
on a given subtemplate.
"""
self.subtemplate = as_template(subtemplate)
[docs]
def value(self, view, template=None):
"""Get a list of items validated against the template.
"""
out = []
for item in view.sequence():
out.append(self.subtemplate.value(item, self))
return out
def __repr__(self):
return 'Sequence({0})'.format(repr(self.subtemplate))
[docs]
class MappingValues(Template):
"""A template used to validate mappings of similar items,
based on a given subtemplate applied to the values.
All keys in the mapping are considered valid, but values
must pass validation by the subtemplate. Similar to the
Sequence template but for mappings.
"""
[docs]
def __init__(self, subtemplate):
"""Create a template for a mapping with variable keys
and item values validated on a given subtemplate.
"""
self.subtemplate = as_template(subtemplate)
[docs]
def value(self, view, template=None):
"""Get a dict with the same keys as the view and the
value of each item validated against the subtemplate.
"""
out = {}
for key, item in view.items():
out[key] = self.subtemplate.value(item, self)
return out
def __repr__(self):
return 'MappingValues({0})'.format(repr(self.subtemplate))
[docs]
class String(Template):
"""A string configuration value template.
"""
[docs]
def __init__(self, default=REQUIRED, pattern=None, expand_vars=False):
"""Create a template with the added optional `pattern` argument,
a regular expression string that the value should match.
"""
super(String, self).__init__(default)
self.pattern = pattern
self.expand_vars = expand_vars
if pattern:
self.regex = re.compile(pattern)
def __repr__(self):
args = []
if self.default is not REQUIRED:
args.append(repr(self.default))
if self.pattern is not None:
args.append('pattern=' + repr(self.pattern))
return 'String({0})'.format(', '.join(args))
[docs]
def convert(self, value, view):
"""Check that the value is a string and matches the pattern.
"""
if not isinstance(value, str):
self.fail(u'must be a string', view, True)
if self.pattern and not self.regex.match(value):
self.fail(
u"must match the pattern {0}".format(self.pattern),
view
)
if self.expand_vars:
return os.path.expandvars(value)
else:
return value
[docs]
class Choice(Template):
"""A template that permits values from a sequence of choices.
Sequences, dictionaries and :class:`Enum` types are supported,
see :meth:`__init__` for usage.
"""
[docs]
def __init__(self, choices, default=REQUIRED):
"""Create a template that validates any of the values from the
iterable `choices`.
If `choices` is a map, then the corresponding value is emitted.
Otherwise, the value itself is emitted.
If `choices` is a `Enum`, then the enum entry with the value is
emitted.
"""
super(Choice, self).__init__(default)
self.choices = choices
[docs]
def convert(self, value, view):
"""Ensure that the value is among the choices (and remap if the
choices are a mapping).
"""
if (isinstance(self.choices, type)
and issubclass(self.choices, enum.Enum)):
try:
return self.choices(value)
except ValueError:
self.fail(
u'must be one of {0!r}, not {1!r}'.format(
[c.value for c in self.choices], value
),
view
)
if value not in self.choices:
self.fail(
u'must be one of {0!r}, not {1!r}'.format(
list(self.choices), value
),
view
)
if isinstance(self.choices, abc.Mapping):
return self.choices[value]
else:
return value
def __repr__(self):
return 'Choice({0!r})'.format(self.choices)
[docs]
class OneOf(Template):
"""A template that permits values complying to one of the given templates.
"""
[docs]
def __init__(self, allowed, default=REQUIRED):
super(OneOf, self).__init__(default)
self.allowed = list(allowed)
def __repr__(self):
args = []
if self.allowed is not None:
args.append('allowed=' + repr(self.allowed))
if self.default is not REQUIRED:
args.append(repr(self.default))
return 'OneOf({0})'.format(', '.join(args))
[docs]
def value(self, view, template):
self.template = template
return super(OneOf, self).value(view, template)
[docs]
def convert(self, value, view):
"""Ensure that the value follows at least one template.
"""
is_mapping = isinstance(self.template, MappingTemplate)
for candidate in self.allowed:
try:
if is_mapping:
if isinstance(candidate, Filename) and \
candidate.relative_to:
next_template = candidate.template_with_relatives(
view,
self.template
)
next_template.subtemplates[view.key] = as_template(
candidate
)
else:
next_template = MappingTemplate({view.key: candidate})
return view.parent.get(next_template)[view.key]
else:
return view.get(candidate)
except exceptions.ConfigTemplateError:
raise
except exceptions.ConfigError:
pass
except ValueError as exc:
raise exceptions.ConfigTemplateError(exc)
self.fail(
u'must be one of {0}, not {1}'.format(
repr(self.allowed), repr(value)
),
view
)
[docs]
class StrSeq(Template):
"""A template for values that are lists of strings.
Validates both actual YAML string lists and single strings. Strings
can optionally be split on whitespace.
"""
[docs]
def __init__(self, split=True, default=REQUIRED):
"""Create a new template.
`split` indicates whether, when the underlying value is a single
string, it should be split on whitespace. Otherwise, the
resulting value is a list containing a single string.
"""
super(StrSeq, self).__init__(default)
self.split = split
def _convert_value(self, x, view):
if isinstance(x, str):
return x
elif isinstance(x, bytes):
return x.decode('utf-8', 'ignore')
else:
self.fail(u'must be a list of strings', view, True)
[docs]
def convert(self, value, view):
if isinstance(value, bytes):
value = value.decode('utf-8', 'ignore')
if isinstance(value, str):
if self.split:
value = value.split()
else:
value = [value]
else:
try:
value = list(value)
except TypeError:
self.fail(u'must be a whitespace-separated string or a list',
view, True)
return [self._convert_value(v, view) for v in value]
[docs]
class Pairs(StrSeq):
"""A template for ordered key-value pairs.
This can either be given with the same syntax as for `StrSeq` (i.e. without
values), or as a list of strings and/or single-element mappings such as::
- key: value
- [key, value]
- key
The result is a list of two-element tuples. If no value is provided, the
`default_value` will be returned as the second element.
"""
[docs]
def __init__(self, default_value=None):
"""Create a new template.
`default` is the dictionary value returned for items that are not
a mapping, but a single string.
"""
super(Pairs, self).__init__(split=True)
self.default_value = default_value
def _convert_value(self, x, view):
try:
return (super(Pairs, self)._convert_value(x, view),
self.default_value)
except exceptions.ConfigTypeError:
if isinstance(x, abc.Mapping):
if len(x) != 1:
self.fail(u'must be a single-element mapping', view, True)
k, v = util.iter_first(x.items())
elif isinstance(x, abc.Sequence):
if len(x) != 2:
self.fail(u'must be a two-element list', view, True)
k, v = x
else:
# Is this even possible? -> Likely, if some !directive cause
# YAML to parse this to some custom type.
self.fail(u'must be a single string, mapping, or a list'
u'' + str(x),
view, True)
return (super(Pairs, self)._convert_value(k, view),
super(Pairs, self)._convert_value(v, view))
[docs]
class Filename(Template):
"""A template that validates strings as filenames.
Filenames are returned as absolute, tilde-free paths.
Relative paths are relative to the template's `cwd` argument
when it is specified. Otherwise, if the paths come from a file,
they will be relative to the configuration directory (see the
`config_dir` method) by default or to the base directory of the
config file if either the source has `base_for_paths` set to True
or the template has `in_source_dir` set to True. Paths from sources
without a file are relative to the current working directory. This
helps attain the expected behavior when using command-line options.
"""
[docs]
def __init__(self, default=REQUIRED, cwd=None, relative_to=None,
in_app_dir=False, in_source_dir=False):
"""`relative_to` is the name of a sibling value that is
being validated at the same time.
`in_app_dir` indicates whether the path should be resolved
inside the application's config directory (even when the setting
does not come from a file).
`in_source_dir` indicates whether the path should be resolved
relative to the directory containing the source file, if there is
one, taking precedence over the application's config directory.
"""
super(Filename, self).__init__(default)
self.cwd = cwd
self.relative_to = relative_to
self.in_app_dir = in_app_dir
self.in_source_dir = in_source_dir
def __repr__(self):
args = []
if self.default is not REQUIRED:
args.append(repr(self.default))
if self.cwd is not None:
args.append('cwd=' + repr(self.cwd))
if self.relative_to is not None:
args.append('relative_to=' + repr(self.relative_to))
if self.in_app_dir:
args.append('in_app_dir=True')
if self.in_source_dir:
args.append('in_source_dir=True')
return 'Filename({0})'.format(', '.join(args))
def resolve_relative_to(self, view, template):
if not isinstance(template, (abc.Mapping, MappingTemplate)):
# disallow config.get(Filename(relative_to='foo'))
raise exceptions.ConfigTemplateError(
u'relative_to may only be used when getting multiple values.'
)
elif self.relative_to == view.key:
raise exceptions.ConfigTemplateError(
u'{0} is relative to itself'.format(view.name)
)
elif self.relative_to not in view.parent.keys():
# self.relative_to is not in the config
self.fail(
(
u'needs sibling value "{0}" to expand relative path'
).format(self.relative_to),
view
)
old_template = {}
old_template.update(template.subtemplates)
# save time by skipping MappingTemplate's init loop
next_template = MappingTemplate({})
next_relative = self.relative_to
# gather all the needed templates and nothing else
while next_relative is not None:
try:
# pop to avoid infinite loop because of recursive
# relative paths
rel_to_template = old_template.pop(next_relative)
except KeyError:
if next_relative in template.subtemplates:
# we encountered this config key previously
raise exceptions.ConfigTemplateError((
u'{0} and {1} are recursively relative'
).format(view.name, self.relative_to))
else:
raise exceptions.ConfigTemplateError((
u'missing template for {0}, needed to expand {1}\'s'
u'relative path'
).format(self.relative_to, view.name))
next_template.subtemplates[next_relative] = rel_to_template
next_relative = rel_to_template.relative_to
return view.parent.get(next_template)[self.relative_to]
[docs]
def value(self, view, template=None):
try:
path, source = view.first()
except exceptions.NotFoundError:
return self.get_default_value(view.name)
if not isinstance(path, str):
self.fail(
u'must be a filename, not {0}'.format(type(path).__name__),
view,
True
)
path = os.path.expanduser(str(path))
if not os.path.isabs(path):
if self.cwd is not None:
# relative to the template's argument
path = os.path.join(self.cwd, path)
elif self.relative_to is not None:
path = os.path.join(
self.resolve_relative_to(view, template),
path,
)
elif ((source.filename and self.in_source_dir)
or (source.base_for_paths and not self.in_app_dir)):
# relative to the directory the source file is in.
path = os.path.join(os.path.dirname(source.filename), path)
elif source.filename or self.in_app_dir:
# From defaults: relative to the app's directory.
path = os.path.join(view.root().config_dir(), path)
return os.path.abspath(path)
[docs]
class Path(Filename):
"""A template that validates strings as `pathlib.Path` objects.
Filenames are parsed equivalent to the `Filename` template and then
converted to `pathlib.Path` objects.
"""
[docs]
def value(self, view, template=None):
value = super(Path, self).value(view, template)
if value is None:
return
import pathlib
return pathlib.Path(value)
[docs]
class Optional(Template):
"""A template that makes a subtemplate optional.
If the value is present and not null, it must validate against the
subtemplate. However, if the value is null or missing, the template will
still validate, returning a default value. If `allow_missing` is False,
the template will not allow missing values while still permitting null.
"""
[docs]
def __init__(self, subtemplate, default=None, allow_missing=True):
self.subtemplate = as_template(subtemplate)
if default is None:
# When no default is passed, try to use the subtemplate's
# default value as the default for this template
try:
default = self.subtemplate.get_default_value()
except exceptions.NotFoundError:
pass
self.default = default
self.allow_missing = allow_missing
[docs]
def value(self, view, template=None):
try:
value, _ = view.first()
except exceptions.NotFoundError:
if self.allow_missing:
# Value is missing but not required
return self.default
# Value must be present even though it can be null. Raise an error.
raise exceptions.NotFoundError(u'{} not found'.format(view.name))
if value is None:
# None (ie, null) is always a valid value
return self.default
return self.subtemplate.value(view, self)
def __repr__(self):
return 'Optional({0}, {1}, allow_missing={2})'.format(
repr(self.subtemplate),
repr(self.default),
self.allow_missing,
)
[docs]
class TypeTemplate(Template):
"""A simple template that checks that a value is an instance of a
desired Python type.
"""
[docs]
def __init__(self, typ, default=REQUIRED):
"""Create a template that checks that the value is an instance
of `typ`.
"""
super(TypeTemplate, self).__init__(default)
self.typ = typ
[docs]
def convert(self, value, view):
if not isinstance(value, self.typ):
self.fail(
u'must be a {0}, not {1}'.format(
self.typ.__name__,
type(value).__name__,
),
view,
True
)
return value
[docs]
class AttrDict(dict):
"""A `dict` subclass that can be accessed via attributes (dot
notation) for convenience.
"""
def __getattr__(self, key):
if key in self:
return self[key]
else:
raise AttributeError(key)
def __setattr__(self, key, value):
self[key] = value
[docs]
def as_template(value):
"""Convert a simple "shorthand" Python value to a `Template`.
"""
if isinstance(value, Template):
# If it's already a Template, pass it through.
return value
elif isinstance(value, abc.Mapping):
# Dictionaries work as templates.
return MappingTemplate(value)
elif value is int:
return Integer()
elif isinstance(value, int):
return Integer(value)
elif isinstance(value, type) and issubclass(value, str):
return String()
elif isinstance(value, str):
return String(value)
elif isinstance(value, set):
# convert to list to avoid hash related problems
return Choice(list(value))
elif isinstance(value, type) and issubclass(value, enum.Enum):
return Choice(value)
elif isinstance(value, list):
return OneOf(value)
elif value is float:
return Number()
elif isinstance(value, float):
return Number(value)
elif isinstance(value, pathlib.PurePath):
return Path(value)
elif value is None:
return Template(None)
elif value is REQUIRED:
return Template()
elif value is dict:
return TypeTemplate(abc.Mapping)
elif value is list:
return TypeTemplate(abc.Sequence)
elif isinstance(value, type):
return TypeTemplate(value)
else:
raise ValueError(u'cannot convert to template: {0!r}'.format(value))