PySerials 0.0.0.dev2__py3-none-any.whl → 0.0.0.dev4__py3-none-any.whl

pyserials/exception/validate.py

@@ -1,12 +1,16 @@
 """Exceptions raised by `pyserials.validate` module."""
 
+from __future__ import annotations
+from typing import Any as _Any, Literal as _Literal
 
-from typing import Any as _Any
+import jsonschema as _jsonschema
+from markitup.html import elem as _html
+from markitup.md import elem as _md
+from pyserials import write as _write
+from pyserials.exception import _base
 
-from pyserials.exception._base import PySerialsException as _PySerialsException
 
-
-class PySerialsValidateException(_PySerialsException):
+class PySerialsValidateException(_base.PySerialsException):
     """Base class for all exceptions raised by `pyserials.validate` module.
 
     Attributes
@@ -21,53 +25,219 @@ class PySerialsValidateException(_PySerialsException):
 
     def __init__(
         self,
-        message: str,
+        description: str,
         data: dict | list | str | int | float | bool,
         schema: dict,
         validator: _Any,
+        registry: _Any = None,
+        description_html: str | _html.Element | None = None,
     ):
-        message = (
-            "Failed to validate data against schema "
-            f"using validator '{validator.__class__.__name__}'; {message}."
+        validator_name = validator.__class__.__name__
+        message_template = "Failed to validate data against schema using validator {validator_name}."
+        validator_name_console, validator_name_html = _base.format_code(validator_name)
+        super().__init__(
+            message=message_template.format(validator_name=validator_name_console),
+            message_html=message_template.format(validator_name=validator_name_html),
+            description=description,
+            description_html=description_html,
+            report_heading="PySerials Schema Validation Error Report",
         )
-        super().__init__(message=message)
         self.data = data
         self.schema = schema
         self.validator = validator
+        self.registry = registry
         return
 
 
-class PySerialsSchemaValidationError(PySerialsValidateException):
-    """Exception raised when data validation fails due to the data being invalid against the schema."""
+class PySerialsInvalidJsonSchemaError(PySerialsValidateException):
+    """Exception raised when data validation fails due to the schema being invalid."""
 
     def __init__(
         self,
         data: dict | list | str | int | float | bool,
         schema: dict,
         validator: _Any,
+        registry: _Any = None,
     ):
         super().__init__(
-            message="the data is invalid",
+            description="The schema is invalid.",
             data=data,
             schema=schema,
             validator=validator,
+            registry=registry,
         )
         return
 
 
-class PySerialsInvalidSchemaError(PySerialsValidateException):
-    """Exception raised when data validation fails due to the schema being invalid."""
+class PySerialsJsonSchemaValidationError(PySerialsValidateException):
+    """Exception raised when data validation fails due to the data being invalid against the schema."""
 
     def __init__(
         self,
+        causes: list[_jsonschema.exceptions.ValidationError],
         data: dict | list | str | int | float | bool,
         schema: dict,
         validator: _Any,
+        registry: _Any = None,
     ):
+        self.causes = causes
+        description, description_html = self._parse_errors()
         super().__init__(
-            message="the schema is invalid",
+            description=description,
+            description_html=description_html,
             data=data,
             schema=schema,
             validator=validator,
+            registry=registry,
         )
         return
+
+    def _report_content(
+        self, mode: _Literal["full", "short"], md: bool
+    ) -> list[str | _html.Element] | str | _html.Element | None:
+        html_details = []
+        for idx, error in enumerate(self.causes):
+            section_html = self._report_error(error, section=[idx + 1], mode=mode, md=md)
+            html_details.append(section_html)
+        return _html.ul([_html.li(detail) for detail in html_details])
+
+    def _parse_errors(self) -> tuple[str, str]:
+        count_errors = len(self.causes)
+        errors = "an error" if count_errors == 1 else f"{count_errors} errors"
+        intro = intro_html = f"Found {errors} in the data at "
+        reports = []
+        errors_loc = []
+        errors_loc_html = []
+        for idx, error in enumerate(self.causes):
+            error_loc, error_loc_html = _base.format_code(error.json_path)
+            errors_loc.append(error_loc)
+            errors_loc_html.append(error_loc_html)
+            section_console = self._parse_error(error, section=[idx + 1])
+            reports.extend(section_console)
+        reports_str = "\n".join(reports)
+        if len(errors_loc) == 1:
+            errors_loc_str = errors_loc[0]
+            errors_loc_html_str = errors_loc_html[0]
+        elif len(errors_loc) == 2:
+            errors_loc_str = " and ".join(errors_loc)
+            errors_loc_html_str = " and ".join(errors_loc_html)
+        else:
+            errors_loc_str = ", ".join(errors_loc[:-1]) + " and " + errors_loc[-1]
+            errors_loc_html_str = ", ".join(errors_loc_html[:-1]) + " and " + errors_loc_html[-1]
+        intro += f"{errors_loc_str}:\n\n{reports_str}"
+        intro_html += f"{errors_loc_html_str}."
+        return intro, intro_html
+
+    def _parse_error(
+        self,
+        error: _jsonschema.exceptions.ValidationError,
+        section: list[int]
+    ) -> list:
+        schema_path = self._create_path(error.absolute_schema_path)
+        title, _ = _base.format_code(error.json_path)
+        console = [
+            _base.ansi_heading(section, title),
+            f"- {_base.ansi_bold('Problem')}: {self._parse_error_message(error)}",
+            f"- {_base.ansi_bold("Validator Path")}: {schema_path}",
+        ]
+        if error.context:
+            console.append(f"- {_base.ansi_bold("Context")}:")
+            for idx, sub_error in enumerate(sorted(error.context, key=lambda x: len(x.context))):
+                sub_console = self._parse_error(
+                    sub_error,
+                    section=section + [idx+1]
+                )
+                console.extend(self._indent(sub_console, 2))
+        return console
+
+    def _report_error(
+        self,
+        error: _jsonschema.exceptions.ValidationError,
+        section: list[int],
+        mode: _Literal["full", "short"],
+        md: bool
+    ) -> _html.Details:
+        details = [
+            _html.p(f"{_html.b("Problem")}: {self._parse_error_message(error)}"),
+            self._create_validator_details(error, mode=mode, md=md),
+            self._create_schema_details(error, mode=mode, md=md),
+            self._create_instance_details(error, mode=mode, md=md),
+        ]
+        if error.context:
+            contexts = []
+            for idx, sub_error in enumerate(sorted(error.context, key=lambda x: len(x.context))):
+                sub_html = self._report_error(
+                    sub_error,
+                    section=section + [idx+1],
+                    mode=mode,
+                    md=md,
+                )
+                contexts.append(sub_html)
+            context_list = _html.ul([_html.li(context) for context in contexts])
+            details.append(f"{_html.b("Context")}: {context_list}")
+        _, title = _base.format_code(error.json_path)
+        html = _html.details(
+            [_html.summary(title), _html.ul([_html.li(elem) for elem in details])]
+        )
+        return html
+
+    def _create_validator_details(self, error: _jsonschema.exceptions.ValidationError, mode: _Literal["full", "short"], md: bool) -> _html.Details:
+        summary = self._create_details_summary("Validator", str(error.validator))
+        return summary if mode == "short" else self._make_details(
+            content=error.validator_value,
+            summary=summary,
+            md=md,
+        )
+
+    def _create_schema_details(self, error: _jsonschema.exceptions.ValidationError, mode: _Literal["full", "short"], md: bool) -> _html.Details:
+        summary = self._create_details_summary("Schema", self._create_path(error.absolute_schema_path))
+        return summary if mode == "short" else self._make_details(
+            content=error.schema,
+            summary=summary,
+            md=md,
+        )
+
+    def _create_instance_details(self, error: _jsonschema.exceptions.ValidationError, mode: _Literal["full", "short"], md: bool) -> _html.Details:
+        summary = self._create_details_summary("Instance", self._create_path(error.absolute_path))
+        return summary if mode == "short" else self._make_details(
+            content=error.instance,
+            summary=summary,
+            md=md,
+        )
+
+    @staticmethod
+    def _make_details(content: dict, summary: str, md: bool) -> _html.Details:
+        yaml = _write.to_yaml_string(content, end_of_file_newline=False)
+        details_summary = _html.summary(summary)
+        details_content = _html.pre(
+            _html.code(yaml, {"class": "language-yaml"})
+        ) if not md else _md.code_fence(yaml, info="yaml")
+        return _html.details([details_summary, details_content])
+
+    def _create_title(self, error: _jsonschema.exceptions.ValidationError) -> tuple[str, str]:
+        problem = self._parse_error_message(error)
+        title_shell = f"'{error.json_path}': {problem}"
+        title_html = f"{_html.code(error.json_path)}: {problem}"
+        return title_shell, title_html
+
+    @staticmethod
+    def _parse_error_message(error: _jsonschema.exceptions.ValidationError) -> str:
+        instance_str = str(error.instance)
+        if error.message.startswith(instance_str):
+            msg = error.message.removeprefix(str(error.instance)).strip()
+            problem = f"Data {msg}"
+        else:
+            problem = error.message
+        return problem
+
+    @staticmethod
+    def _indent(text: list, indent: int = 2) -> list:
+        return [f"{' ' * indent}{line}" for line in text]
+
+    @staticmethod
+    def _create_path(path):
+        return "$." + ".".join(str(path_component) for path_component in path)
+
+    @staticmethod
+    def _create_details_summary(title: str, code: str) -> str:
+        return f"{_html.b(title)}: {_html.code(code)}"

pyserials/nested_dict.py

@@ -0,0 +1,124 @@
+import pyserials as _ps
+
+
+class NestedDict:
+
+    def __init__(
+        self,
+        data: dict | None = None,
+        template_marker_start: str = "${{",
+        template_marker_end: str = "}}",
+        template_implicit_root: bool = True,
+    ):
+        self._data = data or {}
+        self._templater = _ps.update.TemplateFiller(
+            marker_start=template_marker_start,
+            marker_end=template_marker_end,
+            implicit_root=template_implicit_root,
+        )
+        return
+
+    def fill(
+        self,
+        path: str = "",
+        always_list: bool = False,
+        recursive: bool = True,
+    ):
+        if not path:
+            value = self._data
+        else:
+            value = self.__getitem__(path)
+        if not value:
+            return
+        filled_value = self.fill_data(data=value, current_path=path, always_list=always_list, recursive=recursive)
+        if not path:
+            self._data = filled_value
+        else:
+            self.__setitem__(path, filled_value)
+        return filled_value
+
+    def fill_data(
+        self,
+        data,
+        current_path: str = "",
+        always_list: bool = False,
+        recursive: bool = True,
+    ):
+        return self._templater.fill(
+            templated_data=data,
+            source_data=self._data,
+            current_path=current_path,
+            always_list=always_list,
+            recursive=recursive,
+        )
+
+    def __call__(self):
+        return self._data
+
+    def __getitem__(self, item: str):
+        keys = item.split(".")
+        data = self._data
+        for key in keys:
+            if not isinstance(data, dict):
+                raise KeyError(f"Key '{key}' not found in '{data}'.")
+            if key not in data:
+                return
+            data = data[key]
+        # if isinstance(data, dict):
+        #     return NestedDict(data)
+        # if isinstance(data, list) and all(isinstance(item, dict) for item in data):
+        #     return [NestedDict(item) for item in data]
+        return data
+
+    def __setitem__(self, key, value):
+        key = key.split(".")
+        data = self._data
+        for k in key[:-1]:
+            if k not in data:
+                data[k] = {}
+            data = data[k]
+        data[key[-1]] = value
+        return
+
+    def __contains__(self, item):
+        keys = item.split(".")
+        data = self._data
+        for key in keys:
+            if not isinstance(data, dict) or key not in data:
+                return False
+            data = data[key]
+        return True
+
+    def __bool__(self):
+        return bool(self._data)
+
+    def setdefault(self, key, value):
+        key = key.split(".")
+        data = self._data
+        for k in key[:-1]:
+            if k not in data:
+                data[k] = {}
+            data = data[k]
+        return data.setdefault(key[-1], value)
+
+    def get(self, key, default=None):
+        keys = key.split(".")
+        data = self._data
+        for key in keys:
+            if not isinstance(data, dict) or key not in data:
+                return default
+            data = data[key]
+        return data
+
+    def items(self):
+        return self._data.items()
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def update(self, data: dict):
+        self._data.update(data)
+        return

pyserials/read.py

@@ -1,4 +1,4 @@
-from typing import Literal as _Literal
+from typing import Literal as _Literal, Callable as _Callable, Any as _Any
 import json as _json
 from pathlib import Path as _Path
 from functools import partial as _partial
@@ -17,11 +17,11 @@ def from_file(
     toml_as_dict: bool = False,
 ):
     if data_type is None:
-        data_type = _Path(path).suffix.removeprefix(".")
+        data_type = _Path(path).suffix.removeprefix(".").lower()
         if data_type == "yml":
             data_type = "yaml"
-        if data_type not in ("json", "yaml", "toml"):
-            raise _exception.read.PySerialsInvalidFileExtensionError(filepath=path)
+    if data_type not in ("json", "yaml", "toml"):
+        raise _exception.read.PySerialsInvalidFileExtensionError(filepath=path)
     if data_type == "json":
         return json_from_file(path=path, strict=json_strict)
     if data_type == "yaml":
@@ -97,32 +97,56 @@ def json_from_file(path: str | _Path, strict: bool = True) -> dict | list | str
 
 
 def yaml(
-    source: str | _Path, safe: bool = True
+    source: str | _Path,
+    safe: bool = True,
+    constructors: dict[str, _Callable[[_yaml.Constructor, _yaml.ScalarNode], _Any]] | None = None,
 ) -> dict | list | str | int | float | bool | _yaml.CommentedMap | _yaml.CommentedSeq:
+    """Load YAML data from a file or string.
+
+    Parameters
+    ----------
+    source : str | _Path
+        Path to the file or YAML data string.
+    safe : bool, default: True
+        Use safe YAML loader.
+    constructors : dict[str, Callable], default: None
+        Custom YAML constructors.
+
+    References
+    ----------
+    - See `add_constructor` method in
+      `ruamel.yaml.constructor.SafeConstructor` and `ruamel.yaml.constructor.RoundTripConstructor`.
+    - See `add_constructor` in [PyYAML documentation](https://pyyaml.org/wiki/PyYAMLDocumentation).
+    - See Tags in [YAML documentation](https://yaml.org/spec/1.2.0/#id2560445)
+    """
     if isinstance(source, str):
-        return yaml_from_string(data=source, safe=safe)
+        return yaml_from_string(data=source, safe=safe, constructors=constructors)
     return yaml_from_file(path=source, safe=safe)
 
 
 def yaml_from_string(
-    data: str, safe: bool = True
+    data: str,
+    safe: bool = True,
+    constructors: dict[str, _Callable[[_yaml.Constructor, _yaml.ScalarNode], _Any]] | None = None,
 ) -> dict | list | str | int | float | bool | _yaml.CommentedMap | _yaml.CommentedSeq:
     content = _read_from_string(
         data=data,
         data_type="yaml",
-        loader=_yaml.YAML(typ="safe" if safe else "rt").load,
+        loader=_make_yaml_loader(safe=safe, constructors=constructors).load,
         exception=_yaml.YAMLError
     )
     return content
 
 
 def yaml_from_file(
-    path: str | _Path, safe: bool = True
+    path: str | _Path,
+    safe: bool = True,
+    constructors: dict[str, _Callable[[_yaml.Constructor, _yaml.ScalarNode], _Any]] | None = None,
 ) -> dict | list | str | int | float | bool | _yaml.CommentedMap | _yaml.CommentedSeq:
     content = _read_from_file(
         path=path,
         data_type="yaml",
-        loader=_yaml.YAML(typ="safe" if safe else "rt").load,
+        loader=_make_yaml_loader(safe=safe, constructors=constructors).load,
         exception=_yaml.YAMLError
     )
     return content
@@ -136,16 +160,16 @@ def _read_from_file(
 ):
     path = _Path(path).resolve()
     if not path.is_file():
-        raise _exception.read.PySerialsMissingFileError(filepath=path)
+        raise _exception.read.PySerialsMissingFileError(data_type=data_type, filepath=path)
     data = path.read_text()
     if data.strip() == "":
-        raise _exception.read.PySerialsEmptyFileError(filepath=path)
+        raise _exception.read.PySerialsEmptyFileError(data_type=data_type, filepath=path)
     try:
         content = loader(data)
     except exception as e:
-        raise _exception.read.PySerialsInvalidDataFileError(
-            filepath=path, data_type=data_type, data=data
-        ) from e
+        raise _exception.read.PySerialsInvalidDataError(
+            source_type="file", filepath=path, data_type=data_type, data=data, cause=e
+        ) from None
     return content
 
 
@@ -160,5 +184,18 @@ def _read_from_string(
     try:
         content = loader(data)
     except exception as e:
-        raise _exception.read.PySerialsInvalidDataStringError(data_type=data_type, data=data) from e
+        raise _exception.read.PySerialsInvalidDataError(
+            source_type="string", data_type=data_type, data=data, cause=e
+        ) from None
     return content
+
+
+def _make_yaml_loader(
+    safe: bool,
+    constructors: dict[str, _Callable[[_yaml.Constructor, _yaml.ScalarNode], _Any]] | None = None
+) -> _yaml.YAML:
+    loader = _yaml.YAML(typ="safe" if safe else "rt")
+    if constructors:
+        for key, constructor in constructors.items():
+            loader.constructor.add_constructor(key, constructor)
+    return loader