omnist 0.2.0__py3-none-any.whl

omnist/__init__.py

@@ -0,0 +1,104 @@
+"""omnist — one canonical data model, many formats.
+
+A **Document** is a *tree*: an ordered list of labeled edges (repeated
+labels are how arrays appear), held by a :class:`Doc`.  A **Schema** describes
+the shape a Document may have, as ``record`` definitions referenced by name.
+A field's value side is always exactly one of the seven scalars (``string``,
+``integer``, ``number``, ``boolean``, ``date``, ``time``, ``datetime``),
+optionally nullable, or a reference to a named record — never a composed
+value-domain (no enums, no literal-valued fields). Read a format into a
+``Doc``, validate it against a ``Schema``, and write it back to any format.
+
+    from omnist import parse_schema, doc
+
+    s = parse_schema('''
+        record Member { "name": string, "role": string }
+        record Team   { "name": string, "members" [1,]: Member }
+        root Team
+    ''')
+    s.validate(doc({"name": "X", "members": [{"name": "Ann", "role": "dev"}]})).ok
+
+The model is defined formally in ``docs/design/model.md``.  The implementation
+lives in :mod:`omnist.canonical`; this module is its public surface.
+"""
+
+from .canonical.deserialize import materialize
+from .canonical.document import Doc, doc
+from .canonical.dsl import parse_schema, to_dsl
+from .canonical.formats import (
+    check_json,
+    check_toml,
+    check_xml,
+    check_yaml,
+    read_json,
+    read_toml,
+    read_xml,
+    read_yaml,
+    write_json,
+    write_toml,
+    write_xml,
+    write_yaml,
+)
+from .canonical.infer import infer
+from .canonical.oml import check_oml, read_oml, write_oml
+from .canonical.registry import Format, formats, get_format, register_format
+from .canonical.report import Adjustment, WriteReport, finish_write
+from .canonical.schema import (
+    BOOLEAN,
+    DATE,
+    DATETIME,
+    INTEGER,
+    NUMBER,
+    STRING,
+    TIME,
+    Error,
+    Field,
+    Record,
+    Ref,
+    Scalar,
+    Schema,
+    ValidationResult,
+    field,
+    nullable,
+    record,
+    ref,
+    schema,
+    t,
+)
+from .errors import (
+    DetachedNode,
+    DocumentError,
+    OmnistError,
+    ParseError,
+    SchemaError,
+    UnsafeXMLWarning,
+    WriteError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # errors
+    "OmnistError", "SchemaError", "ParseError", "WriteError", "DocumentError",
+    "DetachedNode", "UnsafeXMLWarning",
+    # document
+    "Doc", "doc",
+    # schema model
+    "Schema", "Record", "Scalar", "Ref", "Field", "ValidationResult", "Error",
+    # builders
+    "record", "ref", "field", "schema", "nullable", "t",
+    "STRING", "INTEGER", "NUMBER", "BOOLEAN", "DATE", "TIME", "DATETIME",
+    # dsl
+    "parse_schema", "to_dsl",
+    # operations (compatible_with / equivalent / normalize are Schema methods)
+    "infer", "materialize",
+    # codecs
+    "read_json", "write_json", "read_yaml", "write_yaml",
+    "read_toml", "write_toml", "read_xml", "write_xml",
+    "read_oml", "write_oml",
+    "check_json", "check_yaml", "check_toml", "check_xml", "check_oml",
+    # adjustment reports
+    "WriteReport", "Adjustment", "finish_write",
+    # format registry
+    "Format", "register_format", "get_format", "formats",
+]

omnist/canonical/__init__.py

