sysmlpy 0.96.0__tar.gz → 0.96.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.96.0
+Version: 0.96.2
 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.2}/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.2}/pyproject.toml

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

{sysmlpy-0.96.0 → sysmlpy-0.96.2}/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.2"
 
 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.