PySerials 0.1.1__tar.gz → 0.1.3__tar.gz

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: PySerials
-Version: 0.1.1
-Requires-Python: >=3.10
+Version: 0.1.3
+Requires-Python: >=3.12
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: referencing>=0.35.1
-Requires-Dist: jsonpath-ng<2,>=1.6.1
+Requires-Dist: jsonpath-ng<1.8.0,>=1.6.1
 Requires-Dist: ruamel.yaml>=0.18
 Requires-Dist: ruamel.yaml.string<1,>=0.1.1
 Requires-Dist: tomlkit<0.14,>=0.11.8

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

@@ -1,6 +1,6 @@
 
 [build-system]
-requires = ["setuptools>=61.0", "versioningit"]
+requires = ["setuptools>=61.0", "versioningit", "mypy>=1.0"]
 build-backend = "setuptools.build_meta"
 
 
@@ -17,12 +17,12 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.1.1"
+version = "0.1.3"
 name = "PySerials"
 dependencies = [
     "jsonschema >= 4.21.0, < 5",
     "referencing >= 0.35.1",
-    "jsonpath-ng >= 1.6.1, < 2",
+    "jsonpath-ng >= 1.6.1, < 1.8.0",
     "ruamel.yaml >= 0.18", # https://yaml.readthedocs.io/en/stable/
     "ruamel.yaml.string >= 0.1.1, < 1",
     "tomlkit >= 0.11.8, < 0.14", # https://tomlkit.readthedocs.io/en/stable/,
@@ -30,4 +30,4 @@ dependencies = [
     "ExceptionMan >=0.1,<0.2",
     "ProtocolMan >=0.1,<0.2",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.12"

pyserials-0.1.3/setup.py

@@ -0,0 +1,141 @@
+"""PySerials Setup Script
+
+Usage
+-----
+- Build with mypyc (default when available):
+```
+python -m build
+```
+
+- Development install with compiled extensions:
+```
+pip install -e .
+```
+
+- Force pure-Python build even when compilers are available:
+```
+DISABLE_MYPYC=1 pip install -e .
+```
+
+Notes
+-----
+Compiled extensions are built when **both** conditions are met:
+
+1. **DISABLE_MYPYC** — The environment variable is not set to a truthy
+   value (``1``, ``true``, or ``yes``, case-insensitive).
+   Defaults to unset (enabled).
+
+2. **SHOULD_COMPILE** — The setup command includes a compilation-triggering
+   argument: ``bdist_wheel``, ``editable_wheel``, ``build_ext``, ``build``,
+   ``install``, or ``develop``.
+   Commands like ``egg_info`` or ``sdist`` skip compilation entirely.
+
+If build dependencies are missing or compilation fails,
+the build raises an error and stops.
+
+mypyc modules
+~~~~~~~~~~~~~
+Only modules with measured speedup and no subclassing risk are compiled:
+
+- ``pyserials.compare``  — Recursive dict/list comparison (2.2x speedup).
+- ``pyserials.flatten``  — Nested-to-flat dict conversion (2.4x speedup).
+- ``pyserials.format``   — TOML/YAML object conversion (1.3–2.6x speedup).
+- ``pyserials.update``   — Template filler & recursive update (1.4–2.5x speedup).
+
+Modules intentionally kept as pure Python:
+
+- ``pyserials.read`` / ``pyserials.write`` — I/O-bound; ~98% time in
+  ruamel.yaml / tomlkit / json. Compilation yields only 1.1x.
+- ``pyserials.validate`` — Actually *slower* compiled (0.5–0.9x) due to
+  mypyc boxing overhead at the untyped jsonschema boundary.
+- ``pyserials.property_dict`` / ``pyserials.nested_dict`` — Compiled classes
+  cannot be subclassed from interpreted Python, which would be a breaking
+  change for downstream users.
+"""
+
+import logging
+import os
+import sys
+
+from setuptools import setup, Extension
+
+
+SRC_DIR: str = "src/pyserials"
+
+log = logging.getLogger("pyserials.setup")
+logging.basicConfig(level=logging.INFO, format="%(name)s: %(message)s")
+
+COMPILE_COMMANDS = {
+    "bdist_wheel",
+    "editable_wheel",
+    "build_ext",
+    "build",
+    "install",
+    "develop",
+}
+IS_COMPILE_COMMAND = bool(set(sys.argv) & COMPILE_COMMANDS)
+DISABLE_MYPYC = os.environ.get("DISABLE_MYPYC", "").lower() in ("1", "true", "yes")
+
+# Number of parallel compilation jobs (C compiler invocations).
+# Defaults to os.cpu_count(); override with BUILD_PARALLEL=N.
+PARALLEL = int(os.environ.get("BUILD_PARALLEL", os.cpu_count() or 1))
+
+# mypyc modules to compile (hot-path only; keep error handling in pure Python).
+MYPYC_MODULES = [
+    f"{SRC_DIR}/compare.py",
+    f"{SRC_DIR}/flatten.py",
+    f"{SRC_DIR}/format.py",
+    f"{SRC_DIR}/update.py",
+]
+
+
+def create_mypyc_extensions() -> list[Extension]:
+    """Create mypyc-compiled extensions for performance-critical modules."""
+    try:
+        from mypyc.build import mypycify
+    except ImportError as exc:
+        log.critical("mypyc dependency not found: %s", exc)
+        raise RuntimeError("mypyc dependency not found") from exc
+
+    try:
+        log.info("mypyc modules: %s", MYPYC_MODULES)
+        ext_modules = mypycify(
+            ["--ignore-missing-imports", *MYPYC_MODULES],
+            opt_level="3",
+            debug_level="0",
+            strip_asserts=True,
+            multi_file=False,
+            verbose=True,
+        )
+        log.info("Compiling %d mypyc extensions", len(ext_modules))
+        return ext_modules
+
+    except (Exception, SystemExit) as exc:
+        log.critical("mypyc compilation failed (%s): %s", type(exc).__name__, exc)
+        raise RuntimeError("mypyc compilation failed") from exc
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+log.info(
+    "Setup script invoked by %s command: %s",
+    "build" if IS_COMPILE_COMMAND else "metadata-only",
+    " ".join(sys.argv),
+)
+log.info(
+    "Setup configuration: DISABLE_MYPYC=%s, BUILD_PARALLEL=%d",
+    DISABLE_MYPYC,
+    PARALLEL,
+)
+
+ext_modules: list[Extension] = []
+
+if IS_COMPILE_COMMAND and not DISABLE_MYPYC:
+    ext_modules.extend(create_mypyc_extensions())
+
+setup(
+    ext_modules=ext_modules,
+    options={"build_ext": {"parallel": PARALLEL}},
+)

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: PySerials
-Version: 0.1.1
-Requires-Python: >=3.10
+Version: 0.1.3
+Requires-Python: >=3.12
 Requires-Dist: jsonschema<5,>=4.21.0
 Requires-Dist: referencing>=0.35.1
-Requires-Dist: jsonpath-ng<2,>=1.6.1
+Requires-Dist: jsonpath-ng<1.8.0,>=1.6.1
 Requires-Dist: ruamel.yaml>=0.18
 Requires-Dist: ruamel.yaml.string<1,>=0.1.1
 Requires-Dist: tomlkit<0.14,>=0.11.8

{pyserials-0.1.1 → pyserials-0.1.3}/src/PySerials.egg-info/SOURCES.txt

@@ -1,4 +1,5 @@
 pyproject.toml
+setup.py
 src/PySerials.egg-info/PKG-INFO
 src/PySerials.egg-info/SOURCES.txt
 src/PySerials.egg-info/dependency_links.txt
@@ -7,6 +8,7 @@ src/PySerials.egg-info/requires.txt
 src/PySerials.egg-info/top_level.txt
 src/pyserials/__init__.py
 src/pyserials/compare.py
+src/pyserials/flatten.py
 src/pyserials/format.py
 src/pyserials/nested_dict.py
 src/pyserials/property_dict.py

{pyserials-0.1.1 → pyserials-0.1.3}/src/PySerials.egg-info/requires.txt

@@ -1,6 +1,6 @@
 jsonschema<5,>=4.21.0
 referencing>=0.35.1
-jsonpath-ng<2,>=1.6.1
+jsonpath-ng<1.8.0,>=1.6.1
 ruamel.yaml>=0.18
 ruamel.yaml.string<1,>=0.1.1
 tomlkit<0.14,>=0.11.8

pyserials-0.1.3/src/pyserials/__init__.py

@@ -0,0 +1,38 @@
+"""PySerials: A Python package for reading, writing, validating, and transforming serialized data.
+
+PySerials provides utilities for working with JSON, YAML, and TOML data formats,
+including reading/writing files and strings, recursive dictionary updates,
+template filling, JSON Schema validation, data comparison, and flattening of
+nested structures.
+
+Modules
+-------
+read
+    Read serialized data from files and strings.
+write
+    Write data to serialized format strings and files.
+update
+    Recursively update data structures and fill templates.
+validate
+    Validate data against JSON schemas.
+compare
+    Compare two data structures and report differences.
+format
+    Convert data to specific TOML/YAML object types.
+flatten
+    Flatten nested dictionaries to single-level dictionaries.
+exception
+    Custom exception classes for error reporting.
+
+Classes
+-------
+NestedDict
+    A dictionary wrapper supporting dot-separated key access and template filling.
+PropertyDict
+    A dictionary wrapper supporting attribute-style access.
+"""
+
+from pyserials import exception, update, validate, read, write, format, compare
+from pyserials.nested_dict import NestedDict
+from pyserials.property_dict import PropertyDict
+from pyserials.flatten import flatten

pyserials-0.1.3/src/pyserials/compare.py

@@ -0,0 +1,88 @@
+"""Compare two data structures and report differences.
+
+This module provides functionality to recursively compare nested data structures
+(dicts, lists, tuples, and scalar values), producing categorized lists of
+JSONPath-like paths indicating which elements were added, removed, modified,
+or left unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def items(
+    source: Any,
+    target: Any,
+    path: str = "$",
+) -> dict[str, list[str]]:
+    """Recursively compare two data structures and categorize differences.
+
+    Walks both ``source`` and ``target`` in parallel, emitting JSONPath-style
+    strings for every leaf.  Paths are grouped into four categories:
+
+    * **added** – present in *source* but not in *target*.
+    * **removed** – present in *target* but not in *source*.
+    * **modified** – present in both but with different values or types.
+    * **unchanged** – present in both with the same value.
+
+    .. note::
+        Type comparison uses ``type(x) is type(y)`` (exact equality), not
+        ``isinstance``.  Any type mismatch — including subclass vs base class
+        (e.g. ``True`` vs ``1``, ``OrderedDict`` vs ``dict``) — causes the
+        entire node to be marked **modified** with no further traversal into
+        its children.  Two nodes are traversed recursively only when their
+        exact types match.
+
+    Parameters
+    ----------
+    source : Any
+        The *new* data structure (additions relative to *target*).
+    target : Any
+        The *old* / reference data structure.
+    path : str, default ``"$"``
+        Root JSONPath prefix for all emitted paths.
+
+    Returns
+    -------
+    dict[str, list[str]]
+        A mapping with keys ``"added"``, ``"removed"``, ``"modified"``,
+        and ``"unchanged"``, each containing a sorted list of JSONPath strings.
+    """
+
+    def recursive_compare(src: Any, trg: Any, curr_path: str) -> None:
+        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: int = len(src)
+            len_trg: int = len(trg)
+            min_len: int = 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: dict[str, list[str]] = {
+        "added": [],
+        "removed": [],
+        "modified": [],
+        "unchanged": [],
+    }
+    recursive_compare(source, target, path)
+    return {key: sorted(comp[key]) for key in comp}

pyserials-0.1.3/src/pyserials/exception/__init__.py

@@ -0,0 +1,8 @@
+"""Exceptions raised by PySerials.
+
+All exceptions inherit from :class:`PySerialsException`, which itself
+extends ``exceptionman.ReporterException`` for rich error reporting.
+"""
+
+from pyserials.exception._base import PySerialsException
+from pyserials.exception import read, update, validate

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

@@ -5,22 +5,32 @@ from __future__ import annotations
 from typing import TYPE_CHECKING as _TYPE_CHECKING
 from functools import partial as _partial
 
-from exceptionman import ReporterException as _ReporterException
-import mdit as _mdit
+from exceptionman import ReporterException as _ReporterException  # type: ignore[import-untyped]
+import mdit as _mdit  # type: ignore[import-untyped]
 
 if _TYPE_CHECKING:
     from mdit import Document
 
 
-class PySerialsException(_ReporterException):
-    """Base class for all exceptions raised by PySerials."""
+class PySerialsException(_ReporterException):  # type: ignore[misc]
+    """Base class for all exceptions raised by PySerials.
 
-    def __init__(self, report: Document):
-        sphinx_config = {"html_title": "PySerials Error Report"}
+    Wraps an ``mdit.Document`` error report and configures Sphinx rendering.
+
+    Parameters
+    ----------
+    report : mdit.Document
+        The structured error report document.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, report: Document) -> None:
+        sphinx_config: dict[str, str] = {"html_title": "PySerials Error Report"}
         sphinx_target_config = _mdit.target.sphinx(
             renderer=_partial(
                 _mdit.render.sphinx,
-                config=_mdit.render.get_sphinx_config(sphinx_config)
+                config=_mdit.render.get_sphinx_config(sphinx_config),
             )
         )
         report.target_configs["sphinx"] = sphinx_target_config