sysmlpy 0.96.0__tar.gz → 0.96.1__tar.gz

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.96.0
+Version: 0.96.1
 Summary: 
 License-File: LICENSE
 Author: Jon R. Fox (mycr0ft)
@@ -439,7 +439,79 @@ tree = classtree(model)
 print(tree.dump())
 ```
 
-**All 143 grammar round-trip tests pass** (100%). Covered categories: packages, parts, items, ports, interfaces, binding connectors, flow connections, all action forms (definition, shorthand, succession, decomposition), expressions, calculations, constraints, state definitions, requirements, analysis cases, control flow (if/else, while, loop, fork, join, decision, send, accept, terminate), trade studies, views, viewpoints, render states, portion usages, and annotations.
+**All 168 grammar round-trip tests pass** (100%). Covered categories: packages, parts, items, ports, interfaces, binding connectors, flow connections, all action forms (definition, shorthand, succession, decomposition), expressions, calculations, constraints, state definitions, requirements, analysis cases, control flow (if/else, while, loop, fork, join, decision, send, accept, terminate), trade studies, views, viewpoints, render states, portion usages, and annotations.
+
+### Doc comments, interface ends, and flows (v0.96.1)
+
+These constructs are easy to lose between the parser and the API — v0.96.1 makes them first-class and round-trip-safe:
+
+- **`doc /* ... */` comments** — on a package, on any part/item/port/action/... usage or definition, and inside interface bodies — are captured as a `.doc` attribute (a plain string) and re-emitted by `dump()`/`classtree()`, even when the comment shares its body with ports, attributes, or other members.
+- **Interface ends** — `end <name>;` and `end <name> ::> part.port;` members of an interface body — are captured as `Interface.ends` (name, type, multiplicity tuples) and `Interface.iface_connections` (`::>` target paths), and survive a dump round-trip.
+- **`flow <source> to <target>;`** — parses into a `Flow` child of the owning part, re-emits in the dump, and renders as a flow edge in the Interconnection View.
+
+```python
+from sysmlpy import loads, as_interconnection_view
+from sysmlpy.formatting import classtree
+
+text = """package WaterSystem {
+    doc /* package doc: the coffee water loop */
+
+    part def WaterTank {
+        doc /* stores the water */
+        port waterOut;
+    }
+
+    part def Brewer {
+        doc /* heats and brews */
+        port waterInlet;
+    }
+
+    interface def WaterSupply {
+        doc /* the supply contract */
+        end supplierPort;
+        end consumerPort;
+    }
+
+    part def CoffeeMachine {
+        doc /* makes coffee */
+        part waterTank : WaterTank;
+        part brewer : Brewer;
+
+        interface waterLine : WaterSupply {
+            doc /* internal plumbing */
+            end supplierPort ::> waterTank.waterOut;
+            end consumerPort ::> brewer.waterInlet;
+        }
+
+        flow waterTank.waterOut to brewer.waterInlet;
+    }
+}"""
+
+model = loads(text)
+package = model.children[0]
+
+# doc text on every element
+assert package.doc == "package doc: the coffee water loop"
+tank = package.find("WaterTank")[0]
+assert tank.doc == "stores the water"
+
+# interface ends: names and ::> targets
+machine = package.find("CoffeeMachine")[0]
+water_line = next(c for c in machine.children if type(c).__name__ == "Interface")
+assert [e[0] for e in water_line.ends] == ["supplierPort", "consumerPort"]
+assert water_line.iface_connections == [
+    ("supplierPort", "waterTank.waterOut"),
+    ("consumerPort", "brewer.waterInlet"),
+]
+
+# flows show up in the Interconnection View
+assert "flow" in as_interconnection_view(model)
+
+# and everything survives the dump round-trip (docs included)
+assert "stores the water" in classtree(model).dump()
+```
+
+See `examples/doc_ends_flows.py` for the full walk through the parse → grammar → API layers.
 
 ## Semantic Analysis
 

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/README.md

@@ -403,7 +403,79 @@ tree = classtree(model)
 print(tree.dump())
 ```
 
