sysmlpy 0.62.0__tar.gz → 0.63.0__tar.gz

{sysmlpy-0.62.0 → sysmlpy-0.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.62.0
+Version: 0.63.0
 Summary: 
 License-File: LICENSE
 Author: Jon R. Fox (mycr0ft)

{sysmlpy-0.62.0 → sysmlpy-0.63.0}/pyproject.toml

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

{sysmlpy-0.62.0 → sysmlpy-0.63.0}/src/sysmlpy/__init__.py

@@ -19,6 +19,7 @@ __all__ = [
     "as_traceability_matrix_view",
     "as_sequence_view", "as_case_view", "as_browser_view",
     "extract_traceability", "TraceabilityReport", "RequirementTrace",
+    "to_interchange", "from_interchange", "interchange_to_json_text",
     "analyze", "AnalysisResult", "SemanticIssue", "SemanticAnalyzer",
     "SysMLSyntaxError", "PartialParseError",
     "loads_partial", "load_partial",
@@ -27,7 +28,7 @@ __all__ = [
     "render_state_transition_view_svg", "boxes_view",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.62.0"
+__version__ = "0.63.0"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,
@@ -47,6 +48,9 @@ from sysmlpy.traceability import (
     extract_traceability, TraceabilityReport, RequirementTrace,
     as_traceability_matrix_view,
 )
+from sysmlpy.interchange import (
+    to_interchange, from_interchange, interchange_to_json_text,
+)
 
 
 class PartialParseError(Exception):

{sysmlpy-0.62.0 → sysmlpy-0.63.0}/src/sysmlpy/__main__.py

@@ -31,7 +31,7 @@ import sysmlpy
 from sysmlpy import loads
 
 # Subcommand table, also used to detect the legacy flat invocation form.
-SUBCOMMANDS = ("parse", "analyze", "view", "trace", "format", "fmt")
+SUBCOMMANDS = ("parse", "analyze", "view", "trace", "export", "import", "format", "fmt")
 
 
 # ---------------------------------------------------------------------------
@@ -317,6 +317,71 @@ def cmd_trace(args) -> int:
     return 0
 
 
+def cmd_export(args) -> int:
+    """SysML text → JSON interchange document (v0.63.0, Goal 3)."""
+    from sysmlpy.interchange import to_interchange, interchange_to_json_text
+
+    paths = [Path(f) for f in args.files]
+    for p in _missing_files(paths):
+        print(f"Error: File '{p}' not found.", file=sys.stderr)
+        return 2
+
+    try:
+        model = sysmlpy.load_files(paths, library=args.library)
+    except Exception as e:
+        print(f"Parse error: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        document = to_interchange(model)
+    except Exception as e:
+        print(f"Error: export failed on this model: {e}", file=sys.stderr)
+        return 1
+
+    output = interchange_to_json_text(document, indent=None if args.compact else 2)
+    if args.output:
+        Path(args.output).write_text(output + "\n", encoding="utf-8")
+        print(f"Wrote {args.output}")
+    else:
+        print(output)
+    return 0
+
+
+def cmd_import(args) -> int:
+    """JSON interchange document → SysML text (v0.63.0, Goal 3)."""
+    from sysmlpy.interchange import from_interchange
+
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Error: File '{path}' not found.", file=sys.stderr)
+        return 2
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        model = from_interchange(content)
+    except ValueError as e:
+        print(f"Error: invalid interchange document: {e}", file=sys.stderr)
+        return 2
+    except json.JSONDecodeError as e:
+        print(f"Error: not valid JSON: {e}", file=sys.stderr)
+        return 2
+
+    output = model.dump()
+    if args.output:
+        if not output.endswith("\n"):
+            output += "\n"
+        Path(args.output).write_text(output, encoding="utf-8")
+        print(f"Wrote {args.output}")
+    else:
+        print(output)
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # legacy flat invocation (kept for backward compatibility)
 # ---------------------------------------------------------------------------
@@ -541,6 +606,43 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_trace.set_defaults(func=cmd_trace)
 
+    p_export = sub.add_parser(
+        "export",
+        help="Export SysML to the JSON interchange format",
+        description="Load the files as one merged model and emit a "
+                    "JSON-LD-style partition interchange document "
+                    "(flat @graph of elements with @id/@type). Exit 2 "
+                    "on parse failure.",
+    )
+    p_export.add_argument("files", nargs="+", help="SysML v2 file(s)")
+    p_export.add_argument(
+        "-o", "--output",
+        help="Write the JSON document to a file instead of stdout",
+    )
+    p_export.add_argument(
+        "--compact", action="store_true",
+        help="Emit compact JSON (no indentation)",
+    )
+    p_export.add_argument(
+        "-l", "--library",
+        help="Path to SysML v2 library files to use for parsing",
+    )
+    p_export.set_defaults(func=cmd_export)
+
+    p_import = sub.add_parser(
+        "import",
+        help="Import a JSON interchange document as SysML text",
+        description="Rebuild a model from a JSON interchange document "
+                    "(sysmlpy export format) and print or write the "
+                    "equivalent SysML v2 text. Exit 2 on invalid input.",
+    )
+    p_import.add_argument("file", help="Interchange JSON file")
+    p_import.add_argument(
+        "-o", "--output",
+        help="Write the SysML text to a file instead of stdout",
+    )
+    p_import.set_defaults(func=cmd_import)
+
     return parser
 
 

{sysmlpy-0.62.0 → sysmlpy-0.63.0}/src/sysmlpy/definition.py

@@ -93,7 +93,15 @@ class Model(Searchable):
                 raise ValueError("Base Model must be encapsulated by a package.")
         
         definition = load_grammar_antlr(s, library=library)["ownedRelationship"]
+        return self._load_definition(definition)
 
+    def _load_definition(self: type[ModelType], definition) -> ModelType:
+        """Build the model from a parsed definition-dict member list.
+
+        Shared by :meth:`load` (fresh parse) and the JSON interchange
+        importer (v0.63.0 — ``from_interchange`` feeds the rebuilt dict
+        straight into this path).
+        """
         member_grammar = []
         found_package = False
         for member in definition:

sysmlpy-0.63.0/src/sysmlpy/interchange.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""SysML v2 JSON interchange for sysmlpy (v0.63.0 — Adoption Roadmap Goal 3).
+
+Exports a loaded model to a JSON-LD-style *partition interchange*
+document in the style of the SysML v2 spec's JSON exchange format, and
+imports such a document back into a live :class:`~sysmlpy.definition.Model`
+— losslessly, with deterministic element identifiers.
+
+Document shape::
+
+    {
+      "@context": {"@version": 1.1, "@vocab": "..."},
+      "@id": "id:root",
+      "@graph": [
+        {"@id": "id:pkg-1", "@type": "Package", "declaredName": "P",
+         "ownedRelationship": [{"@id": "id:rel-1"}]},
+        {"@id": "id:rel-1", "@type": "OwningMembership",
+         "ownedRelatedElement": {"@id": "id:part-1"}},
+        {"@id": "id:part-1", "@type": "PartDefinition", ...},
+        ...
+      ]
+    }
+
+Design notes:
+
+- **Flat graph.** Every element (packages, relationships, declarations,
+  bodies, ...) appears exactly once in ``@graph``; structural properties
+  reference other elements by ``{"@id": ...}``.  Scalars (``declaredName``,
+  ``declaredShortName``, keywords, ...) are kept inline.  ``null`` values
+  are preserved so the export/rebuild is shape-exact.
+- **``@type``** is the SysML v2 abstract-syntax metaclass name, exactly
+  as the parser's internal dictionary uses it (``Package``,
+  ``OwningMembership``, ``PartDefinition``, ...).
+- **Deterministic ``@id``s.**  Element identifiers are ``uuid5`` derived
+  from the element's position in the model tree, so exporting the same
+  model twice yields byte-identical JSON (diff-friendly, ties into
+  semantic model diff — roadmap Goal 8).
+- **Round-trip.**  ``from_interchange(to_interchange(model))`` rebuilds
+  the internal dictionary shape-exactly and constructs a live ``Model``
+  through the same grammar-class path as a fresh parse
+  (``Model._load_definition``).
+
+The ``@vocab`` IRI space is sysmlpy-owned; mapping every property to the
+normative OMG JSON-LD context is tracked as follow-up work.
+
+Public surface:
+
+- :func:`to_interchange` — ``Model`` or SysML text → interchange dict
+- :func:`from_interchange` — interchange dict / JSON text → ``Model``
+- :func:`interchange_to_json_text` / convenience formatting helpers
+"""
+
+from __future__ import annotations
+
+import json as _json
+import uuid as _uuid
+
+__all__ = [
+    "INTERCHANGE_CONTEXT",
+    "INTERCHANGE_NAMESPACE",
+    "to_interchange",
+    "from_interchange",
+    "interchange_to_json_text",
+]
+
+#: JSON-LD context emitted with every document.  Property names are the
+#: SysML v2 abstract-syntax property names used by the parser; the
+#: vocabulary IRI is sysmlpy-owned (normative OMG context mapping is
+#: tracked as follow-up work).
+INTERCHANGE_CONTEXT = {
+    "@version": 1.1,
+    "@vocab": "https://github.com/mycr0ft/sysmlpy/interchange#",
+}
+
+#: UUID namespace for deterministic element identifiers.
+INTERCHANGE_NAMESPACE = _uuid.uuid5(
+    _uuid.NAMESPACE_URL, "https://github.com/mycr0ft/sysmlpy/interchange"
+)
+
+_REF_KEYS = ("@id", "@type")
+
+
+# ---------------------------------------------------------------------------
+# export
+# ---------------------------------------------------------------------------
+
+
+def _child_id(parent_id: str, key: str, index: int) -> str:
+    """Deterministic identifier for the child at ``parent.key[index]``."""
+    return "sysml:" + str(
+        _uuid.uuid5(INTERCHANGE_NAMESPACE, f"{parent_id}|{key}|{index}")
+    )
+
+
+def _flatten(node: dict, parent_id: str, key: str, index: int,
+             graph: list) -> str:
+    """Recursively flatten a visitor-dict node into the graph.
+
+    Returns the ``@id`` assigned to this node.
+    """
+    elem_id = _child_id(parent_id, key, index)
+    elem = {"@id": elem_id, "@type": node.get("name")}
+    for k, v in node.items():
+        if k == "name":
+            continue  # captured as @type
+        elem[k] = _flatten_value(v, elem_id, k, graph)
+    graph.append(elem)
+    return elem_id
+
+
+def _flatten_value(v, elem_id: str, key: str, graph: list):
+    """Flatten one property value: dicts become @id refs, scalars inline."""
+    if v is None or isinstance(v, (str, int, float, bool)):
+        return v
+    if isinstance(v, dict):
+        return {"@id": _flatten(v, elem_id, key, 0, graph)}
+    if isinstance(v, list):
+        out = []
+        for i, item in enumerate(v):
+            if isinstance(item, dict):
+                out.append({"@id": _flatten(item, elem_id, key, i, graph)})
+            else:
+                out.append(item)
+        return out
+    # Unknown value type — keep it inline (best effort).
+    return v
+
+
+def to_interchange(source) -> dict:
+    """Export a model to the SysML v2 JSON interchange representation.
+
+    Parameters
+    ----------
+    source : Model or str
+        Either a loaded model (``sysmlpy.loads(...)`` / ``load_files(...)``
+        / programmatically built) or SysML v2 source text (parsed fresh).
+
+    Returns
+    -------
+    dict
+        JSON-LD-style document: ``@context``, root ``@id`` and a flat
+        ``@graph`` of elements.
+    """
+    from sysmlpy.definition import Model
+
+    if isinstance(source, Model):
+        # Export from the *raw parser dict*, not the grammar classes'
+        # ``get_definition()`` output: the class serialization normalizes
+        # the tree (adds ``ownedRelationship`` keys, unwraps
+        # ``OccurrenceUsageElement``), which changes how classes
+        # re-dispatch on import (e.g. satisfy wrappers were lost).
+        # ``dump()`` is the canonical serialization — re-parsing it gives
+        # the same dictionary shape a fresh parse produces.
+        try:
+            text = source.dump()
+        except ValueError:
+            text = ""  # empty model (dump raises "no elements to output")
+        if not text.strip():
+            root_dict = {
+                "name": "PackageBodyElement",
+                "ownedRelationship": [],
+            }
+        else:
+            from sysmlpy import load_grammar
+            root_dict = load_grammar(text)
+    elif isinstance(source, str):
+        from sysmlpy import load_grammar
+        root_dict = load_grammar(source)
+    else:
+        raise TypeError(
+            "to_interchange expects a Model or SysML text, "
+            f"not {source.__class__.__name__}"
+        )
+
+    graph: list = []
+    root_id = _flatten(root_dict, "root", "ownedRelationship", 0, graph)
+    return {
+        "@context": dict(INTERCHANGE_CONTEXT),
+        "@id": root_id,
+        "@graph": graph,
+    }
+
+
+def interchange_to_json_text(document: dict, *, indent: int = 2) -> str:
+    """Serialize an interchange document to a JSON string."""
+    return _json.dumps(document, indent=indent)
+
+
+# ---------------------------------------------------------------------------
+# import
+# ---------------------------------------------------------------------------
+
+
+def _is_ref(v) -> bool:
+    return isinstance(v, dict) and set(v.keys()) == {"@id"}
+
+
+def _rebuild(ref: dict, by_id: dict, stack: tuple = ()) -> dict:
+    """Rebuild the internal-dict node referenced by ``ref``."""
+    elem_id = ref["@id"]
+    if elem_id in stack:
+        raise ValueError(f"Cyclic element reference detected: {elem_id}")
+    elem = by_id.get(elem_id)
+    if elem is None:
+        raise ValueError(f"Interchange document references unknown @id: {elem_id}")
+    node = {"name": elem.get("@type")}
+    for k, v in elem.items():
+        if k in _REF_KEYS:
+            continue
+        node[k] = _rebuild_value(v, by_id, stack + (elem_id,))
+    return node
+
+
+def _rebuild_value(v, by_id: dict, stack: tuple):
+    if _is_ref(v):
+        return _rebuild(v, by_id, stack)
+    if isinstance(v, list):
+        return [
+            _rebuild(i, by_id, stack) if _is_ref(i) else i for i in v
+        ]
+    return v
+
+
+def from_interchange(data) -> "Model":
+    """Import a SysML v2 JSON interchange document into a live Model.
+
+    Parameters
+    ----------
+    data : dict or str
+        The interchange document (as produced by :func:`to_interchange`),
+        either as a dict or as a JSON string.
+
+    Returns
+    -------
+    Model
+    """
+    from sysmlpy.definition import Model
+
+    if isinstance(data, str):
+        data = _json.loads(data)
+    if not isinstance(data, dict):
+        raise ValueError(
+            "Interchange document must be a dict or JSON string, "
+            f"got {type(data).__name__}"
+        )
+    graph = data.get("@graph")
+    if not isinstance(graph, list):
+        raise ValueError("Interchange document has no @graph array")
+    by_id = {}
+    for elem in graph:
+        if not isinstance(elem, dict) or "@id" not in elem:
+            raise ValueError("Every @graph element needs an @id")
+        by_id[elem["@id"]] = elem
+
+    root_ref = data.get("@id")
+    if root_ref is None:
+        # Fall back to the first element that is not referenced by others.
+        referenced = {
+            v["@id"]
+            for elem in graph
+            for v in _walk_refs(elem)
+        }
+        roots = [e["@id"] for e in graph if e["@id"] not in referenced]
+        if not roots:
+            raise ValueError("Cannot determine root element of document")
+        root_ref = roots[0]
+
+    root = _rebuild({"@id": root_ref}, by_id)
+    relationships = root.get("ownedRelationship")
+    if relationships is None:
+        raise ValueError(
+            "Root element carries no ownedRelationship — not a model document"
+        )
+
+    model = Model()
+    return model._load_definition(relationships)
+
+
+def _walk_refs(elem: dict):
+    """Yield every ``{"@id": ...}`` ref reachable from *elem*'s properties."""
+    for v in elem.values():
+        yield from _walk_refs_value(v)
+
+
+def _walk_refs_value(v):
+    if _is_ref(v):
+        yield v
+    elif isinstance(v, list):
+        for item in v:
+            yield from _walk_refs_value(item)
+    elif isinstance(v, dict):
+        for item in v.values():
+            yield from _walk_refs_value(item)