PySerials 0.1.3__tar.gz → 0.2.0__tar.gz

{pyserials-0.1.3 → pyserials-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySerials
-Version: 0.1.3
+Version: 0.2.0
 Requires-Python: >=3.12
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: referencing>=0.35.1

{pyserials-0.1.3 → pyserials-0.2.0}/pyproject.toml

@@ -17,7 +17,7 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.1.3"
+version = "0.2.0"
 name = "PySerials"
 dependencies = [
     "jsonschema >= 4.21.0, < 5",

{pyserials-0.1.3 → pyserials-0.2.0}/setup.py

@@ -57,8 +57,7 @@ import logging
 import os
 import sys
 
-from setuptools import setup, Extension
-
+from setuptools import Extension, setup
 
 SRC_DIR: str = "src/pyserials"
 

{pyserials-0.1.3 → pyserials-0.2.0}/src/PySerials.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySerials
-Version: 0.1.3
+Version: 0.2.0
 Requires-Python: >=3.12
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: referencing>=0.35.1

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/__init__.py

@@ -1,4 +1,4 @@
-"""PySerials: A Python package for reading, writing, validating, and transforming serialized data.
+"""PySerials: read, write, validate, and transform serialized data formats.
 
 PySerials provides utilities for working with JSON, YAML, and TOML data formats,
 including reading/writing files and strings, recursive dictionary updates,
@@ -32,7 +32,20 @@ PropertyDict
     A dictionary wrapper supporting attribute-style access.
 """
 
-from pyserials import exception, update, validate, read, write, format, compare
+__all__ = [
+    "NestedDict",
+    "PropertyDict",
+    "compare",
+    "exception",
+    "flatten",
+    "format",
+    "read",
+    "update",
+    "validate",
+    "write",
+]
+
+from pyserials import compare, exception, format, read, update, validate, write
+from pyserials.flatten import flatten
 from pyserials.nested_dict import NestedDict
 from pyserials.property_dict import PropertyDict
-from pyserials.flatten import flatten

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/compare.py

@@ -72,7 +72,7 @@ def items(
                 recursive_compare(src[i], trg[i], f"{curr_path}[{i}]")
             for i in range(min_len, max(len_src, len_trg)):
                 comp["added" if len_src > len_trg else "removed"].append(
-                    f"{curr_path}[{i}]"
+                    f"{curr_path}[{i}]",
                 )
             return
         comp["unchanged" if src == trg else "modified"].append(curr_path)

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/exception/__init__.py

@@ -4,5 +4,7 @@ All exceptions inherit from :class:`PySerialsException`, which itself
 extends ``exceptionman.ReporterException`` for rich error reporting.
 """
 
-from pyserials.exception._base import PySerialsException
+__all__ = ["PySerialsException", "read", "update", "validate"]
+
 from pyserials.exception import read, update, validate
+from pyserials.exception._base import PySerialsException

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/exception/_base.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING as _TYPE_CHECKING
 from functools import partial as _partial
+from typing import TYPE_CHECKING as _TYPE_CHECKING
 
-from exceptionman import ReporterException as _ReporterException  # type: ignore[import-untyped]
 import mdit as _mdit  # type: ignore[import-untyped]
+from exceptionman import (
+    ReporterException as _ReporterException,  # type: ignore[import-untyped]
+)
 
 if _TYPE_CHECKING:
     from mdit import Document
@@ -31,8 +33,7 @@ class PySerialsException(_ReporterException):  # type: ignore[misc]
             renderer=_partial(
                 _mdit.render.sphinx,
                 config=_mdit.render.get_sphinx_config(sphinx_config),
-            )
+            ),
         )
         report.target_configs["sphinx"] = sphinx_target_config
         super().__init__(report=report)
-        return

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/exception/read.py

@@ -1,14 +1,13 @@
 """Exceptions raised by `pyserials.read` module."""
 
 from __future__ import annotations
-from typing import Literal as _Literal
-from pathlib import Path as _Path
 
-import ruamel.yaml as _yaml
-from ruamel.yaml.error import MarkedYAMLError as _MarkedYAMLError
 import json as _json
-import mdit as _mdit  # type: ignore[import-untyped]
+from pathlib import Path as _Path
+from typing import Literal as _Literal
 
+import mdit as _mdit  # type: ignore[import-untyped]
+from ruamel.yaml.error import MarkedYAMLError as _MarkedYAMLError
 from tomlkit.exceptions import TOMLKitError as _TOMLKitError
 
 from pyserials.exception import _base
