PySerials 0.0.0.dev3__tar.gz → 0.0.0.dev4__tar.gz

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/PKG-INFO

@@ -1,8 +1,11 @@
 Metadata-Version: 2.1
 Name: PySerials
-Version: 0.0.0.dev3
+Version: 0.0.0.dev4
 Requires-Python: >=3.10
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: ruamel.yaml<0.18,>=0.17.32
 Requires-Dist: ruamel.yaml.string<1,>=0.1.1
 Requires-Dist: tomlkit<0.12,>=0.11.8
+Requires-Dist: markitup
+Requires-Dist: ansi-sgr
+Requires-Dist: ExceptionMan

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/pyproject.toml

@@ -17,12 +17,15 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.0.0.dev3"
+version = "0.0.0.dev4"
 name = "PySerials"
 dependencies = [
     "jsonschema >= 4.21.0, < 5",
     "ruamel.yaml >= 0.17.32, < 0.18", # https://yaml.readthedocs.io/en/stable/
     "ruamel.yaml.string >= 0.1.1, < 1",
     "tomlkit >= 0.11.8, < 0.12", # https://tomlkit.readthedocs.io/en/stable/,
+    "markitup",
+    "ansi-sgr",
+    "ExceptionMan"
 ]
 requires-python = ">=3.10"

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/src/PySerials.egg-info/PKG-INFO

@@ -1,8 +1,11 @@
 Metadata-Version: 2.1
 Name: PySerials
-Version: 0.0.0.dev3
+Version: 0.0.0.dev4
 Requires-Python: >=3.10
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: ruamel.yaml<0.18,>=0.17.32
 Requires-Dist: ruamel.yaml.string<1,>=0.1.1
 Requires-Dist: tomlkit<0.12,>=0.11.8
+Requires-Dist: markitup
+Requires-Dist: ansi-sgr
+Requires-Dist: ExceptionMan

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/src/PySerials.egg-info/SOURCES.txt

@@ -7,7 +7,9 @@ src/PySerials.egg-info/not-zip-safe
 src/PySerials.egg-info/requires.txt
 src/PySerials.egg-info/top_level.txt
 src/pyserials/__init__.py
+src/pyserials/compare.py
 src/pyserials/format.py
+src/pyserials/nested_dict.py
 src/pyserials/read.py
 src/pyserials/update.py
 src/pyserials/validate.py

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/src/PySerials.egg-info/requires.txt

@@ -2,3 +2,6 @@ jsonschema<5,>=4.21.0
 ruamel.yaml<0.18,>=0.17.32
 ruamel.yaml.string<1,>=0.1.1
 tomlkit<0.12,>=0.11.8
+markitup
+ansi-sgr
+ExceptionMan

{pyserials-0.0.0.dev3 → pyserials-0.0.0.dev4}/src/pyserials/__init__.py

@@ -1,3 +1,4 @@
 """PySerials"""
 
-from pyserials import exception, update, validate, read, write, format
+from pyserials import exception, update, validate, read, write, format, compare
+from pyserials.nested_dict import NestedDict

pyserials-0.0.0.dev4/src/pyserials/compare.py

@@ -0,0 +1,29 @@
+def items(source, target, path: str = "$"):
+    def recursive_compare(src, trg, curr_path):
+        if type(src) is not type(trg):
+            comp["modified"].append(curr_path)
+            return
+        if isinstance(src, dict):
+            for key in src:
+                if key not in trg:
+                    comp["added"].append(f"{curr_path}.{key}")
+                    continue
+                recursive_compare(src[key], trg[key], f"{curr_path}.{key}")
+            for key in trg:
+                if key not in src:
+                    comp["removed"].append(f"{curr_path}.{key}")
+            return
+        if isinstance(src, (list, tuple)):
+            len_src = len(src)
+            len_trg = len(trg)
+            min_len = min(len_src, len_trg)
+            for i in range(min_len):
+                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}]")
+            return
+        comp["unchanged" if src == trg else "modified"].append(curr_path)
+        return
+    comp = {"added": [], "removed": [], "modified": [], "unchanged": []}
+    recursive_compare(source, target, path)
+    return {key: sorted(comp[key]) for key in comp}

pyserials-0.0.0.dev4/src/pyserials/exception/_base.py