-**All 143 grammar round-trip tests pass** (100%). Covered categories: packages, parts, items, ports, interfaces, binding connectors, flow connections, all action forms (definition, shorthand, succession, decomposition), expressions, calculations, constraints, state definitions, requirements, analysis cases, control flow (if/else, while, loop, fork, join, decision, send, accept, terminate), trade studies, views, viewpoints, render states, portion usages, and annotations.
+**All 168 grammar round-trip tests pass** (100%). Covered categories: packages, parts, items, ports, interfaces, binding connectors, flow connections, all action forms (definition, shorthand, succession, decomposition), expressions, calculations, constraints, state definitions, requirements, analysis cases, control flow (if/else, while, loop, fork, join, decision, send, accept, terminate), trade studies, views, viewpoints, render states, portion usages, and annotations.
+
+### Doc comments, interface ends, and flows (v0.96.1)
+
+These constructs are easy to lose between the parser and the API — v0.96.1 makes them first-class and round-trip-safe:
+
+- **`doc /* ... */` comments** — on a package, on any part/item/port/action/... usage or definition, and inside interface bodies — are captured as a `.doc` attribute (a plain string) and re-emitted by `dump()`/`classtree()`, even when the comment shares its body with ports, attributes, or other members.
+- **Interface ends** — `end <name>;` and `end <name> ::> part.port;` members of an interface body — are captured as `Interface.ends` (name, type, multiplicity tuples) and `Interface.iface_connections` (`::>` target paths), and survive a dump round-trip.
+- **`flow <source> to <target>;`** — parses into a `Flow` child of the owning part, re-emits in the dump, and renders as a flow edge in the Interconnection View.
+
+```python
+from sysmlpy import loads, as_interconnection_view
+from sysmlpy.formatting import classtree
+
+text = """package WaterSystem {
+    doc /* package doc: the coffee water loop */
+
+    part def WaterTank {
+        doc /* stores the water */
+        port waterOut;
+    }
+
+    part def Brewer {
+        doc /* heats and brews */
+        port waterInlet;
+    }
+
+    interface def WaterSupply {
+        doc /* the supply contract */
+        end supplierPort;
+        end consumerPort;
+    }
+
+    part def CoffeeMachine {
+        doc /* makes coffee */
+        part waterTank : WaterTank;
+        part brewer : Brewer;
+
+        interface waterLine : WaterSupply {
+            doc /* internal plumbing */
+            end supplierPort ::> waterTank.waterOut;
+            end consumerPort ::> brewer.waterInlet;
+        }
+
+        flow waterTank.waterOut to brewer.waterInlet;
+    }
+}"""
+
+model = loads(text)
+package = model.children[0]
+
+# doc text on every element
+assert package.doc == "package doc: the coffee water loop"
+tank = package.find("WaterTank")[0]
+assert tank.doc == "stores the water"
+
+# interface ends: names and ::> targets
+machine = package.find("CoffeeMachine")[0]
+water_line = next(c for c in machine.children if type(c).__name__ == "Interface")
+assert [e[0] for e in water_line.ends] == ["supplierPort", "consumerPort"]
+assert water_line.iface_connections == [
+    ("supplierPort", "waterTank.waterOut"),
+    ("consumerPort", "brewer.waterInlet"),
+]
+
+# flows show up in the Interconnection View
+assert "flow" in as_interconnection_view(model)
+
+# and everything survives the dump round-trip (docs included)
+assert "stores the water" in classtree(model).dump()
+```
+
+See `examples/doc_ends_flows.py` for the full walk through the parse → grammar → API layers.
 
 ## Semantic Analysis
 

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "sysmlpy"
-version = "0.96.0"
+version = "0.96.1"
 description = ""
 authors = [{ name = "Jon R. Fox (mycr0ft)", email = "jon.fox@drfox.com" }]
 readme = "README.md"

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/src/sysmlpy/__init__.py

