thundergraph-model 1.2.0__tar.gz → 1.2.2__tar.gz

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thundergraph-model
-Version: 1.2.0
+Version: 1.2.2
 Summary: Executable systems modeling in Python
 License-File: LICENSE
 Requires-Python: >=3.11

thundergraph_model-1.2.2/docs/release/v1.2.1.md

@@ -0,0 +1,55 @@
+# v1.2.1 Release Notes
+
+## Summary
+
+Patch release. No breaking changes. No new authoring API.
+
+---
+
+## Bug fix: `declared_name` and `declared_doc` now preserved in the compiled artifact
+
+**Problem**
+
+`model.name(str)` and `model.doc(str)` were stored exclusively in
+`ModelDefinitionContext._declared_name` / `._declared_doc` during `define()`.
+After `compile_type()` ran, the context was discarded and those values were lost.
+The compiled artifact (`cls._compiled_definition`) did not include them, so there
+was no way to retrieve the human-readable name or documentation text after
+compilation without re-running `define()`.
+
+**Fix**
+
+The compiled artifact now includes two new keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `declared_name` | `str` | The string passed to `model.name(...)`. Always present; validated as required by `_validate_name_and_doc_required`. |
+| `declared_doc` | `str \| None` | The string passed to `model.doc(...)`. Set on `Requirement` subclasses; `None` for `Part` and `System`. |
+
+**Reading the values**
+
+```python
+cd = MyPart.compile()
+name = cd["declared_name"]      # e.g. "hpc_colo_facility"
+doc  = cd["declared_doc"]       # None for Part/System
+
+cd = MyRequirement.compile()
+name = cd["declared_name"]      # e.g. "grid_import_capacity"
+doc  = cd["declared_doc"]       # e.g. "The aggregate facility electrical load shall..."
+```
+
+For `RequirementPackageInstance` objects produced by `instantiate()`, the declaring
+class is `obj.package_type`, not `obj.definition_type`:
+
+```python
+from tg_model.execution.instances import RequirementPackageInstance
+
+if isinstance(instance, RequirementPackageInstance):
+    name = instance.package_type._compiled_definition["declared_name"]
+    doc  = instance.package_type._compiled_definition["declared_doc"]
+```
+
+**Compatibility**
+
+Fully backward-compatible. Existing code that reads the artifact by key (e.g. `artifact["nodes"]`,
+`artifact["edges"]`) is unaffected. The two new keys are additive.

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thundergraph-model"
-version = "1.2.0"
+version = "1.2.2"
 description = "Executable systems modeling in Python"
 readme = "PYPI.md"
 requires-python = ">=3.11"

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/tests/unit/model/test_compile_types.py

@@ -169,3 +169,44 @@ class TestInvalidConnections:
         with pytest.raises(ModelDefinitionError, match="not a port"):
             BadSystem2.compile()
         BadSystem2._reset_compilation()
+
+
+class TestDeclaredNameAndDocInArtifact:
+    """declared_name and declared_doc are preserved in the compiled artifact (v1.2.1)."""
+
+    def test_part_declared_name_in_artifact(self) -> None:
+        result = Battery.compile()
+        assert result["declared_name"] == "battery"
+
+    def test_system_declared_name_in_artifact(self) -> None:
+        result = DriveSystem.compile()
+        assert result["declared_name"] == "drive_system"
+
+    def test_part_declared_doc_is_none(self) -> None:
+        # Parts and Systems have no doc requirement; field is present but None.
+        result = Battery.compile()
+        assert "declared_doc" in result
+        assert result["declared_doc"] is None
+
+    def test_requirement_declared_name_and_doc_in_artifact(self) -> None:
+        from tg_model.model.elements import Requirement
+
+        class LoadRequirement(Requirement):
+            @classmethod
+            def define(cls, model):  # type: ignore[override]
+                model.name("load_requirement")
+                model.doc("The system shall not exceed the declared load limit.")
+
+        result = LoadRequirement.compile()
+        assert result["declared_name"] == "load_requirement"
+        assert result["declared_doc"] == "The system shall not exceed the declared load limit."
+        LoadRequirement._reset_compilation()
+
+    def test_declared_name_present_after_reset_and_recompile(self) -> None:
+        Battery._reset_compilation()
+        result = Battery.compile()
+        assert result["declared_name"] == "battery"
+
+    def test_declared_name_accessible_via_class_attribute(self) -> None:
+        Battery.compile()
+        assert Battery._compiled_definition["declared_name"] == "battery"  # type: ignore[attr-defined]

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/tg_model/execution/configured_model.py

