sdcreader 4.3.0__tar.gz → 4.4.0__tar.gz

{sdcreader-4.3.0/src/sdcreader.egg-info → sdcreader-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.3.0
+Version: 4.4.0
 Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
@@ -97,8 +97,10 @@ that defines it. `source` is the record's bytes, its text or a path; a record of
 
 - **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
   `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
-- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
-  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), `instances` parallel to the path (which
+  occurrence each cluster is among the same cluster's repeats under the same parent; `instance_key` pairs them with the
+  clusters' identifiers, one key per cluster instance), an `occurrence` index for a component repeated within its
+  cluster instance, its `position`, its `elements` as the record holds them (a quantity's units nested:
   `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
   `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
 - **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in

{sdcreader-4.3.0 → sdcreader-4.4.0}/README.md

@@ -72,8 +72,10 @@ that defines it. `source` is the record's bytes, its text or a path; a record of
 
 - **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
   `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
-- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
-  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), `instances` parallel to the path (which
+  occurrence each cluster is among the same cluster's repeats under the same parent; `instance_key` pairs them with the
+  clusters' identifiers, one key per cluster instance), an `occurrence` index for a component repeated within its
+  cluster instance, its `position`, its `elements` as the record holds them (a quantity's units nested:
   `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
   `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
 - **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in

{sdcreader-4.3.0 → sdcreader-4.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcreader"
-version = "4.3.0"
+version = "4.4.0"
 description = "Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included."
 readme = "README.md"
 requires-python = ">=3.10"

{sdcreader-4.3.0 → sdcreader-4.4.0}/src/sdcreader/__init__.py

@@ -14,10 +14,10 @@ to the component that defines it, Exceptional Values included, for record-level
 from .model import (CLOSE, DC_DEFAULTS, EXACT, HAS_UNIT, IDENTIFIER, LEAF_TYPES, NUMERIC_TYPES, PUBLISHER, QUANTIFIED_TYPES, SEE_ALSO,
                     SOURCE, Code, Component, Leaf, Model, enumeration_iri, read_header, read_model)
 from .package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
-from .record import CONTEXT_ELEMENTS, EXCEPTIONAL_VALUES, RECORD_ATTRIBUTES, ExceptionalValue, Record, RecordError, RecordValue, read_record
+from .record import CONTEXT_ELEMENTS, EXCEPTIONAL_VALUES, RECORD_ATTRIBUTES, VALUE_ELEMENTS, ExceptionalValue, Record, RecordError, RecordValue, read_record
 
-__version__ = "4.3.0"
+__version__ = "4.4.0"
 __all__ = ["ModelPackage", "PackageError", "DEFAULT_HOST", "load_package", "fetch_package", "read_model", "read_header", "enumeration_iri",
            "Model", "Component", "Leaf", "Code", "LEAF_TYPES", "NUMERIC_TYPES", "QUANTIFIED_TYPES", "DC_DEFAULTS", "IDENTIFIER", "SOURCE",
            "PUBLISHER", "EXACT", "CLOSE", "SEE_ALSO", "HAS_UNIT", "read_record", "Record", "RecordValue", "RecordError", "ExceptionalValue",
-           "EXCEPTIONAL_VALUES", "RECORD_ATTRIBUTES", "CONTEXT_ELEMENTS", "__version__"]
+           "EXCEPTIONAL_VALUES", "RECORD_ATTRIBUTES", "CONTEXT_ELEMENTS", "VALUE_ELEMENTS", "__version__"]

{sdcreader-4.3.0 → sdcreader-4.4.0}/src/sdcreader/mcp_server.py

@@ -311,7 +311,8 @@ def _handle_read_record(args: dict[str, Any]) -> Any:
     values = [
         {
             "position": v.position, "ct_id": v.component.ct_id, "label": v.component.label, "sdc_type": v.component.sdc_type,
-            "path": [p.label for p in v.path], "occurrence": v.occurrence, "elements": v.elements, "context": v.context,
+            "path": [p.label for p in v.path], "instances": list(v.instances), "occurrence": v.occurrence,
+            "elements": v.elements, "context": v.context,
             "exceptional": ({"code": v.exceptional.code, "name": v.exceptional.name, "origin": v.exceptional.origin}
                             if v.exceptional else None),
         }

{sdcreader-4.3.0 → sdcreader-4.4.0}/src/sdcreader/record.py

@@ -39,6 +39,18 @@ RECORD_ATTRIBUTES = ("dm-label", "dm-language", "dm-encoding", "creation_timesta
 #: Per-value context elements: what the record says about a value rather than the value itself.
 CONTEXT_ELEMENTS = ("act", "vtb", "vte", "tr", "modified", "latitude", "longitude")
 
+#: The elements that hold a value, by the SDC4 reference model (sdc4.xsd), for every value type. A recovery Exceptional
+#: Value stands beside one of these; one written at the source stands in place of them. Units, language, magnitude
+#: status, accuracy, reference ranges and a link's relation describe a value and are not in this set.
+VALUE_ELEMENTS = frozenset({
+    "xdstring-value", "xdtoken-value", "true-value", "false-value",
+    "xdcount-value", "xdquantity-value", "xdfloat-value", "xddouble-value",
+    "xdtemporal-date", "xdtemporal-time", "xdtemporal-datetime", "xdtemporal-duration", "xdtemporal-year",
+    "xdtemporal-year-month", "xdtemporal-month", "xdtemporal-month-day", "xdtemporal-day",
+    "ordinal", "symbol", "link", "uri", "media-content", "lower", "upper",
+    "xdstringlist-value", "xdtokenlist-value", "xddecimallist-value", "xdintegerlist-value",
+})
+
 
 class RecordError(Exception):
     pass
@@ -48,19 +60,32 @@ class RecordError(Exception):
 class ExceptionalValue:
     code: str              # "ASKR"
     name: str              # "Asked and Refused"
-    origin: str            # "source": in place of the value; "recovery": beside a value that failed its constraint
+    origin: str            # "source": in place of the value; "recovery": beside a value that failed its constraint.
+                           # Inferred from the record's shape, so a best guess: a published model may require the
+                           # value element (SDCStudio's generated schemas do, though the reference model leaves it
+                           # optional), and then a source Exceptional Value sits beside a value too. Whoever inserted
+                           # Exceptional Values (a validator's recovery) knows the origin for certain.
 
 
 @dataclass
 class RecordValue:
     component: Component
     path: list[Component]          # the clusters above it, root first
-    occurrence: int                # 0 for the first time this component appears under this path, 1 for the next, ...
+    occurrence: int                # 0 for the first time this component appears in its cluster instance, 1 for the next
     position: int                  # document order among the record's values, 0-based
     elements: dict                 # the value elements as the record holds them: name -> text, or name -> dict for a
                                    # nested element (a quantity's units: {"label": "Trade Units", "xdstring-value": "EA"})
     context: dict[str, str]        # act, vtb, vte, tr, modified, latitude, longitude, where present
     exceptional: ExceptionalValue | None = None
+    instances: tuple[int, ...] = ()   # parallel to `path`: which occurrence each cluster is among the same cluster's
+                                      # repeats under the same parent instance (4.4.0). Two lines of one Line cluster
+                                      # in one Lines cluster are (..., 0) and (..., 1).
+
+    @property
+    def instance_key(self) -> tuple[tuple[str, int], ...]:
+        """The value's cluster instance, root first: (ct_id, occurrence) for every cluster above it. Values with equal
+        keys belong to the same cluster instance; a mapper writes one target element per key."""
+        return tuple(zip((c.ct_id for c in self.path), self.instances))
 
     @property
     def rejected(self) -> dict:
@@ -131,9 +156,11 @@ def read_record(source: bytes | str | Path, model: Model) -> Record:
             attributes[n] = _text(el)
 
     record = Record(model=model, attributes=attributes)
-    seen: dict[tuple, int] = {}
+    seen: dict[tuple, int] = {}       # leaf occurrences, per cluster instance
+    clusters: dict[tuple, int] = {}   # cluster occurrences, per parent cluster instance
 
-    def walk(el, path: list[Component]):
+    def walk(el, path: list[Component], instances: tuple[int, ...]):
+        parent = tuple(zip((c.ct_id for c in path), instances))
         for child in el:
             if not _is_sdc4(child):
                 continue
@@ -142,16 +169,21 @@ def read_record(source: bytes | str | Path, model: Model) -> Record:
                 continue
             comp = model.components.get(n[3:])
             if comp is None:                     # an adapter: pass through to the component inside
-                walk(child, path)
+                walk(child, path, instances)
             elif comp.sdc_type == "Cluster" or comp.sdc_type not in LEAF_TYPES:
-                walk(child, path + [comp])       # a cluster, or a structural component (audit, party, ...) holding values
+                key = (parent, comp.ct_id)       # a cluster, or a structural component (audit, party, ...) holding values
+                k = clusters.get(key, 0)
+                clusters[key] = k + 1
+                walk(child, path + [comp], instances + (k,))
             else:
-                key = (comp.ct_id, tuple(c.ct_id for c in path))
+                key = (comp.ct_id, parent)
                 occurrence = seen.get(key, 0)
                 seen[key] = occurrence + 1
-                record.values.append(_value(child, comp, path, occurrence, len(record.values)))
+                v = _value(child, comp, path, occurrence, len(record.values))
+                v.instances = instances
+                record.values.append(v)
 
-    walk(root, [])
+    walk(root, [], ())
     return record
 
 
@@ -173,7 +205,7 @@ def _value(el, comp: Component, path: list[Component], occurrence: int, position
             elements[n] = _nested(c)
     exceptional = None
     if ev_code:
-        value_present = any(k.endswith("-value") or k.startswith("xdtemporal-") for k in elements)
+        value_present = any(k in VALUE_ELEMENTS for k in elements)
         exceptional = ExceptionalValue(code=ev_code, name=EXCEPTIONAL_VALUES[ev_code],
                                        origin="recovery" if value_present else "source")
     return RecordValue(component=comp, path=path, occurrence=occurrence, position=position, elements=elements,

{sdcreader-4.3.0 → sdcreader-4.4.0/src/sdcreader.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.3.0
+Version: 4.4.0
 Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
@@ -97,8 +97,10 @@ that defines it. `source` is the record's bytes, its text or a path; a record of
 
 - **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
   `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
-- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
-  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), `instances` parallel to the path (which
+  occurrence each cluster is among the same cluster's repeats under the same parent; `instance_key` pairs them with the
+  clusters' identifiers, one key per cluster instance), an `occurrence` index for a component repeated within its
+  cluster instance, its `position`, its `elements` as the record holds them (a quantity's units nested:
   `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
   `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
 - **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in

{sdcreader-4.3.0 → sdcreader-4.4.0}/tests/test_record.py

@@ -128,3 +128,43 @@ def test_context_elements_are_kept_apart_from_the_value(model):
     r = read_record(etree.tostring(tree), model)
     v = next(v for v in r.values if v.context)
     assert v.context == {"vtb": "2026-01-01T00:00:00"} and "vtb" not in v.elements
+
+
+@pytest.mark.parametrize("sdc_type, value_el", [("XdOrdinal", "ordinal"), ("XdLink", "link"), ("XdFile", "uri"),
+                                                ("XdInterval", "lower"), ("XdBoolean", "true-value")])
+def test_recovery_is_recognized_for_every_value_element(model, sdc_type, value_el):
+    """4.3.1: a recovery Exceptional Value beside a value whose element does not end in -value (an ordinal, a link,
+    a file, an interval) was read as written at the source, and its rejected value was lost."""
+    from sdcreader.record import VALUE_ELEMENTS, _value
+    from sdcreader.model import Component
+    assert value_el in VALUE_ELEMENTS
+    el = etree.Element(f"{{{SDC4}}}ms-x")
+    etree.SubElement(el, "label").text = "L"
+    etree.SubElement(el, f"{{{SDC4}}}INV").append(etree.Element("ev-name"))
+    etree.SubElement(el, value_el).text = "bad"
+    comp = Component(ct_id="x", sdc_type=sdc_type, label="L", description="", data_type="", constraints={}, links={})
+    v = _value(el, comp, [], 0, 0)
+    assert v.exceptional.origin == "recovery" and v.rejected == {value_el: "bad"}
+
+
+def test_cluster_instances_number_repeats_under_the_same_parent(model):
+    """4.4.0: a cluster repeated under the same parent instance is numbered, and every value in it carries the number,
+    so a mapper can write one target element per instance."""
+    tree = etree.parse(str(RECORD))
+    _, comp = _first_string(tree)
+    cluster = comp.getparent().getparent()                   # the cluster holding the first value (through its adapter)
+    twin = etree.fromstring(etree.tostring(cluster))
+    cluster.addnext(twin)
+    r = read_record(etree.tostring(tree), model)
+    ct = comp.tag.split("ms-", 1)[1]
+    first, second = [v for v in r.values if v.component.ct_id == ct][:2]
+    assert first.path == second.path
+    assert first.instances[-1] == 0 and second.instances[-1] == 1
+    assert first.instance_key != second.instance_key
+    assert first.occurrence == second.occurrence == 0, "occurrence counts within a cluster instance"
+
+
+def test_every_value_has_an_instance_number_per_cluster_in_its_path(model):
+    r = read_record(RECORD, model)
+    assert all(len(v.instances) == len(v.path) for v in r.values)
+    assert all(v.instance_key[0] == (model.root.ct_id, 0) for v in r.values)