@@ -27,7 +26,7 @@ class PySerialsReadException(_base.PySerialsException):
         Path to the input datafile, if data was read from a file.
     """
 
-    __slots__ = ("source_type", "data_type", "filepath")
+    __slots__ = ("data_type", "filepath", "source_type")
 
     def __init__(
         self,
@@ -44,7 +43,9 @@ class PySerialsReadException(_base.PySerialsException):
             "string."
             if source_type == "string"
             else _mdit.inline_container(
-                "file at ", _mdit.element.code_span(filepath), "."
+                "file at ",
+                _mdit.element.code_span(filepath),
+                ".",
             ),
             separator=" ",
         )
@@ -60,7 +61,6 @@ class PySerialsReadException(_base.PySerialsException):
         self.source_type: _Literal["file", "string"] = source_type
         self.data_type: _Literal["json", "yaml", "toml"] | None = data_type
         self.filepath: _Path | None = filepath
-        return
 
 
 class PySerialsEmptyStringError(PySerialsReadException):
@@ -71,7 +71,6 @@ class PySerialsEmptyStringError(PySerialsReadException):
     def __init__(self, data_type: _Literal["json", "yaml", "toml"]) -> None:
         problem = "The string is empty."
         super().__init__(problem=problem, source_type="string", data_type=data_type)
-        return
 
 
 class PySerialsInvalidFileExtensionError(PySerialsReadException):
@@ -91,10 +90,10 @@ class PySerialsInvalidFileExtensionError(PySerialsReadException):
             _mdit.element.code_span(".toml"),
             ", but got ",
             _mdit.element.code_span(str(filepath.suffix.removeprefix("."))),
-            ". Please provide the extension explicitly, or rename the file to have a valid extension.",
+            ". Please provide the extension explicitly,"
+            " or rename the file to have a valid extension.",
         )
         super().__init__(problem=problem, source_type="file", filepath=filepath)
-        return
 
 
 class PySerialsMissingFileError(PySerialsReadException):
@@ -103,13 +102,17 @@ class PySerialsMissingFileError(PySerialsReadException):
     __slots__ = ()
 
     def __init__(
-        self, data_type: _Literal["json", "yaml", "toml"], filepath: _Path
+        self,
+        data_type: _Literal["json", "yaml", "toml"],
+        filepath: _Path,
     ) -> None:
         problem: str = "The file does not exist."
         super().__init__(
-            problem=problem, source_type="file", data_type=data_type, filepath=filepath
+            problem=problem,
+            source_type="file",
+            data_type=data_type,
+            filepath=filepath,
         )
-        return
 
 
 class PySerialsEmptyFileError(PySerialsReadException):
@@ -118,13 +121,17 @@ class PySerialsEmptyFileError(PySerialsReadException):
     __slots__ = ()
 
     def __init__(
-        self, data_type: _Literal["json", "yaml", "toml"], filepath: _Path
+        self,
+        data_type: _Literal["json", "yaml", "toml"],
+        filepath: _Path,
     ) -> None:
         problem: str = "The file is empty."
         super().__init__(
-            problem=problem, source_type="file", data_type=data_type, filepath=filepath
+            problem=problem,
+            source_type="file",
+            data_type=data_type,
+            filepath=filepath,
         )
-        return
 
 
 class PySerialsInvalidDataError(PySerialsReadException):
@@ -137,16 +144,16 @@ class PySerialsInvalidDataError(PySerialsReadException):
     """
 
     __slots__ = (
-        "data",
         "cause",
-        "problem",
-        "problem_line",
-        "problem_column",
-        "problem_data_type",
         "context",
-        "context_line",
         "context_column",
         "context_data_type",
+        "context_line",
+        "data",
+        "problem",
+        "problem_column",
+        "problem_data_type",
+        "problem_line",
     )
 
     def __init__(
@@ -173,7 +180,7 @@ class PySerialsInvalidDataError(PySerialsReadException):
             self.problem_line = cause.problem_mark.line + 1
             self.problem_column = cause.problem_mark.column + 1
             self.problem_data_type = cause.problem_mark.name.removeprefix(
-                "<"
+                "<",
             ).removesuffix(">")
             self.problem = cause.problem.strip()
             if cause.context:
@@ -182,7 +189,7 @@ class PySerialsInvalidDataError(PySerialsReadException):
                     self.context_line = cause.context_mark.line + 1
                     self.context_column = cause.context_mark.column + 1
                     self.context_data_type = cause.context_mark.name.removeprefix(
-                        "<"
+                        "<",
                     ).removesuffix(">")
         elif isinstance(cause, _json.JSONDecodeError):
             self.problem = cause.msg
@@ -192,7 +199,7 @@ class PySerialsInvalidDataError(PySerialsReadException):
             self.problem_line = getattr(cause, "line", None)
             self.problem_column = getattr(cause, "col", None)
             self.problem = cause.args[0].removesuffix(
-                f" at line {self.problem_line} col {self.problem_column}"
+                f" at line {self.problem_line} col {self.problem_column}",
             )
         self.problem = self.problem.strip().capitalize().removesuffix(".")
         description = ["The data is not valid"]
@@ -203,7 +210,7 @@ class PySerialsInvalidDataError(PySerialsReadException):
                     _mdit.element.code_span(str(self.problem_line)),
                     ", column ",
                     _mdit.element.code_span(str(self.problem_column)),
-                ]
+                ],
             )
         description.append(f": {self.problem}.")
         super().__init__(
@@ -213,7 +220,6 @@ class PySerialsInvalidDataError(PySerialsReadException):
             data_type=data_type,
             filepath=filepath,
         )