@@ -535,12 +535,29 @@ def _wire_requirement_block_references(
     path_registry: dict[str, ElementInstance | ValueSlot],
     out: list[ReferenceBinding],
 ) -> None:
-    """Bind ``references`` edges authored inside a :class:`~tg_model.model.elements.Requirement` package."""
+    """Bind ``references`` edges authored inside a :class:`~tg_model.model.elements.Requirement` package.
+
+    Source refs from ``parameter()`` / ``attribute()`` inside a Requirement carry
+    the block's ``symbol_path_prefix`` baked into ``ref.path`` (so they can flow
+    through ``allocate(inputs=...)``). Citation refs do not (they keep
+    ``self.owner_type`` so they're locally scoped). Strip ``_symbol_path_prefix``
+    from each edge endpoint so the result is a clean local-relative path before
+    prepending the runtime ``block_instance_path``.
+    """
+    symbol_prefix: tuple[str, ...] = tuple(compiled.get("_symbol_path_prefix") or ())
+
+    def _instance_path(raw_path: tuple[str, ...]) -> tuple[str, ...]:
+        if symbol_prefix and raw_path[: len(symbol_prefix)] == symbol_prefix:
+            local = raw_path[len(symbol_prefix):]
+        else:
+            local = raw_path
+        return block_instance_path + local
+
     for edge in compiled.get("edges", []):
         if edge.get("kind") != "references":
             continue
-        src_path = block_instance_path + tuple(edge["source"]["path"])
-        tgt_path = block_instance_path + tuple(edge["target"]["path"])
+        src_path = _instance_path(tuple(edge["source"]["path"]))
+        tgt_path = _instance_path(tuple(edge["target"]["path"]))
         src_key = ".".join(src_path)
         tgt_key = ".".join(tgt_path)
         src = path_registry.get(src_key)

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/tg_model/model/compile_types.py