@@ -0,0 +1,79 @@
+"""Canonical model (design proposal implementation).
+
+A self-contained implementation of the redesigned Document and Schema models
+described in ``docs/design/model.md``:
+
+* :mod:`~omnist.canonical.document` — the Document as an ordered list of
+  labeled edges, not a dict-with-arrays.
+* :mod:`~omnist.canonical.schema` — the Schema as ``Record`` (labels) /
+  ``Scalar`` (one of seven, never composed) / ``Ref``, with field
+  cardinality, plus conformance.
+* :mod:`~omnist.canonical.dsl` — the ``record`` text syntax.
+* :mod:`~omnist.canonical.operations` — ``compatible_with`` / ``equivalent``
+  / ``normalize`` on the new model.
+
+This package is the implementation of the model; ``import omnist`` is its
+public surface.
+"""
+
+from .deserialize import materialize
+from .document import Doc, doc
+from .dsl import parse_schema, to_dsl
+from .formats import (
+    check_json,
+    check_toml,
+    check_xml,
+    check_yaml,
+    read_json,
+    read_toml,
+    read_xml,
+    read_yaml,
+    write_json,
+    write_toml,
+    write_xml,
+    write_yaml,
+)
+from .infer import infer
+from .operations import compatible_with, equivalent, normalize
+from .registry import Format, formats, get_format, register_format
+
+# register the four built-in formats
+from .registry import _register_builtins as _rb  # noqa: E402
+from .report import Adjustment, WriteReport, finish_write
+from .schema import (
+    BOOLEAN,
+    DATE,
+    DATETIME,
+    INTEGER,
+    NUMBER,
+    STRING,
+    TIME,
+    Field,
+    Record,
+    Ref,
+    Scalar,
+    Schema,
+    ValidationResult,
+    field,
+    nullable,
+    record,
+    ref,
+    schema,
+    t,
+)
+
+_rb()
+
+__all__ = [
+    "Doc", "doc",
+    "Schema", "Record", "Scalar", "Ref", "Field", "ValidationResult",
+    "record", "ref", "field", "schema", "nullable", "t",
+    "STRING", "INTEGER", "NUMBER", "BOOLEAN", "DATE", "TIME", "DATETIME",
+    "parse_schema", "to_dsl",
+    "compatible_with", "equivalent", "normalize", "infer", "materialize",
+    "read_json", "read_yaml", "read_toml", "read_xml",
+    "write_json", "write_yaml", "write_toml", "write_xml",
+    "check_json", "check_yaml", "check_toml", "check_xml",
+    "WriteReport", "Adjustment", "finish_write",
+    "Format", "register_format", "get_format", "formats",
+]

omnist/canonical/deserialize.py