-        return
 
     def _report_content(self) -> dict[str, _mdit.element.Admonition]:
 
@@ -245,7 +251,7 @@ class PySerialsInvalidDataError(PySerialsReadException):
                     self.problem_data_type,
                 ),
                 type="error",
-            )
+            ),
         }
         if self.context:
             content["context_details"] = _mdit.element.admonition(

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/exception/update.py

@@ -1,7 +1,9 @@
 """Exceptions raised by `pyserials.update` module."""
 
 from __future__ import annotations
-from typing import Any as _Any, Literal as _Literal
+
+from typing import Any as _Any
+from typing import Literal as _Literal
 
 import mdit as _mdit  # type: ignore[import-untyped]
 
@@ -21,18 +23,21 @@ class PySerialsUpdateException(_base.PySerialsException):
         Full data input.
     """
 
-    __slots__ = ("path", "data", "data_full")
+    __slots__ = ("data", "data_full", "path")
 
     def __init__(
         self,
         path: str,
         data: object,
-        data_full: dict[str, _Any] | list[_Any] | str | int | float | bool,
+        *,
+        data_full: dict[str, _Any] | list[_Any] | str | float | bool,
         problem: object,
         section: dict[str, object] | None = None,
     ) -> None:
         intro = _mdit.inline_container(
-            "Failed to update data at ", _mdit.element.code_span(path), "."
+            "Failed to update data at ",
+            _mdit.element.code_span(path),
+            ".",
         )
         report = _mdit.document(
             heading="Data Update Error",
@@ -46,7 +51,6 @@ class PySerialsUpdateException(_base.PySerialsException):
         self.path = path
         self.data = data
         self.data_full = data_full
-        return
 
 
 class PySerialsUpdateRecursiveDataError(PySerialsUpdateException):
@@ -61,11 +65,11 @@ class PySerialsUpdateRecursiveDataError(PySerialsUpdateException):
     """
 
     __slots__ = (
-        "type_data",
-        "type_data_addon",
-        "problem_type",
         "data_addon",
         "data_addon_full",
+        "problem_type",
+        "type_data",
+        "type_data_addon",
     )
 
     def __init__(
@@ -88,7 +92,8 @@ class PySerialsUpdateRecursiveDataError(PySerialsUpdateException):
             )
             if problem_type == "duplicate"
             else _mdit.inline_container(
-                "There was a type mismatch between the source and addon dictionary values: ",
+                "There was a type mismatch between the source"
+                " and addon dictionary values: ",
                 "the value is of type ",
                 _mdit.element.code_span(self.type_data.__name__),
                 " in the source data, ",
@@ -106,7 +111,6 @@ class PySerialsUpdateRecursiveDataError(PySerialsUpdateException):
         self.problem_type: _Literal["duplicate", "type_mismatch"] = problem_type
         self.data_addon = data_addon
         self.data_addon_full = data_addon_full
-        return
 
 
 class PySerialsUpdateTemplatedDataError(PySerialsUpdateException):
@@ -124,7 +128,7 @@ class PySerialsUpdateTemplatedDataError(PySerialsUpdateException):
         The end marker of the template.
     """
 
-    __slots__ = ("path_invalid", "data_source", "template_start", "template_end")
+    __slots__ = ("data_source", "path_invalid", "template_end", "template_start")
 
     def __init__(
         self,
@@ -132,7 +136,8 @@ class PySerialsUpdateTemplatedDataError(PySerialsUpdateException):
         path_invalid: str | object,
         path: str | object,
         data: object,
-        data_full: dict[str, _Any] | list[_Any] | str | int | float | bool,
+        *,
+        data_full: dict[str, _Any] | list[_Any] | str | float | bool,
         data_source: dict[str, _Any] | list[_Any],
         template_start: str,
         template_end: str,
@@ -150,4 +155,3 @@ class PySerialsUpdateTemplatedDataError(PySerialsUpdateException):
             data_full=data_full,
             problem=_mdit.inline_container(*parts),
         )
-        return

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/exception/validate.py

@@ -1,6 +1,7 @@
 """Exceptions raised by `pyserials.validate` module."""
 
 from __future__ import annotations
+
 from typing import Any as _Any
 
 import jsonschema as _jsonschema  # type: ignore[import-untyped]
@@ -24,12 +25,13 @@ class PySerialsValidateException(_base.PySerialsException):
         The validator that was used to validate the data against the schema.
     """
 
-    __slots__ = ("data", "schema", "validator", "registry")
+    __slots__ = ("data", "registry", "schema", "validator")
 
     def __init__(
         self,
         problem: str | object,
-        data: dict[str, _Any] | list[_Any] | str | int | float | bool,
+        *,
+        data: dict[str, _Any] | list[_Any] | str | float | bool,
         schema: dict[str, _Any],
         validator: _Any,
         registry: _Any = None,
@@ -53,7 +55,6 @@ class PySerialsValidateException(_base.PySerialsException):
         self.schema = schema
         self.validator = validator
         self.registry = registry
-        return
 
 
 class PySerialsInvalidJsonSchemaError(PySerialsValidateException):
@@ -63,7 +64,8 @@ class PySerialsInvalidJsonSchemaError(PySerialsValidateException):
 
     def __init__(
         self,
-        data: dict[str, _Any] | list[_Any] | str | int | float | bool,
+        *,
+        data: dict[str, _Any] | list[_Any] | str | float | bool,
         schema: dict[str, _Any],
         validator: _Any,
         registry: _Any = None,
@@ -75,18 +77,18 @@ class PySerialsInvalidJsonSchemaError(PySerialsValidateException):
             validator=validator,
             registry=registry,
         )
-        return
 
 
 class PySerialsJsonSchemaValidationError(PySerialsValidateException):
-    """Exception raised when data validation fails due to the data being invalid against the schema."""
+    """Raised when the data does not satisfy its JSON Schema."""
 
     __slots__ = ("causes",)
 
     def __init__(
         self,
         causes: list[_jsonschema.exceptions.ValidationError],
-        data: dict[str, _Any] | list[_Any] | str | int | float | bool,
+        *,
+        data: dict[str, _Any] | list[_Any] | str | float | bool,
         schema: dict[str, _Any],
         validator: _Any,
         registry: _Any = None,
@@ -103,22 +105,49 @@ class PySerialsJsonSchemaValidationError(PySerialsValidateException):
             validator=validator,
             registry=registry,
         )
-        return
+
+    def __str__(self) -> str:
+        n = len(self.causes)
+        plural = "s" if n != 1 else ""
+        lines = [f"Schema validation failed: {n} error{plural} found."]
+        for i, error in enumerate(self.causes, 1):
+            lines.extend(self._format_error_text(error, indent=2, prefix=f"[{i}]"))
+        return "\n".join(lines)
 
     def _generate_problem_statement(self) -> _mdit.container.MDContainer:
-        error_paths = [
-            _mdit.element.code_span(error.json_path) for error in self.causes
-        ]
-        error_paths_str = self._join_list(error_paths)
-        count_errors = len(error_paths)
-        problem = _mdit.inline_container(
-            "Found ",
-            "an error " if count_errors == 1 else f"{count_errors} errors ",
-            "in the data at ",
-            error_paths_str,
-            ".",
+        n = len(self.causes)
+        plural = "s" if n != 1 else ""
+        header = _mdit.inline_container(f"Found {n} error{plural}:")
+        list_items = [self._make_error_item(error) for error in self.causes]
+        return _mdit.block_container(
+            header,
+            _mdit.element.unordered_list(list_items),
         )
-        return problem
+
+    @classmethod
+    def _context_depth(cls, error: _jsonschema.exceptions.ValidationError) -> int:
+        """Return the maximum depth of an error's context tree (0 for leaf errors)."""
+        if not error.context:
+            return 0
+        return 1 + max(cls._context_depth(sub) for sub in error.context)
+
+    @classmethod
+    def _make_error_item(
+        cls,
+        error: _jsonschema.exceptions.ValidationError,
+    ) -> _mdit.container.MDContainer:
+        """Recursively build an mdit item for one error, nesting context sub-errors."""
+        path = _mdit.element.code_span(error.json_path or "$")
+        msg = cls._parse_error_message(error)
+        item = _mdit.inline_container(path, " — ", msg)
+        if error.context:
+            sorted_context = sorted(error.context, key=cls._context_depth)
+            sub_items = [cls._make_error_item(sub) for sub in sorted_context]
+            item = _mdit.block_container(
+                item,
+                _mdit.element.unordered_list(sub_items),
+            )
+        return item
 
     def _generate_error_report(
         self,
@@ -157,7 +186,7 @@ class PySerialsJsonSchemaValidationError(PySerialsValidateException):
         if error.context:
             context_paths = []
             for idx, sub_error in enumerate(
-                sorted(error.context, key=lambda x: len(x.context))
+                sorted(error.context, key=self._context_depth),
             ):
                 section[str(idx)] = self._generate_error_report(sub_error)
                 context_paths.append(_mdit.element.code_span(sub_error.json_path))
@@ -177,7 +206,7 @@ class PySerialsJsonSchemaValidationError(PySerialsValidateException):
             full_ver_items[0].append(
                 f" This was caused by {err} at {context_paths_joined}.",
             )
-        doc = _mdit.document(
+        return _mdit.document(
             heading=_mdit.element.code_span(error.json_path),
             body={
                 "short": (
@@ -188,25 +217,45 @@ class PySerialsJsonSchemaValidationError(PySerialsValidateException):
             },
             section=section,
         )
-        return doc
 
     @staticmethod
     def _make_yaml_code_admo(
-        admo_type: str, title: str, title_details: str, content: dict[str, _Any]
+        admo_type: str,
+        title: str,
+        title_details: str,
+        content: dict[str, _Any],
     ) -> _mdit.element.Admonition:
         code_block = _mdit.element.code_block(
             content=_write.to_yaml_string(content, end_of_file_newline=False),
             language="yaml",
         )
-        admo = _mdit.element.admonition(
+        return _mdit.element.admonition(
             title=_mdit.inline_container(
-                f"**{title}**: ", _mdit.element.code_span(title_details)
+                f"**{title}**: ",
+                _mdit.element.code_span(title_details),
             ),
             body=code_block,
             type=admo_type,
             dropdown=True,
         )
-        return admo
+
+    @classmethod
+    def _format_error_text(
+        cls,
+        error: _jsonschema.exceptions.ValidationError,
+        indent: int = 0,
+        prefix: str = "",
+    ) -> list[str]:
+        """Recursively format a ValidationError as indented plain-text lines."""
+        pad = " " * indent
+        path = error.json_path or "$"
+        label = f"{prefix} " if prefix else ""
+        lines = [f"{pad}{label}{path}: {error.message}"]
+        for j, sub in enumerate(sorted(error.context, key=cls._context_depth)):
+            lines.extend(
+                cls._format_error_text(sub, indent=indent + 4, prefix=f"[{j}]"),
+            )
+        return lines
 
     @staticmethod
     def _parse_error_message(error: _jsonschema.exceptions.ValidationError) -> str:
@@ -231,7 +280,7 @@ class PySerialsJsonSchemaValidationError(PySerialsValidateException):
     ) -> Stringable:
         if len(items) == 1:
             return items[0]
-        elif len(items) == 2:
+        if len(items) == 2:
             return _mdit.inline_container(items[0], sep_pair, items[1])
         container: list[_Any] = []
         for item in items[:-1]:

{pyserials-0.1.3 → pyserials-0.2.0}/src/pyserials/flatten.py

@@ -87,12 +87,14 @@ def _flatten(
             return output
         if len(data) != 1:
             num_non_prim = sum(
-                1 for v in data if not isinstance(v, (str, int, float, bool, type(None)))
+                1
+                for v in data
+                if not isinstance(v, (str, int, float, bool, type(None)))
             )
             raise ValueError(
-                f"Data at '{path or 'root'}' contains a list with {len(data)} element(s) "
-                f"({num_non_prim} non-primitive); only a list containing exactly one "
-                f"non-primitive element is supported: {data}"
+                f"Data at '{path or 'root'}' contains a list with {len(data)}"
+                f" element(s) ({num_non_prim} non-primitive); only a list containing"
+                f" exactly one non-primitive element is supported: {data}",
             )
         return _flatten(data=data[0], output=output, path=path)
     raise ValueError(f"Unknown data type {type(data)} at {path}")