@@ -151,6 +151,8 @@ def compile_type(
 
         artifact: dict[str, Any] = {
             "owner": qualified_name(element_cls),
+            "declared_name": ctx._declared_name,
+            "declared_doc": ctx._declared_doc,
             "nodes": {
                 name: {
                     "kind": decl.kind,
@@ -162,6 +164,11 @@ def compile_type(
             "edges": [_serialize_edge(edge) for edge in ctx.edges],
             "child_types": child_types,
             "_type_registry": type_registry,
+            # Threaded path prefix used by Requirement parameter()/attribute() refs.
+            # Runtime needs this to translate refs that carry the threaded path
+            # back to a local-relative path before prepending the instance path
+            # of a composed Requirement block.
+            "_symbol_path_prefix": tuple(ctx.symbol_path_prefix),
             "behavior_transitions": _serialize_behavior_transitions(ctx.behavior_transitions),
         }
         cls_mut._compiled_definition = artifact
@@ -515,7 +522,13 @@ def _validate_requirement_package_value_exprs(ctx: Any) -> None:
 
 
 def _validate_references_edges(ctx: Any) -> None:
-    """``references`` edges must resolve to declared nodes; target must be a citation."""
+    """``references`` edges must resolve to declared nodes; target must be a citation.
+
+    Source refs may also point at the root_block (``path=()``, ``kind='part'``,
+    ``owner_type is ctx.owner_type``), which represents a citation on the class
+    itself rather than on one of its declared members. We treat that as valid
+    without requiring a node lookup.
+    """
     for edge in ctx.edges:
         if edge.get("kind") != "references":
             continue
@@ -528,11 +541,20 @@ def _validate_references_edges(ctx: Any) -> None:
                 f"{ctx.owner_type.__name__}: references target must be a citation ref, "
                 f"got {getattr(tgt, 'kind', None)!r}"
             )
-        sdecl = _lookup_node_decl_for_ref(ctx, src)
-        if sdecl is None:
-            raise ModelDefinitionError(
-                f"{ctx.owner_type.__name__}: references source path {getattr(src, 'path', ())!r} does not resolve"
-            )
+        # Self-reference (root_block): empty path, kind=part, owner_type matches.
+        # No node decl exists for the class itself — accept without lookup.
+        if (
+            getattr(src, "path", None) == ()
+            and getattr(src, "kind", None) == "part"
+            and getattr(src, "owner_type", None) is ctx.owner_type
+        ):
+            pass
+        else:
+            sdecl = _lookup_node_decl_for_ref(ctx, src)
+            if sdecl is None:
+                raise ModelDefinitionError(
+                    f"{ctx.owner_type.__name__}: references source path {getattr(src, 'path', ())!r} does not resolve"
+                )
         tdecl = _lookup_node_decl_for_ref(ctx, tgt)
         if tdecl is None or tdecl.kind != "citation":
             raise ModelDefinitionError(
@@ -541,13 +563,26 @@ def _validate_references_edges(ctx: Any) -> None:
 
 
 def _lookup_node_decl_for_ref(ctx: Any, ref: Any) -> NodeDecl | None:
-    """Resolve a definition-time ref using the owning type's definition context (no recursive ``compile()``)."""
+    """Resolve a definition-time ref using the owning type's definition context (no recursive ``compile()``).
+
+    Refs from ``Requirement`` ``parameter()`` / ``attribute()`` calls are threaded
+    under ``ctx.symbol_owner`` (typically the configured root type) with a path
+    prefixed by ``ctx.symbol_path_prefix``. Strip that prefix before walking the
+    local context so refs and locally-declared nodes line up.
+    """
     path = getattr(ref, "path", ())
     if not path:
         return None
-    if getattr(ref, "owner_type", None) is not ctx.owner_type:
-        return None
-    return _walk_path_in_definition_ctx(ctx, path)
+    ref_owner = getattr(ref, "owner_type", None)
+    if ref_owner is ctx.owner_type:
+        return _walk_path_in_definition_ctx(ctx, path)
+    symbol_owner = getattr(ctx, "symbol_owner", None)
+    symbol_prefix = tuple(getattr(ctx, "symbol_path_prefix", ()) or ())
+    if ref_owner is symbol_owner and (not symbol_prefix or path[: len(symbol_prefix)] == symbol_prefix):
+        local_path = path[len(symbol_prefix):]
+        if local_path:
+            return _walk_path_in_definition_ctx(ctx, local_path)
+    return None
 
 
 def _walk_path_in_definition_ctx(ctx: Any, path: tuple[str, ...]) -> NodeDecl | None:

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/tg_model/model/definition_context.py

@@ -1295,7 +1295,12 @@ class ModelDefinitionContext:
         Parameters
         ----------
         source : Ref
-            Any declared node on this type (part, port, parameter, requirement, …).
+            Any declared node on this type (part, port, parameter, attribute,
+            requirement, …). For ``Requirement`` blocks, parameters and
+            attributes are threaded under ``symbol_owner`` so allocations can
+            wire them across boundaries; refs whose ``owner_type`` is either
+            the local ``owner_type`` or the configured ``symbol_owner`` are
+            both accepted as sources.
         citation : Ref
             Must be ``kind='citation'`` on this type.
 
@@ -1307,8 +1312,23 @@ class ModelDefinitionContext:
         self._check_frozen()
         if citation.kind != "citation":
             raise ModelDefinitionError(f"references(): citation must be a citation ref, got kind={citation.kind!r}")
-        if source.owner_type is not self.owner_type or citation.owner_type is not self.owner_type:
-            raise ModelDefinitionError("references(): source and citation must belong to this type")
+        # Accept refs from either the local owner_type or the threaded
+        # symbol_owner. For Parts, both are the same. For Requirements,
+        # parameter()/attribute() return refs with owner_type=symbol_owner so
+        # they can flow through allocations; those must be valid sources here.
+        valid_owners = (self.owner_type, self.symbol_owner)
+        if source.owner_type not in valid_owners or citation.owner_type not in valid_owners:
+            raise ModelDefinitionError(
+                f"references(): source and citation must belong to this type "
+                f"({self.owner_type.__name__})"
+                + (
+                    f" or its symbol owner ({self.symbol_owner.__name__})"
+                    if self.symbol_owner is not self.owner_type
+                    else ""
+                )
+                + f". Got source.owner_type={source.owner_type.__name__}, "
+                f"citation.owner_type={citation.owner_type.__name__}."
+            )
         self.edges.append(
             {
                 "kind": "references",

{thundergraph_model-1.2.0 → thundergraph_model-1.2.2}/uv.lock

@@ -1815,7 +1815,7 @@ wheels = [
 
 [[package]]
 name = "thundergraph-model"
-version = "1.2.0"
+version = "1.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "unitflow", extra = ["numpy"] },