summaryrefslogtreecommitdiff
path: root/docs/extensions.rst
diff options
context:
space:
mode:
authorJohan Fleury <jfleury@arcaik.net>2018-10-08 12:58:12 -0400
committerJohan Fleury <jfleury@arcaik.net>2018-10-08 12:58:12 -0400
commit735c78d3ecb695dd16cb37879880f522c4b29c72 (patch)
tree8bfb2ecbd0f03730efa1540cc65d8490b67e8ddd /docs/extensions.rst
Import upstream version 1.7.0
Diffstat (limited to 'docs/extensions.rst')
-rw-r--r--docs/extensions.rst105
1 files changed, 105 insertions, 0 deletions
diff --git a/docs/extensions.rst b/docs/extensions.rst
new file mode 100644
index 0000000..24dee64
--- /dev/null
+++ b/docs/extensions.rst
@@ -0,0 +1,105 @@
+Extensions
+==========
+
+It is possible to extend the validation of each of the three basic types, ``map`` & ``seq`` & ``scalar``.
+
+Extensions can be used to do more complex validation that is not natively supported by the core pykwalify lib.
+
+
+
+Loading extensions
+------------------
+
+There are 2 ways to load extensions into a schema.
+
+First you can specify any ``*.py`` file via the cli via the ``-e FILE`` or ``--extension FILE`` flag. If you would do this when using pykwalify as a library you should pass in a list of files to the ``extensions`` variable to the ``Core`` class.
+
+The second way is to specify a list of files in the keyword ``extensions`` that can only be specified at the top level of the schema. The files can be either relative or absolute.
+
+
+
+How custom validation works
+---------------------------
+
+Each function defined inside the extension must be defined with a globally unique method name and the following variables
+
+.. code-block:: python
+
+ def method_name(value, rule_obj, path):
+ pass
+
+To raise a validation error you can either raise any exception and it will propegate up to the caller or you can return ``True`` or ``False``. Any value/object that will be interpreted as ``False`` inside a if check will cause a ``CoreError`` validation error to be raised.
+
+When using a validation function on a ``sequence``, the method will be called with the entire list content as the value.
+
+When using a validation function on a ``mapping``, the method will be called with the entire dict content as the value.
+
+When using a validation function on any ``scalar`` type value, the method will be called with the scalar value.
+
+This is a example of how to use extensions inside a simple schema
+
+.. code-block:: yaml
+
+ # Schema
+ extensions:
+ - e.py
+ type: map
+ func: ext_map
+ mapping:
+ foo:
+ type: seq
+ func: ext_list
+ sequence:
+ - type: str
+ func: ext_str
+
+.. code-block:: yaml
+
+ # Data
+ foo:
+ - foo
+ - bar
+
+This is the extension file named ``ext.py`` that is located in the same directory as the schema file.
+
+.. code-block:: python
+
+ # -*- coding: utf-8 -*-
+ import logging
+ log = logging.getLogger(__name__)
+
+
+ def ext_str(value, rule_obj, path):
+ log.debug("value: %s", value)
+ log.debug("rule_obj: %s", rule_obj)
+ log.debug("path: %s", path)
+
+ # Either raise some exception that you have defined your self
+ # raise AssertionError('Custom assertion error in jinja_function()')
+
+ # Or you should return True/False that will tell if it validated
+ return True
+
+
+ def ext_list(value, rule_obj, path):
+ log.debug("value: %s", value)
+ log.debug("rule_obj: %s", rule_obj)
+ log.debug("path: %s", path)
+
+ # Either raise some exception that you have defined your self
+ # raise AssertionError('Custom assertion error in jinja_function()')
+
+ # Or you should return True/False that will tell if it validated
+ return True
+
+
+ def ext_map(value, rule_obj, path):
+ log.debug("value: %s", value)
+ log.debug("rule_obj: %s", rule_obj)
+ log.debug("path: %s", path)
+
+ # Either raise some exception that you have defined your self
+ # raise AssertionError('Custom assertion error in jinja_function()')
+
+ # Or you should return True/False that will tell if it validated
+ return True