@@ -0,0 +1,117 @@
+"""Schema-directed deserialization: upgrade a freshly-read node's leaf values
+to match a :class:`~omnist.canonical.schema.Schema`'s declared scalars.
+
+Readers (``read_json``, etc.) hand back text-shaped values: JSON/YAML/TOML
+have no ``date``/``time`` type, so a temporal field arrives as an ISO-8601
+string; a whole-number ``float`` may need to become an ``int`` (or vice
+versa) to match what the schema declares. :func:`materialize` converts each
+leaf **only when the conversion is value-exact** -- ``"2024-01-01" -> date``,
+``1.0 -> int 1`` -- and raises :class:`~omnist.errors.ParseError` when it
+isn't -- ``1.5 -> integer``, ``"abc" -> integer``.
+
+This is unambiguous by construction: every field has exactly one candidate
+scalar (see ``docs/design/model.md``), so there's never a choice between
+candidate representations -- only "does this value exactly fit the one
+scalar declared, or not."
+
+Shape problems (a missing field, an unexpected field, the wrong cardinality)
+are left to :meth:`Schema.validate`, not raised here -- :func:`materialize`
+only ever touches values whose field type it can identify; anything it
+doesn't recognize is passed through unchanged for ``validate`` to flag.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any
+
+from ..errors import ParseError
+from .schema import Record, Scalar, Schema
+
+_TEMPORAL_CLASS = {"date": _dt.date, "time": _dt.time, "datetime": _dt.datetime}
+
+
+def materialize(node: Any, schema: Schema) -> Any:
+    """A copy of ``node`` with leaf values upgraded to match ``schema``."""
+    return _materialize_type(node, schema, schema.root, "$")
+
+
+def _materialize_type(node: Any, schema: Schema, t: Any, path: str) -> Any:
+    d = schema.resolve(t)
+    if isinstance(d, Scalar):
+        return _materialize_scalar(node, d, path)
+    return _materialize_record(node, schema, d, path)
+
+
+def _materialize_record(node: Any, schema: Schema, rec: Record, path: str) -> Any:
+    if not isinstance(node, list):
+        return node                       # a shape mismatch -- validate()'s job
+    out = []
+    counts: dict = {}
+    for label, child in node:
+        i = counts.get(label, 0)
+        counts[label] = i + 1
+        p = f"{path}.{label}" if i == 0 else f"{path}.{label}[{i}]"
+        f = rec.field(label)
+        if f is None:
+            out.append((label, child))    # an unexpected field -- validate()'s job
+        else:
+            out.append((label, _materialize_type(child, schema, f.type, p)))
+    return out
+
+
+def _materialize_scalar(value: Any, s: Scalar, path: str) -> Any:
+    if value is None or isinstance(value, list):
+        return value                      # null, or a shape mismatch -- validate()'s job
+    if s.name == "string":
+        if isinstance(value, str):
+            return value
+    elif s.name == "boolean":
+        if isinstance(value, bool):
+            return value
+    elif s.name == "integer":
+        if isinstance(value, bool):
+            pass
+        elif isinstance(value, int):
+            return value
+        elif isinstance(value, float) and value.is_integer():
+            return int(value)
+    elif s.name == "number":
+        if isinstance(value, bool):
+            pass
+        elif isinstance(value, (int, float)):
+            return float(value)
+    elif s.name in _TEMPORAL_CLASS:
+        converted = _materialize_temporal(value, s.name)
+        if converted is not _SENTINEL:
+            return converted
+    raise ParseError(f"{path}: {value!r} cannot be read as {s.name} "
+                     "(not a value-exact conversion)")
+
+
+_SENTINEL = object()
+
+
+def _materialize_temporal(value: Any, name: str) -> Any:
+    cls = _TEMPORAL_CLASS[name]
+    if isinstance(value, cls):
+        if name == "date" and isinstance(value, _dt.datetime):
+            return _SENTINEL               # datetime is a date subclass -- not this kind
+        return value
+    if not isinstance(value, str):
+        return _SENTINEL
+    try:
+        parsed = cls.fromisoformat(value)
+    except ValueError:
+        return _SENTINEL
+    if name == "datetime" and _is_iso(value, _dt.date):
+        return _SENTINEL                  # a bare date string is not a datetime
+    return parsed
+
+
+def _is_iso(value: str, cls) -> bool:
+    try:
+        cls.fromisoformat(value)
+        return True
+    except ValueError:
+        return False

omnist/canonical/document.py

@@ -0,0 +1,331 @@
+"""The Document model — a canonical tree of ordered, labeled edges.
+
+A Document model **node** is either
+
+* a **leaf** holding a scalar value (``str``/``int``/``float``/``bool``/
+  ``datetime`` values, or ``None``), or
+* an **internal node** holding an *ordered list of edges*, each a
+  ``(label, child)`` pair.  **Labels may repeat** — "many members" is the label
+  ``member`` appearing several times, not a field pointing to an array.
+
+The canonical Python form of a node is therefore::
+
+    scalar                                   # a leaf
+    [(label, node), (label, node), ...]      # an internal node (ordered)
+
+This single shape represents every supported format canonically, including
+XML's interleaved repeated elements, which a dict-with-array-values cannot.
+``Doc`` is a thin, guarded wrapper around a node, with navigation helpers.
+Order is preserved (it is data); schema validation ignores it.  See
+``docs/design/model.md``.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import TYPE_CHECKING, Any, Iterator, List, Optional, Tuple
+
+from ..errors import DocumentError
+
+if TYPE_CHECKING:
+    from .report import WriteReport
+    from .schema import Schema
+
+_MAX_DEPTH = 200
+
+Edge = Tuple[str, Any]   # (label, node)
+
+
+def _is_scalar(v: Any) -> bool:
+    # bool is an int subclass and datetime a date subclass — both are fine here.
+    return isinstance(v, (str, int, float, _dt.date, _dt.time, _dt.datetime)) or v is None
+
+
+# ---------------------------------------------------------------------------
+# Building a node from a plain Python value (JSON-shaped)
+# ---------------------------------------------------------------------------
+
+def build_node(value: Any, path: str = "$", depth: int = 0,
+               seen: Optional[frozenset] = None) -> Any:
+    """Turn a plain Python value into a canonical node.
+
+    A ``dict`` becomes an ordered edge list; a key whose value is a list expands
+    into one edge **per item** (the same label repeated).  A scalar becomes a
+    leaf.  A *bare* list (a top-level array, or a list nested directly inside a
+    list) has no labeled-edge form and raises ``DocumentError``.
+    """
+    if depth > _MAX_DEPTH:
+        raise DocumentError(f"{path}: nesting exceeds the maximum depth ({_MAX_DEPTH})")
+    if isinstance(value, dict):
+        seen = seen or frozenset()
+        if id(value) in seen:
+            raise DocumentError(f"{path}: cycle detected")
+        seen = seen | {id(value)}
+        edges: List[Edge] = []
+        for k, v in value.items():
+            if not isinstance(k, str):
+                raise DocumentError(f"{path}: object key {k!r} is not a string")
+            kp = _join(path, k)
+            for child in _children(v, kp, depth + 1, seen):
+                edges.append((k, child))
+        return edges
+    if isinstance(value, (list, tuple)):
+        raise DocumentError(f"{path}: a bare array has no labeled-edge form "
+                            "(arrays appear only as a repeated field)")
+    if _is_scalar(value):
+        return value
+    raise DocumentError(f"{path}: {type(value).__name__} is not a Document value")
+
+
+def _children(v: Any, path: str, depth: int, seen: frozenset) -> Iterator[Any]:
+    if isinstance(v, (list, tuple)):
+        for i, item in enumerate(v):
+            if isinstance(item, (list, tuple)):
+                raise DocumentError(
+                    f"{path}[{i}]: an array of arrays has no labeled-edge form")
+            yield build_node(item, f"{path}[{i}]", depth + 1, seen)
+    else:
+        yield build_node(v, path, depth, seen)
+
+
+def _join(path: str, key: str) -> str:
+    return f"{path}.{key}" if key.isidentifier() else f'{path}["{key}"]'
+
+
+# ---------------------------------------------------------------------------
+# Doc — guarded wrapper with navigation
+# ---------------------------------------------------------------------------
+
+class Doc:
+    """A guarded handle on a Document node (a leaf value or an edge list)."""
+
+    __slots__ = ("_node", "path")
+
+    def __init__(self, node: Any, path: str = "$") -> None:
+        self._node = node
+        self.path = path
+
+    # -- construction ---------------------------------------------------
+    @classmethod
+    def of(cls, value: Any) -> "Doc":
+        return cls(build_node(value))
+
+    @classmethod
+    def from_format(cls, name: str, text: str) -> "Doc":
+        from .registry import get_format
+        return cls(get_format(name).read(text))
+
+    @classmethod
+    def from_json(cls, text: str, *, schema: Optional["Schema"] = None) -> "Doc":
+        from .formats import read_json
+        return cls(read_json(text, schema=schema))
+
+    @classmethod
+    def from_yaml(cls, text: str, *, schema: Optional["Schema"] = None) -> "Doc":
+        from .formats import read_yaml
+        return cls(read_yaml(text, schema=schema))
+
+    @classmethod
+    def from_toml(cls, text: str, *, schema: Optional["Schema"] = None) -> "Doc":
+        from .formats import read_toml
+        return cls(read_toml(text, schema=schema))
+
+    @classmethod
+    def from_xml(cls, text: str, *, schema: Optional["Schema"] = None) -> "Doc":
+        from .formats import read_xml
+        return cls(read_xml(text, schema=schema))
+
+    @classmethod
+    def from_oml(cls, text: str, *, schema: Optional["Schema"] = None) -> "Doc":
+        from .oml import read_oml
+        return cls(read_oml(text, schema=schema))
+
+    # -- shape ----------------------------------------------------------
+    @property
+    def is_leaf(self) -> bool:
+        return not isinstance(self._node, list)
+
+    @property
+    def value(self) -> Any:
+        if isinstance(self._node, list):
+            raise DocumentError(f"{self.path}: not a leaf; use edges()")
+        return self._node
+
+    def edges(self) -> List[Tuple[str, "Doc"]]:
+        if not isinstance(self._node, list):
+            raise DocumentError(f"{self.path}: a leaf has no edges")
+        out, counts = [], {}
+        for label, child in self._node:
+            i = counts.get(label, 0)
+            counts[label] = i + 1
+            cp = f"{self.path}.{label}" if i == 0 else f"{self.path}.{label}[{i}]"
+            out.append((label, Doc(child, cp)))
+        return out
+
+    def labels(self) -> List[str]:
+        seen, out = set(), []
+        for label, _ in self._iter():
+            if label not in seen:
+                seen.add(label)
+                out.append(label)
+        return out
+
+    def get(self, label: str) -> List["Doc"]:
+        return [c for lbl, c in self.edges() if lbl == label]
+
+    def get_one(self, label: str) -> "Doc":
+        cs = self.get(label)
+        if len(cs) != 1:
+            raise DocumentError(
+                f"{self.path}: expected exactly one {label!r}, found {len(cs)}")
+        return cs[0]
+
+    def count(self, label: str) -> int:
+        return sum(1 for lbl, _ in self._iter() if lbl == label)
+
+    def _iter(self) -> Iterator[Tuple[str, Any]]:
+        if isinstance(self._node, list):
+            yield from self._node
+
+    def child(self, label: str) -> "Doc":
+        """A cursor to the single child under ``label`` (editable if internal)."""
+        return self.get_one(label)
+
+    # -- editing (mutates the underlying edge list) ---------------------
+    def add(self, label: str, value: Any) -> "Doc":
+        """Append an edge ``(label, value)``.  A repeated label is how an array
+        grows.  Returns ``self`` for chaining."""
+        self._require_internal("add")
+        self._node.append((label, build_node(value, f"{self.path}.{label}")))
+        return self
+
+    def remove(self, label: str) -> "Doc":
+        """Remove every edge under ``label``."""
+        self._require_internal("remove")
+        self._node[:] = [(lbl, c) for lbl, c in self._node if lbl != label]
+        return self
+
+    def set(self, label: str, value: Any) -> "Doc":
+        """Replace the (single) child under ``label``, or add it if absent."""
+        self._require_internal("set")
+        new = build_node(value, f"{self.path}.{label}")
+        for i, (lbl, _) in enumerate(self._node):
+            if lbl == label:
+                self._node[i] = (label, new)
+                return self
+        self._node.append((label, new))
+        return self
+
+    def _require_internal(self, op: str) -> None:
+        if not isinstance(self._node, list):
+            raise DocumentError(f"{self.path}: cannot {op} on a leaf")
+
+    # -- export ---------------------------------------------------------
+    def to_data(self) -> Any:
+        return _copy(self._node)
+
+    def to_grouped(self) -> Any:
+        """A JSON-shaped projection: same-label edges grouped into a list.
+
+        A label seen once stays a single value; a label seen more than once
+        becomes a list (the schema-less fallback of the count-1 rule, see
+        ``docs/design/model.md`` §10)."""
+        return _grouped(self._node)
+
+    def to_json(self, **o: Any) -> str:
+        from .formats import write_json
+        return write_json(self._node, **o)
+
+    def to_yaml(self, **o: Any) -> str:
+        from .formats import write_yaml
+        return write_yaml(self._node, **o)
+
+    def to_toml(self, **o: Any) -> str:
+        from .formats import write_toml
+        return write_toml(self._node, **o)
+
+    def to_xml(self, **o: Any) -> str:
+        from .formats import write_xml
+        return write_xml(self._node, **o)
+
+    def to_oml(self, **o: Any) -> str:
+        from .oml import write_oml
+        return write_oml(self._node, **o)
+
+    def to_format(self, name: str, **o: Any) -> str:
+        from .registry import get_format
+        return get_format(name).write(self._node, **o)
+
+    def check_json(self) -> "WriteReport":
+        from .formats import check_json
+        return check_json(self._node)
+
+    def check_yaml(self) -> "WriteReport":
+        from .formats import check_yaml
+        return check_yaml(self._node)
+
+    def check_toml(self) -> "WriteReport":
+        from .formats import check_toml
+        return check_toml(self._node)
+
+    def check_xml(self) -> "WriteReport":
+        from .formats import check_xml
+        return check_xml(self._node)
+
+    def check_oml(self) -> "WriteReport":
+        from .oml import check_oml
+        return check_oml(self._node)
+
+    def check_format(self, name: str) -> "WriteReport":
+        """Simulate writing to format ``name`` and return the adjustment
+        report, without producing output. Requires the registered
+        :class:`~omnist.canonical.registry.Format` to provide a ``check``
+        callable (the four built-ins do; a custom plugin may not)."""
+        from .registry import get_format
+        fmt = get_format(name)
+        if fmt.check is None:
+            raise DocumentError(
+                f"format {name!r} has no check() -- cannot simulate a write")
+        return fmt.check(self._node)
+
+    def validate(self, schema):
+        return schema.validate(self)
+
+    # -- dunders --------------------------------------------------------
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, Doc):
+            return self._node == other._node
+        try:
+            return self._node == build_node(other)
+        except DocumentError:
+            return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"Doc({'leaf' if self.is_leaf else 'node'}: {self._node!r})"
+
+
+def doc(value: Any) -> Doc:
+    """Build a :class:`Doc` from a plain Python value."""
+    return value if isinstance(value, Doc) else Doc.of(value)
+
+
+def _copy(node: Any) -> Any:
+    if isinstance(node, list):
+        return [(label, _copy(child)) for label, child in node]
+    return node
+
+
+def _grouped(node: Any) -> Any:
+    if not isinstance(node, list):
+        return node
+    counts: dict = {}
+    for label, _ in node:
+        counts[label] = counts.get(label, 0) + 1
+    out: dict = {}
+    for label, child in node:
+        g = _grouped(child)
+        if counts[label] > 1:
+            out.setdefault(label, []).append(g)
+        else:
+            out[label] = g
+    return out