@@ -8,7 +8,7 @@ Uses the ANTLR4 parser for full SysML v2 grammar support.
 """
 
 __all__ = [
-    "load", "loads", "parse", "load_grammar", "load_antlr", "load_grammar_antlr",
+    "load", "loads", "load_wrapped", "loads_wrapped", "parse", "load_grammar", "load_antlr", "load_grammar_antlr",
     "load_files", "load_project", "load_with_dependencies",
     "Searchable",
     "Store", "InMemoryStore", "NetworkXStore", "KuzuStore", "CayleyStore", "create_store", "new_id",
@@ -35,7 +35,7 @@ __all__ = [
     "render_state_transition_view_svg", "boxes_view",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.96.0"
+__version__ = "0.96.1"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,
@@ -311,6 +311,93 @@ def loads(s: str, library=None, rescue_language="English") -> Model:
                         rescue_language=rescue_language)
 
 
+def _is_bare_top_level(s: str) -> bool:
+    """True when *s* starts with a top-level definition/usage keyword
+    rather than a (library) package — the same textual probe
+    :meth:`sysmlpy.definition.Model.load` uses for its strict guard."""
+    s_stripped = s.strip() if isinstance(s, str) else s
+    if not isinstance(s_stripped, str) or not s_stripped.split():
+        return False
+    invalid_starts = ['item', 'part', 'port', 'attribute', 'action', 'state',
+                      'connection', 'interface', 'requirement', 'case', 'use',
+                      'calc', 'constraint', 'concern', 'ref', 'flow', 'allocation',
+                      'view', 'viewpoint', 'rendering', 'metadata', 'individual']
+    return s_stripped.split(None, 1)[0] in invalid_starts
+
+
+def loads_wrapped(s: str, package_name="Snippets", library=None,
+                  rescue_language="English") -> Model:
+    """Load bare top-level SysML (no enclosing package) into a Model by
+    wrapping it in a synthetic package.
+
+    OMG example and training snippets frequently open directly with
+    ``part def Camera { ... }`` or ``action def DecisionTest { ... }``.
+    :func:`loads` / ``Model.load`` deliberately reject that form ("Base
+    Model must be encapsulated by a package"). This loader accepts it:
+    the source is wrapped as ``package <package_name> { ... }`` and then
+    parsed exactly like :func:`loads`. Content already carrying a
+    top-level package (or ``standard library package``) passes through
+    untouched, so the function is safe to call unconditionally on file
+    text.
+
+    Parameters
+    ----------
+    s : str
+        The SysML v2 source code to parse.
+    package_name : str, optional
+        Name of the synthetic package. Defaults to ``"Snippets"``.
+    library : str or Path, optional
+        Path to SysML v2 library files for resolving imports.
+
+    Returns
+    -------
+    Model
+        Model instance with one child: the synthetic package.
+
+    .. versionadded:: 0.96.1
+    """
+    if _is_bare_top_level(s):
+        s = "package %s {\n%s\n}\n" % (package_name, s.rstrip("\n"))
+    return loads(s, library=library, rescue_language=rescue_language)
+
+
+def load_wrapped(fp, package_name="Snippets", library=None) -> Model:
+    """File-pointer twin of :func:`loads_wrapped`.
+
+    Deserialize ``fp`` (a ``.read()``-supporting file-like object) —
+    wrapping bare top-level definitions in a synthetic package when
+    needed — to a Model object. Content with a top-level package passes
+    through untouched.
+
+    Parameters
+    ----------
+    fp : _io.TextIOWrapper
+        File pointer to a SysML v2.0 document.
+    package_name : str, optional
+        Name of the synthetic package. Defaults to ``"Snippets"``.
+    library : str or Path, optional
+        Path to SysML v2 library files for resolving imports.
+
+    Returns
+    -------
+    Model
+        Model instance structured utilizing SysML v2.0 grammar.
+
+    Raises
+    ------
+    TypeError
+        Input was not a ``.read()``-supporting file-like object.
+
+    .. versionadded:: 0.96.1
+    """
+    if not hasattr(fp, "read"):
+        raise TypeError(
+            f"the SysML object must be a file-like object, "
+            f"not {fp.__class__.__name__}"
+        )
+    return loads_wrapped(fp.read(), package_name=package_name, library=library)
+
+
 def parse(s: str, library=None):
     """Parse SysML source, returning (model, errors) rather than raising.
 

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/src/sysmlpy/antlr_visitor.py

@@ -10222,6 +10222,19 @@ def _visit_definition_body_item_dict(item_ctx, is_interface=False):
             inner_element = _visit_nested_non_occurrence_usage(non_occ)
             wrapper = "NonOccurrenceUsageMember"
     
+    # v0.96.1: a bare ``doc /* ... */`` member parses as
+    # DefinitionMemberContext (MemberPrefix + DefinitionElement ->
+    # AnnotatingElement -> Documentation) with NO
+    # definitionBodyItemContent — handle it directly (previously the
+    # doc member was dropped when it shared its body with siblings).
+    if not inner_element and hasattr(item_ctx, 'definitionMember') and item_ctx.definitionMember():
+        member_ctx = item_ctx.definitionMember()
+        element_ctx = member_ctx.definitionElement()
+        if element_ctx is not None:
+            ann_dict = _visit_nested_definition_element(element_ctx)
+            if ann_dict is not None and ann_dict.get("name") == "PackageMember":
+                inner_element = ann_dict.get("ownedRelatedElement", {})
+                wrapper = "DefinitionMember"
     # Check for definitionBodyItemContent
     if not inner_element and hasattr(item_ctx, 'definitionBodyItemContent') and item_ctx.definitionBodyItemContent():
         content = item_ctx.definitionBodyItemContent()

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/src/sysmlpy/definition.py

@@ -26,6 +26,7 @@ from sysmlpy.usage import (
     Allocation, Metadata, Rendering, Individual, FlowDef,
     View, Viewpoint, Concern, Reference,
 )
+from sysmlpy.usage import _comment_body_to_text as _comment_body_to_text_package
 
 ModelType = TypeVar("Model", bound="Model")
 
@@ -565,6 +566,8 @@ class Package(Searchable):
         self.typedby = None
         self.grammar = PackageGrammar()
         self.parent = None
+        # v0.96.1: doc text from a package-level ``doc /* ... */`` comment.
+        self.doc = None
 
         if name is not None:
             self._set_name(name)
@@ -708,6 +711,33 @@ class Package(Searchable):
             else:
                 child_defs.append(PackageMember(v).get_definition())
 
+        # v0.96.1: keep the package-level doc comment in the rebuilt
+        # body — captured as ``self.doc`` at load time (the doc member
+        # has no public-API child to re-serialize, so emit it directly).
+        if getattr(self, 'doc', None):
+            doc_dict = {
+                "name": "Documentation",
+                "body": "/* %s */" % self.doc,
+                "identification": None,
+                "ownedRelationship": [],
+            }
+            child_defs.append({
+                "name": "PackageMember",
+                "prefix": None,
+                "ownedRelatedElement": {
+                    "name": "DefinitionElement",
+                    "ownedRelatedElement": {
+                        "name": "AnnotatingElement",
+                        "ownedRelatedElement": {
+                            "name": "Documentation",
+                            "body": "/* %s */" % self.doc,
+                            "identification": None,
+                            "ownedRelationship": [],
+                        },
+                    },
+                },
+            })
+
         body_children = getattr(
             getattr(getattr(self, 'grammar', None), 'body', None), 'children', None
         )
@@ -1311,6 +1341,15 @@ class Package(Searchable):
                 mf = getattr(inner_element, 'children', None)
                 if mf is not None and mf.__class__.__name__ == "MetadataFeature":
                     self._add_metadata_child(mf)
+                elif mf is not None and mf.__class__.__name__ in (
+                        "Documentation", "CommentSysML"):
+                    # v0.96.1: package-level ``doc /* ... */`` — capture
+                    # the text as ``self.doc`` (previously silently
+                    # dropped).
+                    text = _comment_body_to_text_package(
+                        getattr(mf, 'body', ''))
+                    if text:
+                        self.doc = text
                 else:
                     print(f"[Package.load_from_grammar] Unknown class: {inner_class} - skipping")  # pragma: no cover
             elif inner_class == "NonOccurrenceUsageElement":

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/src/sysmlpy/dfa_cache.py

@@ -50,6 +50,7 @@ _state: Dict[str, Any] = {
     "directory": None,      # None = default (env/XDG/~/.cache/sysmlpy)
     "load_attempted": False,
     "loaded": False,
+    "file_states": 0,       # DFA states in the cache file at load time
     "save_attempted": False,
     "saved": False,
     "saved_states": 0,
@@ -290,9 +291,12 @@ def load_dfa_cache(path: Optional[str] = None) -> bool:
             payload = pickle.load(f)
         if not isinstance(payload, tuple) or len(payload) != 5:
             raise ValueError("unexpected cache payload shape")
+        file_states = sum(len(dfa.states) for dfa in payload[1])
+        file_states += sum(len(dfa.states) for dfa in payload[4])
         with _lock:
             _install(payload)
             _state["loaded"] = True
+            _state["file_states"] = file_states
         return True
     except Exception as exc:
         warnings.warn(
@@ -315,10 +319,18 @@ def save_dfa_cache(path: Optional[str] = None) -> bool:
         return False
     path = path or cache_file()
     try:
-        if os.path.isfile(path):
+        warm_states = sum(len(dfa.states) for dfa in _payload()[1])
+        warm_states += sum(len(dfa.states) for dfa in _payload()[4])
+        with _lock:
+            file_states = _state["file_states"]
+        if os.path.isfile(path) and warm_states <= file_states:
+            # Nothing learned beyond what the file already holds.
             with _lock:
                 _state["saved"] = False
             return False
+        # Fresh write, or a strictly warmer in-process cache: supersede
+        # the file so DFA states learned since its last write (e.g. new
+        # grammar paths like the short-name `<...>` forms) persist.
         P, L = _classes()
         payload = _payload()
         blob = pickle.dumps(payload, protocol=_CACHE_PROTOCOL)
@@ -355,6 +367,7 @@ def reset_for_tests() -> None:
         for key in ("load_attempted", "loaded", "save_attempted",
                     "saved", "saved_states"):
             _state[key] = False if key != "saved_states" else 0
+        _state["file_states"] = 0
 
 
 def stats() -> Dict[str, Any]:

{sysmlpy-0.96.0 → sysmlpy-0.96.1}/src/sysmlpy/grammar/classes.py

@@ -4067,7 +4067,14 @@ class InterfaceDefinition:
                 if isinstance(def_dict, dict) and def_dict.get("body") is not None:
                     body_dict = def_dict["body"]
                     if isinstance(body_dict, dict) and body_dict.get("name") in ("DefinitionBody", "InterfaceBody"):
-                        self.body = InterfaceBody({"name": "InterfaceBody", "item": body_dict.get("ownedRelatedElement", [])})
+                        # v0.96.1: a rebuilt DefinitionBody dict carries
+                        # its items in "ownedRelatedElement" (the
+                        # standard relationship name); a native
+                        # InterfaceBody dict carries them in "item".
+                        items = body_dict.get("item",
+                                              body_dict.get("ownedRelatedElement", []))
+                        self.body = InterfaceBody(
+                            {"name": "InterfaceBody", "item": items})
                     else:
                         self.body = InterfaceBody(body_dict)
             else:
@@ -5105,6 +5112,13 @@ class DefinitionBodyItem:
                         self.children.append(NonOccurrenceUsageMember(item))
                     elif item["name"] == "DefinitionMember":
                         self.children.append(DefinitionMember(item))
+                    elif item["name"] == "InterfaceOccurrenceUsageMember":
+                        # v0.96.1: interface ends inside a rebuilt
+                        # definition body (the ends have no public-API
+                        # child to re-serialize).
+                        self.children.append(
+                            InterfaceOccurrenceUsageMember(item)
+                        )
                     elif item["name"] == "Import":
                         # Imports are legal in usage bodies too
                         # (``part p1 { private import Q::*; }``) —
@@ -7551,7 +7565,18 @@ class InterfaceUsageDeclaration:
             if definition["part1"] is not None:
                 self.part = InterfacePart(definition["part1"])
                 # The connect usage was optional and it was used here.
-                self.keyword = "connect\n"
+                # v0.96.1: only when the binary part actually carries the
+                # CONNECT-form ends — the visitor also emits an EMPTY
+                # part1 for plain ``interface x : T { ... }`` (body-form
+                # ends), and marking those "connect" produced a
+                # reparse-breaking ``interface x: T connect ...`` dump.
+                binpart = getattr(self.part, 'children', None)
+                has_end_members = False
+                if binpart is not None and binpart.__class__.__name__ == "BinaryInterfacePart":
+                    has_end_members = bool(
+                        getattr(binpart, 'children', []) or [])
+                if has_end_members:
+                    self.keyword = "connect\n"
             elif definition["part2"] is not None:
                 self.part = InterfacePart(definition["part2"])