@@ -0,0 +1,58 @@
+"""PySerials base Exception class."""
+
+from __future__ import annotations
+from typing import Literal as _Literal
+import ansi_sgr as _sgr
+from markitup import html as _html, doc as _doc
+from exceptionman import ReporterException as _ReporterException
+
+
+_ANSI_HEADING_STYLE = {
+    1: _sgr.style(text_styles="bold", background_color="red"),
+    2: _sgr.style(text_styles="bold", background_color="yellow"),
+    3: _sgr.style(text_styles="bold", background_color="green"),
+    4: _sgr.style(text_styles="bold", background_color="blue"),
+    5: _sgr.style(text_styles="bold", background_color="magenta"),
+    6: _sgr.style(text_styles="bold", background_color="cyan"),
+}
+
+
+class PySerialsException(_ReporterException):
+    """Base class for all exceptions raised by PySerials."""
+
+    def __init__(
+        self,
+        message: str,
+        description: str | None = None,
+        message_html: str | _html.Element | None = None,
+        description_html: str | _html.Element | None = None,
+        report_heading: str = "PySerials Error Report",
+    ):
+        super().__init__(
+            message=message,
+            description=description,
+            message_html=message_html,
+            description_html=description_html,
+            report_heading=report_heading,
+        )
+        return
+
+
+def ansi_heading(section: list[int], title: str) -> str:
+    """Get an ANSI SGR formatted heading."""
+    sec = ".".join(str(n) for n in section)
+    sec_level = min(len(section), 6)
+    heading = f" {sec}. {title} "
+    return _sgr.format(heading, control_sequence=_ANSI_HEADING_STYLE[sec_level])
+
+
+def ansi_bold(text: str) -> str:
+    return _sgr.format(text, control_sequence=_sgr.style(text_styles="bold"))
+
+
+def format_code(code: str) -> tuple[str, str]:
+    console = _sgr.format(
+        code, control_sequence=_sgr.style(text_color=(220, 220, 220), background_color=(20, 20, 20))
+    )
+    html = str(_html.elem.code(code))
+    return console, html

pyserials-0.0.0.dev4/src/pyserials/exception/read.py

