Document powerline.lint.spec.Spec object
This commit is contained in:
ZyX
parent
b781c72348
commit
e9c9b6519f
|
|
@ -12,6 +12,51 @@ from powerline.lint.selfcheck import havemarks
|
|||
|
||||
|
||||
class Spec(object):
|
||||
'''Class that describes some JSON value
|
||||
|
||||
In powerline it is only used to describe JSON values stored in powerline
|
||||
configuration.
|
||||
|
||||
:param dict keys:
|
||||
Dictionary that maps keys that may be present in the given JSON
|
||||
dictionary to their descriptions. If this parameter is not empty it
|
||||
implies that described value has dictionary type. Non-dictionary types
|
||||
must be described using ``Spec()``: without arguments.
|
||||
|
||||
.. note::
|
||||
Methods that create the specifications return ``self``, so calls to them
|
||||
may be chained: ``Spec().type(unicode).re('^\w+$')``. This does not
|
||||
apply to functions that *apply* specification like :py:meth`Spec.match`.
|
||||
|
||||
.. note::
|
||||
Methods starting with ``check_`` return two values: first determines
|
||||
whether caller should proceed on running other checks, second
|
||||
determines whether there were any problems (i.e. whether error was
|
||||
reported). One should not call these methods directly: there is
|
||||
:py:meth:`Spec.match` method for checking values.
|
||||
|
||||
.. note::
|
||||
In ``check_`` and ``match`` methods specifications are identified by
|
||||
their indexes for the purpose of simplyfying :py:meth:`Spec.copy`
|
||||
method.
|
||||
|
||||
Some common parameters:
|
||||
|
||||
``data``:
|
||||
Whatever data supplied by the first caller for checker functions. Is not
|
||||
processed by :py:class:`Spec` methods in any fashion.
|
||||
``context``:
|
||||
:py:class:`powerline.lint.context.Context` instance, describes context
|
||||
of the value. :py:class:`Spec` methods only use its ``.key`` methods for
|
||||
error messages.
|
||||
``echoerr``:
|
||||
Callable that should be used to echo errors. Is supposed to take four
|
||||
optional keyword arguments: ``problem``, ``problem_mark``, ``context``,
|
||||
``context_mark``.
|
||||
``value``:
|
||||
Checked value.
|
||||
'''
|
||||
|
||||
def __init__(self, **keys):
|
||||
self.specs = []
|
||||
self.keys = {}
|
||||
|
|
@ -24,6 +69,13 @@ class Spec(object):
|
|||
self.update(**keys)
|
||||
|
||||
def update(self, **keys):
|
||||
'''Describe additional keys that may be present in given JSON value
|
||||
|
||||
If called with some keyword arguments implies that described value is
|
||||
a dictionary. If called without keyword parameters it is no-op.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
for k, v in keys.items():
|
||||
self.keys[k] = len(self.specs)
|
||||
self.specs.append(v)
|
||||
|
|
@ -33,6 +85,14 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def copy(self, copied=None):
|
||||
'''Deep copy the spec
|
||||
|
||||
:param dict copied:
|
||||
Internal dictionary used for storing already copied values. This
|
||||
parameter should not be used.
|
||||
|
||||
:return: New :py:class:`Spec` object that is a deep copy of ``self``.
|
||||
'''
|
||||
copied = copied or {}
|
||||
try:
|
||||
return copied[id(self)]
|
||||
|
|
@ -42,6 +102,15 @@ class Spec(object):
|
|||
return self.__class__()._update(self.__dict__, copied)
|
||||
|
||||
def _update(self, d, copied):
|
||||
'''Helper for the :py:meth:`Spec.copy` function
|
||||
|
||||
Populates new instance with values taken from the old one.
|
||||
|
||||
:param dict d:
|
||||
``__dict__`` of the old instance.
|
||||
:param dict copied:
|
||||
Storage for already copied values.
|
||||
'''
|
||||
self.__dict__.update(d)
|
||||
self.keys = copy(self.keys)
|
||||
self.checks = copy(self.checks)
|
||||
|
|
@ -50,6 +119,30 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def unknown_spec(self, keyfunc, spec):
|
||||
'''Define specification for non-static keys
|
||||
|
||||
This method should be used if key names cannot be determined at runtime
|
||||
or if a number of keys share identical spec (in order to not repeat it).
|
||||
:py:meth:`Spec.match` method processes dictionary in the given order:
|
||||
|
||||
* First it tries to use specifications provided at the initialization or
|
||||
by the :py:meth:`Spec.update` method.
|
||||
* If no specification for given key was provided it processes
|
||||
specifications from ``keyfunc`` argument in order they were supplied.
|
||||
Once some key matches specification supplied second ``spec`` argument
|
||||
is used to determine correctness of the value.
|
||||
|
||||
:param Spec keyfunc:
|
||||
:py:class:`Spec` instance or a regular function that returns two
|
||||
values (the same :py:meth:`Spec.match` returns). This argument is
|
||||
used to match keys that were not provided at initialization or via
|
||||
:py:meth:`Spec.update`.
|
||||
:param Spec spec:
|
||||
:py:class:`Spec` instance that will be used to check keys matched by
|
||||
``keyfunc``.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
if isinstance(keyfunc, Spec):
|
||||
self.specs.append(keyfunc)
|
||||
keyfunc = len(self.specs) - 1
|
||||
|
|
@ -58,10 +151,31 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def unknown_msg(self, msgfunc):
|
||||
'''Define message which will be used when unknown key was found
|
||||
|
||||
“Unknown” is a key that was not provided at the initialization and via
|
||||
:py:meth:`Spec.update` and did not match any ``keyfunc`` proided via
|
||||
:py:meth:`Spec.unknown_spec`.
|
||||
|
||||
:param msgfunc:
|
||||
Function that takes that unknown key as an argument and returns the
|
||||
message text. Text will appear at the top (start of the sentence).
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.ufailmsg = msgfunc
|
||||
return self
|
||||
|
||||
def context_message(self, msg):
|
||||
'''Define message that describes context
|
||||
|
||||
:param str msg:
|
||||
Message that describes context. Is written using the
|
||||
:py:meth:`str.format` syntax and is expected to display keyword
|
||||
parameter ``key``.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.cmsg = msg
|
||||
for spec in self.specs:
|
||||
if not spec.cmsg:
|
||||
|
|
@ -69,6 +183,15 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def check_type(self, value, context_mark, data, context, echoerr, types):
|
||||
'''Check that given value matches given type(s)
|
||||
|
||||
:param tuple types:
|
||||
List of accepted types. Since :py:class:`Spec` is supposed to
|
||||
describe JSON values only ``dict``, ``list``, ``unicode``, ``bool``,
|
||||
``float`` and ``NoneType`` types make any sense.
|
||||
|
||||
:return: proceed, hadproblem.
|
||||
'''
|
||||
havemarks(value)
|
||||
if type(value.value) not in types:
|
||||
echoerr(
|
||||
|
|
@ -85,6 +208,34 @@ class Spec(object):
|
|||
return True, False
|
||||
|
||||
def check_func(self, value, context_mark, data, context, echoerr, func, msg_func):
|
||||
'''Check value using given function
|
||||
|
||||
:param function func:
|
||||
Callable that should accept four positional parameters:
|
||||
|
||||
#. checked value,
|
||||
#. ``data`` parameter with arbitrary data (supplied by top-level
|
||||
caller),
|
||||
#. current context and
|
||||
#. function used for echoing errors.
|
||||
|
||||
This callable should return three values:
|
||||
|
||||
#. determines whether ``check_func`` caller should proceed
|
||||
calling other checks,
|
||||
#. determines whether ``check_func`` should echo error on its own
|
||||
(it should be set to False if ``func`` echoes error itself) and
|
||||
#. determines whether function has found some errors in the checked
|
||||
value.
|
||||
|
||||
:param function msg_func:
|
||||
Callable that takes checked value as the only positional parameter
|
||||
and returns a string that describes the problem. Only useful for
|
||||
small checker functions since it is ignored when second returned
|
||||
value is false.
|
||||
|
||||
:return: proceed, hadproblem.
|
||||
'''
|
||||
havemarks(value)
|
||||
proceed, echo, hadproblem = func(value, data, context, echoerr)
|
||||
if echo and hadproblem:
|
||||
|
|
@ -95,6 +246,19 @@ class Spec(object):
|
|||
return proceed, hadproblem
|
||||
|
||||
def check_list(self, value, context_mark, data, context, echoerr, item_func, msg_func):
|
||||
'''Check that each value in the list matches given specification
|
||||
|
||||
:param function item_func:
|
||||
Callable like ``func`` from :py:meth:`Spec.check_func`. Unlike
|
||||
``func`` this callable is called for each value in the list and may
|
||||
be a :py:class:`Spec` object index.
|
||||
:param func msg_func:
|
||||
Callable like ``msg_func`` from :py:meth:`Spec.check_func`. Should
|
||||
accept one problematic item and is not used for :py:class:`Spec`
|
||||
object indicies in ``item_func`` method.
|
||||
|
||||
:return: proceed, hadproblem.
|
||||
'''
|
||||
havemarks(value)
|
||||
i = 0
|
||||
hadproblem = False
|
||||
|
|
@ -124,6 +288,17 @@ class Spec(object):
|
|||
return True, hadproblem
|
||||
|
||||
def check_either(self, value, context_mark, data, context, echoerr, start, end):
|
||||
'''Check that given value matches one of the given specifications
|
||||
|
||||
:param int start:
|
||||
First specification index.
|
||||
:param int end:
|
||||
Specification index that is greater by 1 then last specification
|
||||
index.
|
||||
|
||||
This method does not give an error if any specification from
|
||||
``self.specs[start:end]`` is matched by the given value.
|
||||
'''
|
||||
havemarks(value)
|
||||
new_echoerr = DelayedEchoErr(echoerr)
|
||||
|
||||
|
|
@ -140,6 +315,17 @@ class Spec(object):
|
|||
return False, hadproblem
|
||||
|
||||
def check_tuple(self, value, context_mark, data, context, echoerr, start, end):
|
||||
'''Check that given value is a list with items matching specifications
|
||||
|
||||
:param int start:
|
||||
First specification index.
|
||||
:param int end:
|
||||
Specification index that is greater by 1 then last specification
|
||||
index.
|
||||
|
||||
This method checks that each item in the value list matches
|
||||
specification with index ``start + item_number``.
|
||||
'''
|
||||
havemarks(value)
|
||||
hadproblem = False
|
||||
for (i, item, spec) in zip(itertools.count(), value, self.specs[start:end]):
|
||||
|
|
@ -157,6 +343,15 @@ class Spec(object):
|
|||
return True, hadproblem
|
||||
|
||||
def type(self, *args):
|
||||
'''Describe value that has one of the types given in arguments
|
||||
|
||||
:param args:
|
||||
List of accepted types. Since :py:class:`Spec` is supposed to
|
||||
describe JSON values only ``dict``, ``list``, ``unicode``, ``bool``,
|
||||
``float`` and ``NoneType`` types make any sense.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.checks.append(('check_type', args))
|
||||
return self
|
||||
|
||||
|
|
@ -177,6 +372,20 @@ class Spec(object):
|
|||
}
|
||||
|
||||
def len(self, comparison, cint, msg_func=None):
|
||||
'''Describe value that has given length
|
||||
|
||||
:param str comparison:
|
||||
Type of the comparison. Valid values: ``le``, ``lt``, ``ge``,
|
||||
``gt``, ``eq``.
|
||||
:param int cint:
|
||||
Integer with which length is compared.
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit
|
||||
something like “length of ["foo", "bar"] is not greater then 10”.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
cmp_func = self.cmp_funcs[comparison]
|
||||
msg_func = (
|
||||
msg_func
|
||||
|
|
@ -191,6 +400,25 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def cmp(self, comparison, cint, msg_func=None):
|
||||
'''Describe value that is a number or string that has given property
|
||||
|
||||
:param str comparison:
|
||||
Type of the comparison. Valid values: ``le``, ``lt``, ``ge``,
|
||||
``gt``, ``eq``. This argument will restrict the number or string to
|
||||
emit True on the given comparison.
|
||||
:param cint:
|
||||
Number or string with which value is compared. Type of this
|
||||
parameter affects required type of the checked value: ``str`` and
|
||||
``unicode`` types imply ``unicode`` values, ``float`` type implies
|
||||
that value can be either ``int`` or ``float``, ``int`` type implies
|
||||
``int`` value and for any other type the behavior is undefined.
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit
|
||||
something like “10 is not greater then 10”.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
if type(cint) is str:
|
||||
self.type(unicode)
|
||||
elif type(cint) is float:
|
||||
|
|
@ -207,6 +435,14 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def unsigned(self, msg_func=None):
|
||||
'''Describe unsigned integer value
|
||||
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.type(int)
|
||||
self.checks.append((
|
||||
'check_func',
|
||||
|
|
@ -216,6 +452,20 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def list(self, item_func, msg_func=None):
|
||||
'''Describe list with any number of elements, each matching given spec
|
||||
|
||||
:param item_func:
|
||||
:py:class:`Spec` instance or a callable. Check out
|
||||
:py:meth:`Spec.check_list` documentation for more details. Note that
|
||||
in :py:meth:`Spec.check_list` description :py:class:`Spec` instance
|
||||
is replaced with its index in ``self.specs``.
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit just
|
||||
“failed check”, which is rather indescriptive.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.type(list)
|
||||
if isinstance(item_func, Spec):
|
||||
self.specs.append(item_func)
|
||||
|
|
@ -224,6 +474,17 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def tuple(self, *specs):
|
||||
'''Describe list with the given number of elements, each matching corresponding spec
|
||||
|
||||
:param (Spec,) specs:
|
||||
List of specifications. Last element(s) in this list may be
|
||||
optional. Each element in this list describes element with the same
|
||||
index in the checked value. Check out :py:meth:`Spec.check_tuple`
|
||||
for more details, but note that there list of specifications is
|
||||
replaced with start and end indicies in ``self.specs``.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.type(list)
|
||||
|
||||
max_len = len(specs)
|
||||
|
|
@ -246,10 +507,25 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def func(self, func, msg_func=None):
|
||||
'''Describe value that is checked by the given function
|
||||
|
||||
Check out :py:meth:`Spec.check_func` documentation for more details.
|
||||
'''
|
||||
self.checks.append(('check_func', func, msg_func or (lambda value: 'failed check')))
|
||||
return self
|
||||
|
||||
def re(self, regex, msg_func=None):
|
||||
'''Describe value that is a string that matches given regular expression
|
||||
|
||||
:param str regex:
|
||||
Regular expression that should be matched by the value.
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit
|
||||
something like “String "xyz" does not match "[a-f]+"”.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.type(unicode)
|
||||
compiled = re.compile(regex)
|
||||
msg_func = msg_func or (lambda value: 'String "{0}" does not match "{1}"'.format(value, regex))
|
||||
|
|
@ -261,6 +537,15 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def ident(self, msg_func=None):
|
||||
'''Describe value that is an identifier like ``foo:bar`` or ``foo``
|
||||
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit
|
||||
something like “String "xyz" is not an … identifier”.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
msg_func = (
|
||||
msg_func
|
||||
or (lambda value: 'String "{0}" is not an alphanumeric/underscore colon-separated identifier'.format(value))
|
||||
|
|
@ -268,6 +553,17 @@ class Spec(object):
|
|||
return self.re('^\w+(?::\w+)?$', msg_func)
|
||||
|
||||
def oneof(self, collection, msg_func=None):
|
||||
'''Describe value that is equal to one of the value in the collection
|
||||
|
||||
:param set collection:
|
||||
A collection of possible values.
|
||||
:param function msg_func:
|
||||
Function that should accept checked value and return message that
|
||||
describes the problem with this value. Default value will emit
|
||||
something like “"xyz" must be one of {"abc", "def", "ghi"}”.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
msg_func = msg_func or (lambda value: '"{0}" must be one of {1!r}'.format(value, list(collection)))
|
||||
self.checks.append((
|
||||
'check_func',
|
||||
|
|
@ -277,6 +573,19 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def error(self, msg):
|
||||
'''Describe value that must not be there
|
||||
|
||||
Useful for giving more descriptive errors for some specific keys then
|
||||
just “found unknown key: shutdown_event” or for forbidding certain
|
||||
values when :py:meth:`Spec.unknown_spec` was used.
|
||||
|
||||
:param str msg:
|
||||
Message given for the offending value. It is formatted using
|
||||
:py:meth:`str.format` with the only positional parameter which is
|
||||
the value itself.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.checks.append((
|
||||
'check_func',
|
||||
(lambda *args: (True, True, True)),
|
||||
|
|
@ -285,20 +594,54 @@ class Spec(object):
|
|||
return self
|
||||
|
||||
def either(self, *specs):
|
||||
'''Describes value that matches one of the given specs
|
||||
|
||||
Check out :py:meth:`Spec.check_either` method documentation for more
|
||||
details, but note that there a list of specs was replaced by start and
|
||||
end indicies in ``self.specs``.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
start = len(self.specs)
|
||||
self.specs.extend(specs)
|
||||
self.checks.append(('check_either', start, len(self.specs)))
|
||||
return self
|
||||
|
||||
def optional(self):
|
||||
'''Mark value as optional
|
||||
|
||||
Only useful for key specs in :py:meth:`Spec.__init__` and
|
||||
:py:meth:`Spec.update` and some last supplied to :py:meth:`Spec.tuple`.
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.isoptional = True
|
||||
return self
|
||||
|
||||
def required(self):
|
||||
'''Mark value as required
|
||||
|
||||
Only useful for key specs in :py:meth:`Spec.__init__` and
|
||||
:py:meth:`Spec.update` and some last supplied to :py:meth:`Spec.tuple`.
|
||||
|
||||
.. note::
|
||||
Value is required by default. This method is only useful for
|
||||
altering existing specification (or rather its copy).
|
||||
|
||||
:return: self.
|
||||
'''
|
||||
self.isoptional = False
|
||||
return self
|
||||
|
||||
def match_checks(self, *args):
|
||||
'''Process checks registered for the given value
|
||||
|
||||
Processes only “top-level” checks: key specifications given using at the
|
||||
initialization or via :py:meth:`Spec.unknown_spec` are processed by
|
||||
:py:meth:`Spec.match`.
|
||||
|
||||
:return: proceed, hadproblem.
|
||||
'''
|
||||
hadproblem = False
|
||||
for check in self.checks:
|
||||
proceed, chadproblem = getattr(self, check[0])(*(args + check[1:]))
|
||||
|
|
@ -309,6 +652,10 @@ class Spec(object):
|
|||
return True, hadproblem
|
||||
|
||||
def match(self, value, context_mark=None, data=None, context=(), echoerr=echoerr):
|
||||
'''Check that given value matches this specification
|
||||
|
||||
:return: proceed, hadproblem.
|
||||
'''
|
||||
havemarks(value)
|
||||
proceed, hadproblem = self.match_checks(value, context_mark, data, context, echoerr)
|
||||
if proceed:
|
||||
|
|
@ -367,7 +714,11 @@ class Spec(object):
|
|||
return True, hadproblem
|
||||
|
||||
def __getitem__(self, key):
|
||||
'''Get specification for the given key
|
||||
'''
|
||||
return self.specs[self.keys[key]]
|
||||
|
||||
def __setitem__(self, key, value):
|
||||
return self.update(**{key: value})
|
||||
'''Set specification for the given key
|
||||
'''
|
||||
self.update(**{key: value})
|
||||
|
|
|
|||
Loading…
Reference in New Issue