Added validation using jsonschema

Author: tr11

CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - Allow to pass a `ignore_missing_paths` parameter to each config method
+- Support for Hashicorp Vault credentials (in `config.contrib`)
+
+### Changed
+
+- Added a `validate` method to validate `Configuration` instances against a [json schema](https://json-schema.org/understanding-json-schema/basics.html#basics).
 
 ## [0.9.0] - 2023-08-04
 

README.md

@@ -276,13 +276,62 @@ When setting the `interpolate` parameter in any `Configuration` instance, the li
 cfg = config_from_dict({
     "percentage": "{val:.3%}",
     "with_sign": "{val:+f}",
-    "val": 1.23456}, interpolate=True)
+    "val": 1.23456,
+    }, interpolate=True)
 
 assert cfg.val == 1.23456
 assert cfg.with_sign == "+1.234560"
 assert cfg.percentage == "123.456%"
 ```
 
+###### Validation
+
+Validation relies on the [jsonchema](https://github.com/python-jsonschema/jsonschema) library, which is automatically installed using the extra `validation`. To use it, call the `validate` method on any `Configuration` instance in a manner similar to what is described on the `jsonschema` library:
+
+```python
+schema = {
+    "type" : "object",
+    "properties" : {
+        "price" : {"type" : "number"},
+        "name" : {"type" : "string"},
+    },
+}
+
+cfg = config_from_dict({"name" : "Eggs", "price" : 34.99})
+assert cfg.validate(schema)
+
+cfg = config_from_dict({"name" : "Eggs", "price" : "Invalid"})
+assert not cfg.validate(schema)
+
+# pass the `raise_on_error` parameter to get the traceback of validation failures
+cfg.validate(schema, raise_on_error=True)
+# ValidationError: 'Invalid' is not of type 'number'
+```
+
+To use the [format](https://python-jsonschema.readthedocs.io/en/latest/validate/#validating-formats) feature of the `jsonschema` library, the extra dependencies must be installed separately as explained in the documentation of `jsonschema`.   
+
+```python
+from jsonschema import Draft202012Validator
+
+schema = {
+    "type" : "object",
+    "properties" : {
+        "ip" : {"format" : "ipv4"},
+    },
+}
+
+cfg = config_from_dict({"ip": "10.0.0.1"})
+assert cfg.validate(schema, format_checker=Draft202012Validator.FORMAT_CHECKER)
+
+cfg = config_from_dict({"ip": "10"})
+assert not cfg.validate(schema, format_checker=Draft202012Validator.FORMAT_CHECKER)
+
+# with the `raise_on_error` parameter:
+c.validate(schema, raise_on_error=True, format_checker=Draft202012Validator.FORMAT_CHECKER)
+# ValidationError: '10' is not a 'ipv4'
+```
+
+
 ## Extras
 
 The `config.contrib` package contains extra implementations of the `Configuration` class used for special cases. Currently the following are implemented:
@@ -311,6 +360,14 @@ The `config.contrib` package contains extra implementations of the `Configuratio
   pip install python-configuration[gcp]
   ```
 
+* `HashicorpVaultConfiguration` in `config.contrib.vault`, which takes Hashicorp Vault
+  credentials into a `Configuration`-compatible instance. To install the needed dependencies
+  execute
+
+  ```shell
+  pip install python-configuration[vault]
+  ```
+
 ## Features
 
 * Load multiple configuration types

config/configuration.py

@@ -391,6 +391,21 @@ def reload(self) -> None:  # pragma: no cover
         """
         raise NotImplementedError()
 
+    def validate(
+        self, schema: Any, raise_on_error: bool = False, **kwargs: Mapping[str, Any]
+    ) -> bool:
+        try:
+            from jsonschema import validate, ValidationError
+        except ImportError:  # pragma: no cover
+            raise RuntimeError("Validation requires the `jsonschema` library.")
+        try:
+            validate(self.as_dict(), schema, **kwargs)
+        except ValidationError as err:
+            if raise_on_error:
+                raise err
+            return False
+        return True
+
     @contextmanager
     def dotted_iter(self) -> Iterator["Configuration"]:
         """

pyproject.toml

@@ -20,6 +20,7 @@ google-cloud-secret-manager = { version = "^2.16.3", optional = true }
 hvac = { version ="^1.1.1", optional = true }
 pyyaml = { version = "^6.0", optional = true }
 toml = { version = "^0.10.0", optional = true }
+jsonschema = { version = "^4.18.6", optional = true }
 
 [tool.poetry.group.dev.dependencies]
 flake8-blind-except = "^0.2.0"
@@ -47,6 +48,7 @@ gcp = ["google-cloud-secret-manager"]
 toml = ["toml"]
 vault = ["hvac"]
 yaml = ["pyyaml"]
+validation = ["jsonschema"]
 
 [tool.black]
 line-length = 88
@@ -89,6 +91,8 @@ module= [
     'botocore.exceptions', 
     'hvac',
     'hvac.exceptions',
+    'jsonschema',
+    'jsonschema.exceptions'
 ]
 ignore_missing_imports = true
 

tests/test_validation.py

@@ -0,0 +1,93 @@
+from config import (
+    Configuration,
+    ConfigurationSet,
+    EnvConfiguration,
+    config,
+    config_from_dict,
+)
+import pytest
+
+try:
+    import jsonschema
+except ImportError:
+    jsonschema = None
+
+
+@pytest.mark.skipif("jsonschema is None")
+def test_validation_ok():  # type: ignore
+    d = {"items": [1, 3]}
+    cfg = config_from_dict(d)
+
+    schema = {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "items": {"enum": [1, 2, 3]},
+                "maxItems": 2,
+            }
+        },
+    }
+
+    assert cfg.validate(schema)
+
+
+@pytest.mark.skipif("jsonschema is None")
+def test_validation_fail():  # type: ignore
+    from jsonschema.exceptions import ValidationError
+
+    schema = {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "items": {"enum": [1, 2, 3]},
+                "maxItems": 2,
+            }
+        },
+    }
+
+    with pytest.raises(ValidationError) as err:
+        d = {"items": [1, 4]}
+        cfg = config_from_dict(d)
+        assert not cfg.validate(schema)
+        cfg.validate(schema, raise_on_error=True)
+    assert "4 is not one of [1, 2, 3]" in str(err)
+
+    with pytest.raises(ValidationError) as err:
+        d = {"items": [1, 2, 3]}
+        cfg = config_from_dict(d)
+        assert not cfg.validate(schema)
+        cfg.validate(schema, raise_on_error=True)
+    assert "[1, 2, 3] is too long" in str(err)
+
+
+@pytest.mark.skipif("jsonschema is None")
+def test_validation_format():  # type: ignore
+    from jsonschema import Draft202012Validator
+    from jsonschema.exceptions import ValidationError
+
+    schema = {
+        "type": "object",
+        "properties": {
+            "ip": {"format": "ipv4"},
+        },
+    }
+
+    cfg = config_from_dict({"ip": "10.0.0.1"})
+    assert cfg.validate(schema, format_checker=Draft202012Validator.FORMAT_CHECKER)
+
+    # this passes since we didn't specify the format checker
+    cfg = config_from_dict({"ip": "10"})
+    assert cfg.validate(schema)
+
+    # fails with the format checker
+    with pytest.raises(ValidationError) as err:
+        cfg = config_from_dict({"ip": "10"})
+        cfg.validate(
+            schema,
+            raise_on_error=True,
+            format_checker=Draft202012Validator.FORMAT_CHECKER,
+        )
+    print(str(err))
+    assert "'10' is not a 'ipv4'" in str(err)