@@ -0,0 +1,211 @@
+"""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
+import json as _json
+
+from markitup import html as _html, md as _md
+from tomlkit.exceptions import TOMLKitError as _TOMLKitError
+
+from pyserials.exception._base import PySerialsException as _PySerialsException
+
+
+class PySerialsReadException(_PySerialsException):
+    """Base class for all exceptions raised by `pyserials.read` module.
+
+    Attributes
+    ----------
+    source_type : {"file", "string"}
+        Type of source from which data was read.
+    data_type : {"json", "yaml", "toml"} or None
+        Type of input data, if known.
+    filepath : pathlib.Path or None
+        Path to the input datafile, if data was read from a file.
+    """
+
+    def __init__(
+        self,
+        source_type: _Literal["file", "string"],
+        description: str,
+        description_html: str | _html.Element | None = None,
+        data_type: _Literal["json", "yaml", "toml"] | None = None,
+        filepath: _Path | None = None,
+    ):
+        if source_type == "string":
+            source = source_html = "string"
+        else:
+            source = f"file at '{filepath}'"
+            source_html = f"file at <code>{filepath}</code>"
+        data_ = f"{data_type.upper()} data" if data_type else "data"
+        message_template = f"Failed to read {data_} from input {{source}}."
+        super().__init__(
+            message=message_template.format(source=source),
+            message_html=message_template.format(source=source_html),
+            description=description,
+            description_html=description_html,
+            report_heading="PySerials Read Error Report",
+        )
+        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):
+    """Exception raised when a string to be read is empty."""
+
+    def __init__(self, data_type: _Literal["json", "yaml", "toml"]):
+        description = f"The string is empty."
+        super().__init__(description=description, source_type="string", data_type=data_type)
+        return
+
+
+class PySerialsInvalidFileExtensionError(PySerialsReadException):
+    """Exception raised when a file to be read has an unrecognized extension."""
+
+    def __init__(self, filepath: _Path):
+        description = (
+            f"The file extension must be one of 'json', 'yaml', 'yml', or '.toml', "
+            f"but got '{filepath.suffix.removeprefix('.')}'. "
+            "Please provide the extension explicitly, or rename the file to have a valid extension."
+        )
+        super().__init__(description=description, source_type="file", filepath=filepath)
+        return
+
+
+class PySerialsMissingFileError(PySerialsReadException):
+    """Exception raised when a file to be read does not exist."""
+
+    def __init__(self, data_type: _Literal["json", "yaml", "toml"], filepath: _Path):
+        description = f"The file does not exist."
+        super().__init__(description=description, source_type="file", data_type=data_type, filepath=filepath)
+        return
+
+
+class PySerialsEmptyFileError(PySerialsReadException):
+    """Exception raised when a file to be read is empty."""
+
+    def __init__(self, data_type: _Literal["json", "yaml", "toml"], filepath: _Path):
+        description = f"The file is empty."
+        super().__init__(description=description, source_type="file", data_type=data_type, filepath=filepath)
+        return
+
+
+class PySerialsInvalidDataError(PySerialsReadException):
+    """Exception raised when the data is invalid.
+
+    Attributes
+    ----------
+    data : str
+        The input data that was supposed to be read.
+    """
+
+    def __init__(
+        self,
+        source_type: _Literal["file", "string"],
+        data_type: _Literal["json", "yaml", "toml"],
+        data: str,
+        cause: Exception,
+        filepath: _Path | None = None,
+    ):
+        self.data = data
+        self.cause = cause
+        self.problem: str = str(cause)
+        self.problem_line: int | None = None
+        self.problem_column: int | None = None
+        self.problem_data_type: str | None = None
+        self.context: str | None = None
+        self.context_line: int | None = None
+        self.context_column: int | None = None
+        self.context_data_type: str | None = None
+
+        if isinstance(cause, _yaml.YAMLError):
+            self.problem_line = cause.problem_mark.line + 1
+            self.problem_column = cause.problem_mark.column + 1
+            self.problem_data_type = cause.problem_mark.name
+            self.problem = cause.problem.strip()
+            if cause.context:
+                self.context = cause.context.strip()
+                self.context_line = cause.context_mark.line + 1
+                self.context_column = cause.context_mark.column + 1
+                self.context_data_type = cause.context_mark.name
+        elif isinstance(cause, _json.JSONDecodeError):
+            self.problem = cause.msg
+            self.problem_line = cause.lineno
+            self.problem_column = cause.colno
+        elif isinstance(cause, _TOMLKitError):
+            self.problem_line = cause.line
+            self.problem_column = cause.col
+            self.problem = cause.args[0].removesuffix(f" at line {self.problem_line} col {self.problem_column}")
+        self.problem = self.problem.strip().capitalize().removesuffix(".")
+        description = "The data is not valid"
+        if self.problem_line:
+            description += f" at line {self.problem_line}, column {self.problem_column}"
+        description += f": {self.problem}."
+        super().__init__(description=description, source_type=source_type, data_type=data_type, filepath=filepath)
+        return
+
+    def _report_content(self, mode: _Literal["full", "short"], md: bool) -> _html.elem.Ul:
+
+        def make_tabel(problem, line, column, data_type):
+            rows = [
+                [title, value] for title, value in [
+                    ["Description", problem],
+                    ["Line Number", line],
+                    ["Column Number", column],
+                    ["Data Type", data_type],
+                ] if value is not None
+            ]
+            return _html.elem.table_from_rows(rows_body=rows)
+
+        content_list = [
+            _html.elem.details(
+                [
+                    _html.elem.summary("❌ Problem"),
+                    make_tabel(self.problem, self.problem_line, self.problem_column, self.problem_data_type)
+                ]
+            ),
+        ]
+        if self.context:
+            content_list.append(
+                _html.elem.details(
+                    [
+                        _html.elem.summary("🔍 Context"),
+                        make_tabel(self.context, self.context_line, self.context_column, self.context_data_type)
+                    ]
+                ),
+            )
+        data_lines = self.data.splitlines()
+        if self.problem_line:
+            line_idx = self.problem_line - 1
+            problem_line = data_lines[line_idx]
+            if md:
+                problem_line = f"- {problem_line}"
+            else:
+                if self.problem_column:
+                    col_idx = self.problem_column - 1
+                    prob_col = problem_line[col_idx]
+                    prob_col_highlight = _html.elem.span(prob_col, {"class": "highlight-char"})
+                    problem_line = f"{problem_line[:col_idx]}{prob_col_highlight}{problem_line[col_idx+1:]}"
+                problem_line = str(_html.elem.span(problem_line, {"class": "highlight-line"}))
+            data_lines[line_idx] = problem_line
+        if mode == "short":
+            if self.problem_line is not None:
+                problem_line_idx = self.problem_line - 1
+                start_line = max(0, problem_line_idx)
+                end_line = min(len(data_lines), problem_line_idx + 1)
+                if self.context_line is not None:
+                    context_line_idx = self.context_line - 1
+                    start_line = max(0, context_line_idx, problem_line_idx)
+                    end_line = min(len(data_lines), context_line_idx + 1, problem_line_idx + 1)
+                data_lines = data_lines[start_line:end_line]
+        data = "\n".join(data_lines)
+        if md:
+            code_block = _md.elem.code_fence(data, info="diff")
+        else:
+            code_block = _html.elem.pre(_html.elem.code(data, {"class": f"language-{self.data_type}"}))
+        content_list.append(_html.elem.details([_html.elem.summary("📄 Data"), code_block]))
+        return _html.elem.ul([_html.elem.li(content) for content in content_list])

pyserials-0.0.0.dev4/src/pyserials/exception/update.py

@@ -0,0 +1,139 @@
+"""Exceptions raised by `pyserials.update` module."""
+
+from __future__ import annotations
+from typing import Any as _Any, Literal as _Literal
+
+from markitup.html import elem as _html
+
+from pyserials.exception import _base
+
+
+class PySerialsUpdateException(_base.PySerialsException):
+    """Base class for all exceptions raised by `pyserials.update` module.
+
+    Attributes
+    ----------
+    path : str
+        JSONPath to where the update failed.
+    data : dict | list | str | int | float | bool
+        Data that failed to update.
+    data_full : dict | list | str | int | float | bool
+        Full data input.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        data: dict | list | str | int | float | bool,
+        data_full: dict | list | str | int | float | bool,
+        description: str,
+        description_html: str | _html.Element | None = None,
+    ):
+        message_template = "Failed to update data at {path}."
+        path_console, path_html = _base.format_code(path)
+        super().__init__(
+            message=message_template.format(path=path_console),
+            message_html=message_template.format(path=path_html),
+            description=description,
+            description_html=description_html,
+            report_heading="PySerials Update Error Report",
+        )
+        self.path = path
+        self.data = data
+        self.data_full = data_full
+        return
+
+
+class PySerialsUpdateDictFromAddonError(PySerialsUpdateException):
+    """Base class for all exceptions raised by `pyserials.update.dict_from_addon`.
+
+    Attributes
+    ----------
+    data_addon : Any
+        Value of the failed data in the addon dictionary.
+    data_addon_full : dictionary
+        Full addon input.
+    """
+
+    def __init__(
+        self,
+        problem_type: _Literal["duplicate", "type_mismatch"],
+        path: str,
+        data: _Any,
+        data_full: dict,
+        data_addon: _Any,
+        data_addon_full: dict,
+    ):
+        self.type_data = type(data)
+        self.type_data_addon = type(data_addon)
+        type_data_console, type_data_html = _base.format_code(self.type_data.__name__)
+        type_data_addon_console, type_data_addon_html = _base.format_code(self.type_data_addon.__name__)
+        path_console, path_html = _base.format_code(path)
+        kwargs_console, kwargs_html = (
+            {"path": path, "type_data": type_data, "type_data_addon": type_data_addon}
+            for path, type_data, type_data_addon in zip(
+                (path_console, path_html),
+                (type_data_console, type_data_html),
+                (type_data_addon_console, type_data_addon_html),
+            )
+        )
+        description_template = (
+            "There was a duplicate in the addon dictionary; "
+            "the value of type {type_data_addon} already exists in the source data."
+        ) if problem_type == "duplicate" else (
+            "There was a type mismatch between the source and addon dictionary values; "
+            "the value is of type {type_data} in the source data, "
+            "but of type {type_data_addon} in the addon data."
+        )
+        super().__init__(
+            description=description_template.format(**kwargs_console),
+            description_html=description_template.format(**kwargs_html),
+            path=path,
+            data=data,
+            data_full=data_full,
+        )
+        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):
+    """Exception raised when updating templated data fails.
+
+    Attributes
+    ----------
+    path_invalid : str
+        JSONPath that caused the update to fail.
+    data_source : dict
+        Source data that was used to update the template.
+    template_start : str
+        The start marker of the template.
+    template_end : str
+        The end marker of the template.
+    """
+
+    def __init__(
+        self,
+        description_template: str,
+        path_invalid: str,
+        path: str,
+        data: str,
+        data_full: dict | list | str | int | float | bool,
+        data_source: dict,
+        template_start: str,
+        template_end: str,
+    ):
+        path_invalid_console, path_invalid_html = _base.format_code(path_invalid.replace("'", ""))
+        super().__init__(
+            description=description_template.format(path_invalid=path_invalid_console),
+            description_html=description_template.format(path_invalid=path_invalid_html),
+            path=path.replace("'", ""),
+            data=data,
+            data_full=data_full,
+        )
+        self.path_invalid = path_invalid
+        self.data_source = data_source
+        self.template_start = template_start
+        self.template_end = template_end
+        return