sdcreader 4.3.1__tar.gz → 4.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.3.1
+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.1 → 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.1 → sdcreader-4.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcreader"
-version = "4.3.1"
+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.1 → sdcreader-4.4.0}/src/sdcreader/__init__.py

@@ -16,7 +16,7 @@ from .model import (CLOSE, DC_DEFAULTS, EXACT, HAS_UNIT, IDENTIFIER, LEAF_TYPES,
 from .package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
 from .record import CONTEXT_ELEMENTS, EXCEPTIONAL_VALUES, RECORD_ATTRIBUTES, VALUE_ELEMENTS, ExceptionalValue, Record, RecordError, RecordValue, read_record
 
-__version__ = "4.3.1"
+__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",

{sdcreader-4.3.1 → 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.1 → sdcreader-4.4.0}/src/sdcreader/record.py

@@ -71,12 +71,21 @@ class ExceptionalValue:
 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:
@@ -147,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
@@ -158,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
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.3.1
+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.1 → sdcreader-4.4.0}/tests/test_record.py

@@ -145,3 +145,26 @@ def test_recovery_is_recognized_for_every_value_element(model, sdc_type, value_e
     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)