sysmlpy 0.90.1__tar.gz → 0.91.0__tar.gz

sysmlpy-0.90.1/README.md → sysmlpy-0.91.0/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: sysmlpy
+Version: 0.91.0
+Summary: 
+License-File: LICENSE
+Author: Jon R. Fox (mycr0ft)
+Author-email: jon.fox@drfox.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: cayley
+Provides-Extra: graph
+Provides-Extra: jupyter
+Provides-Extra: kuzu
+Provides-Extra: sim
+Provides-Extra: xlsx
+Requires-Dist: antlr4-python3-runtime (>=4.13)
+Requires-Dist: arrow (>=1.4.0,<2.0.0)
+Requires-Dist: ipython (>=8.0) ; extra == "jupyter"
+Requires-Dist: kuzu (>=0.7,<0.12) ; extra == "kuzu"
+Requires-Dist: networkx (>=3.0) ; extra == "graph"
+Requires-Dist: openpyxl (>=3.1) ; extra == "xlsx"
+Requires-Dist: pint (>=0.24)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: requests (>=2.31) ; extra == "cayley"
+Requires-Dist: transitions (>=0.9,<0.10) ; extra == "sim"
+Description-Content-Type: text/markdown
+
 # sysmlpy
 [![PyPI version](https://badge.fury.io/py/sysmlpy.svg)](https://badge.fury.io/py/sysmlpy)[![PyPI status](https://img.shields.io/pypi/status/sysmlpy.svg)](https://pypi.python.org/pypi/sysmlpy/)[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
 
@@ -41,6 +74,7 @@ sysmlpy requires the following Python packages:
 - [kuzu](https://kuzudb.com/) — embedded graph database with disk persistence and Cypher queries (install with `pip install sysmlpy[kuzu]`)
 - [cayley](https://cayley.io/) — graph database via HTTP API, supports BoltDB/LevelDB backends (install with `pip install sysmlpy[cayley]`)
 - [PlantUML](https://plantuml.com/) **v1.2020.0+** — diagram rendering (requires Java + PlantUML JAR or [PlantUML server](https://www.plantuml.com/plantuml)). The generator uses `<style>` blocks and `skinparam` stereotype selectors introduced in v1.2020.
+- [IPython](https://ipython.org/) **v8.0+** — the `%%sysml` Jupyter cell magic (install with `pip install sysmlpy[jupyter]`; see [Jupyter integration](#jupyter-integration))
 
 ## Installation
 
@@ -53,6 +87,52 @@ Multiple installation methods are supported by sysmlpy, including:
 |       ![PyPI logo](https://simpleicons.org/icons/pypi.svg)        |     PyPI     |              ``python -m pip install sysmlpy[cayley]`` (with Cayley graph DB)              |
 |     ![GitHub logo](https://simpleicons.org/icons/github.svg)      |    GitHub    | ``python -m pip install https://github.com/mycr0ft/sysmlpy/archive/refs/heads/main.zip`` |
 
+## Jupyter integration
+
+With the `jupyter` extra installed (`pip install sysmlpy[jupyter]`), the
+`%%sysml` cell magic lets you write SysML v2 textual notation directly in
+notebook cells, parsed and accumulated into a persistent session `Model`
+exposed in the notebook namespace as `model` (alias `_sysml`):
+
+```python
+# once per notebook
+%load_ext sysmlpy.ipython_magic
+```
+
+```sysml
+%%sysml
+package Vehicle {
+    part def Engine {
+        attribute fuelRate : Real;
+    }
+    part def Vehicle {
+        part engine : Vehicle::Engine;
+    }
+}
+```
+
+Re-declaring a package merges at *package-member* granularity: elements
+with the same `name` and `sysml_type` replace prior definitions; sibling
+members are preserved. Line magics mirror the OMG Pilot Implementation
+Jupyter kernel's command set:
+
+| Magic | Purpose |
+|-------|---------|
+| `%sysml_reset` | Discard the session model |
+| `%sysml_list [NAME]` | List packages, or find elements by exact declared name |
+| `%sysml_show NAME [--json]` | `dump()` of the AST rooted at a named element |
+| `%sysml_viz NAME... [--view V]` | PlantUML view (general\|interconnection\|action\|package\|tree) |
+
+Cell options: `%%sysml --reset` (fresh model), `--file PATH` (parse from a
+file; use `-` as the cell body), `--show` (print the round-tripped model).
+Parse errors report to stderr with line/column and never discard the
+session model. The full magic-command reference — the complete set of the
+official [OMG Pilot Implementation Jupyter
+kernel](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/org.omg.sysml.jupyter.kernel)
+and the mapping to this implementation — is in the
+[sysml-copier](https://github.com/mycr0ft/sysml-copier) template's
+`docs/sysml-magics.md`.
+
 ## Command-Line Tools
 
 sysmlpy ships a CLI (`sysmlpy`, plus `sysmlpy-lsp` for editor support).
@@ -797,3 +877,4 @@ Two companion tools for the SysML v2 community, created by the same author:
 
 ## License
 sysmlpy is released under the MIT license, hence allowing commercial use of the library.
+

sysmlpy-0.90.1/PKG-INFO → sysmlpy-0.91.0/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: sysmlpy
-Version: 0.90.1
-Summary: 
-License-File: LICENSE
-Author: Jon R. Fox (mycr0ft)
-Author-email: jon.fox@drfox.com
-Requires-Python: >=3.9,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Provides-Extra: cayley
-Provides-Extra: graph
-Provides-Extra: kuzu
-Provides-Extra: sim
-Provides-Extra: xlsx
-Requires-Dist: antlr4-python3-runtime (>=4.13)
-Requires-Dist: arrow (>=1.4.0,<2.0.0)
-Requires-Dist: kuzu (>=0.7,<0.12) ; extra == "kuzu"
-Requires-Dist: networkx (>=3.0) ; extra == "graph"
-Requires-Dist: openpyxl (>=3.1) ; extra == "xlsx"
-Requires-Dist: pint (>=0.24)
-Requires-Dist: pyyaml (>=6.0)
-Requires-Dist: requests (>=2.31) ; extra == "cayley"
-Requires-Dist: transitions (>=0.9,<0.10) ; extra == "sim"
-Description-Content-Type: text/markdown
-
 # sysmlpy
 [![PyPI version](https://badge.fury.io/py/sysmlpy.svg)](https://badge.fury.io/py/sysmlpy)[![PyPI status](https://img.shields.io/pypi/status/sysmlpy.svg)](https://pypi.python.org/pypi/sysmlpy/)[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
 
@@ -72,6 +41,7 @@ sysmlpy requires the following Python packages:
 - [kuzu](https://kuzudb.com/) — embedded graph database with disk persistence and Cypher queries (install with `pip install sysmlpy[kuzu]`)
 - [cayley](https://cayley.io/) — graph database via HTTP API, supports BoltDB/LevelDB backends (install with `pip install sysmlpy[cayley]`)
 - [PlantUML](https://plantuml.com/) **v1.2020.0+** — diagram rendering (requires Java + PlantUML JAR or [PlantUML server](https://www.plantuml.com/plantuml)). The generator uses `<style>` blocks and `skinparam` stereotype selectors introduced in v1.2020.
+- [IPython](https://ipython.org/) **v8.0+** — the `%%sysml` Jupyter cell magic (install with `pip install sysmlpy[jupyter]`; see [Jupyter integration](#jupyter-integration))
 
 ## Installation
 
@@ -84,6 +54,52 @@ Multiple installation methods are supported by sysmlpy, including:
 |       ![PyPI logo](https://simpleicons.org/icons/pypi.svg)        |     PyPI     |              ``python -m pip install sysmlpy[cayley]`` (with Cayley graph DB)              |
 |     ![GitHub logo](https://simpleicons.org/icons/github.svg)      |    GitHub    | ``python -m pip install https://github.com/mycr0ft/sysmlpy/archive/refs/heads/main.zip`` |
 
+## Jupyter integration
+
+With the `jupyter` extra installed (`pip install sysmlpy[jupyter]`), the
+`%%sysml` cell magic lets you write SysML v2 textual notation directly in
+notebook cells, parsed and accumulated into a persistent session `Model`
+exposed in the notebook namespace as `model` (alias `_sysml`):
+
+```python
+# once per notebook
+%load_ext sysmlpy.ipython_magic
+```
+
+```sysml
+%%sysml
+package Vehicle {
+    part def Engine {
+        attribute fuelRate : Real;
+    }
+    part def Vehicle {
+        part engine : Vehicle::Engine;
+    }
+}
+```
+
+Re-declaring a package merges at *package-member* granularity: elements
+with the same `name` and `sysml_type` replace prior definitions; sibling
+members are preserved. Line magics mirror the OMG Pilot Implementation
+Jupyter kernel's command set:
+
+| Magic | Purpose |
+|-------|---------|
+| `%sysml_reset` | Discard the session model |
+| `%sysml_list [NAME]` | List packages, or find elements by exact declared name |
+| `%sysml_show NAME [--json]` | `dump()` of the AST rooted at a named element |
+| `%sysml_viz NAME... [--view V]` | PlantUML view (general\|interconnection\|action\|package\|tree) |
+
+Cell options: `%%sysml --reset` (fresh model), `--file PATH` (parse from a
+file; use `-` as the cell body), `--show` (print the round-tripped model).
+Parse errors report to stderr with line/column and never discard the
+session model. The full magic-command reference — the complete set of the
+official [OMG Pilot Implementation Jupyter
+kernel](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/org.omg.sysml.jupyter.kernel)
+and the mapping to this implementation — is in the
+[sysml-copier](https://github.com/mycr0ft/sysml-copier) template's
+`docs/sysml-magics.md`.
+
 ## Command-Line Tools
 
 sysmlpy ships a CLI (`sysmlpy`, plus `sysmlpy-lsp` for editor support).
@@ -828,4 +844,3 @@ Two companion tools for the SysML v2 community, created by the same author:
 
 ## License
 sysmlpy is released under the MIT license, hence allowing commercial use of the library.
-

{sysmlpy-0.90.1 → sysmlpy-0.91.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "sysmlpy"
-version = "0.90.1"
+version = "0.91.0"
 description = ""
 authors = [{ name = "Jon R. Fox (mycr0ft)", email = "jon.fox@drfox.com" }]
 readme = "README.md"
@@ -23,6 +23,7 @@ openpyxl = { version = ">=3.1", optional = true }
 arrow = "^1.4.0"
 transitions = {version = "^0.9", optional = true}
 requests = { version = ">=2.31", optional = true }
+ipython = { version = ">=8.0", optional = true }
 
 [tool.poetry.extras]
 graph = ["networkx"]
@@ -30,6 +31,7 @@ kuzu = ["kuzu"]
 xlsx = ["openpyxl"]
 sim = ["transitions"]
 cayley = ["requests"]
+jupyter = ["ipython"]
 
 [tool.poetry.scripts]
 sysmlpy = "sysmlpy.__main__:main"

{sysmlpy-0.90.1 → sysmlpy-0.91.0}/src/sysmlpy/__init__.py

@@ -34,7 +34,7 @@ __all__ = [
     "render_state_transition_view_svg", "boxes_view",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.90.1"
+__version__ = "0.91.0"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,

sysmlpy-0.91.0/src/sysmlpy/ipython_magic.py

@@ -0,0 +1,251 @@
+"""%%sysml cell magic: parse and accumulate SysML v2 models in IPython/Jupyter.
+
+Load once per notebook:
+
+    %load_ext sysmlpy.ipython_magic
+
+Then write SysML v2 textual notation in `%%sysml` cells:
+
+    %%sysml
+    package Vehicle {
+        part def Engine {
+            attribute fuelRate : Real;
+        }
+        part def Vehicle {
+            part engine : Vehicle::Engine;
+        }
+    }
+
+The parsed model accumulates across cells into a persistent `Model` exposed in
+the notebook namespace as `model` (alias `_sysml`). Re-declaring a package
+merges at package-member granularity: a re-declared element (matched by name +
+sysml_type) replaces the prior definition; other members are preserved.
+
+Line magics (analogues of the OMG Pilot Implementation kernel commands —
+see docs/sysml-magics.md in sysml-copier or the module docstrings):
+
+    %sysml_reset                 discard the session model
+    %sysml_list [NAME]           list packages, or find elements by exact name
+    %sysml_show NAME [--json]    print the AST rooted at a named element
+    %sysml_viz NAME [--view V]   PlantUML view of a named element
+
+Requires the `jupyter` extra: pip install sysmlpy[jupyter]
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
+from IPython.core.magic_arguments import (
+    argument,
+    magic_arguments,
+    parse_argstring,
+)
+
+
+@magics_class
+class SysMLMagics(Magics):
+    def __init__(self, shell):
+        super().__init__(shell)
+        self.model = None  # persistent session Model
+
+    # -- helpers -----------------------------------------------------------
+    def _publish(self):
+        """(Re-)bind the session model into the user namespace."""
+        self.shell.push({"model": self.model, "_sysml": self.model})
+
+    def _analyze(self, model, source: str) -> list[str]:
+        """Best-effort semantic diagnostics (analyzer API may vary)."""
+        out: list[str] = []
+        try:
+            from sysmlpy import SemanticAnalyzer
+
+            result = SemanticAnalyzer(model).analyze(source)
+            for issue in getattr(result, "issues", []) or []:
+                out.append(f"[semantic] [{issue.code}] {issue.message}")
+        except Exception:
+            pass
+        return out
+
+    def _merge(self, model) -> int:
+        """Merge freshly parsed packages into the session model.
+
+        Member-granularity merge: within a package of the same name, a
+        re-declared element (matched by name+sysml_type) replaces the prior
+        definition; other members are preserved. New packages are appended.
+        Returns the number of replaced members.
+        """
+        if self.model is None:
+            self.model = model
+            return 0
+        replaced = 0
+        for pkg in getattr(model, "packages", []):
+            existing_pkg = next(
+                (c for c in self.model.children
+                 if getattr(c, "name", None) == pkg.name),
+                None,
+            )
+            if existing_pkg is None:
+                self.model.children.append(pkg)
+                continue
+            for member in getattr(pkg, "children", []):
+                key = (getattr(member, "name", None),
+                       getattr(member, "sysml_type", None))
+                children = existing_pkg.children
+                for i, old in enumerate(children):
+                    if (getattr(old, "name", None),
+                            getattr(old, "sysml_type", None)) == key:
+                        children[i] = member
+                        replaced += 1
+                        break
+                else:
+                    children.append(member)
+        return replaced
+
+    # -- the cell magic ----------------------------------------------------
+    @magic_arguments()
+    @argument("--reset", action="store_true", help="discard the session model first")
+    @argument("--file", default=None, metavar="PATH",
+              help="parse SysML from PATH instead of the cell body (use '-' as the body)")
+    @argument("--show", action="store_true",
+              help="print the round-tripped model text after merge")
+    @cell_magic
+    def sysml(self, line: str, cell: str):
+        """Parse a cell of SysML v2 textual notation into the session model."""
+        import sys
+
+        args = parse_argstring(self.sysml, line)
+
+        if args.reset:
+            self.model = None
+
+        if args.file:
+            source = Path(args.file).read_text(encoding="utf-8")
+        else:
+            source = cell
+
+        from sysmlpy import parse
+
+        model, errors = parse(source)
+        if errors:
+            for e in errors:
+                print(f"[parse] {e}", file=sys.stderr)
+            return None
+
+        replaced = self._merge(model)
+        for w in self._analyze(model, source):
+            print(w, file=sys.stderr)
+        self._publish()
+
+        if args.show:
+            print(str(self.model))
+        total = len(getattr(self.model, "packages", []))
+        note = f", {replaced} redefined" if replaced else ""
+        print(f"sysml: model updated — {total} package(s) loaded{note}")
+        return None
+
+    # -- line magics (OMG kernel command analogues) ------------------------
+    @line_magic
+    def sysml_reset(self, line: str = ""):
+        """%sysml_reset — discard the persistent SysML session model."""
+        self.model = None
+        self.shell.user_ns.pop("model", None)
+        self.shell.user_ns.pop("_sysml", None)
+        print("sysml: session model discarded")
+
+    @line_magic
+    def sysml_list(self, line: str = ""):
+        """%sysml_list [NAME] — list packages, or find elements by exact name.
+
+        Without an argument, lists top-level packages. With a name, lists all
+        elements whose declared name matches exactly (any depth). Use
+        model.find(sysml_type=...) from Python for richer queries.
+        """
+        if self.model is None:
+            print("sysml: no model loaded — run a %%sysml cell first")
+            return None
+        name = line.strip() or None
+        if name is None:
+            for pkg in getattr(self.model, "packages", []):
+                print(pkg.name)
+            return None
+        results = self.model.find(name)
+        if not results:
+            print(f"sysml: no elements named {name!r}")
+        for r in results:
+            print(f"{r.sysml_type:14} {r.name}")
+        return None
+
+    @magic_arguments()
+    @argument("--json", action="store_true",
+              help="JSON representation (dump() output piped through json when possible)")
+    @argument("name", help="element name (exact declared name)")
+    @line_magic
+    def sysml_show(self, line: str):
+        """%sysml_show NAME [--json] — print the AST rooted at a named element."""
+        import json as _json
+
+        args = parse_argstring(self.sysml_show, line)
+        if self.model is None:
+            print("sysml: no model loaded — run a %%sysml cell first")
+            return None
+        results = self.model.find(args.name)
+        if not results:
+            print(f"sysml: no elements named {args.name!r}")
+            return None
+        for r in results:
+            text = r.dump() if hasattr(r, "dump") else str(r)
+            if args.json:
+                try:
+                    parsed = _json.loads(text)
+                    print(_json.dumps(parsed, indent=2))
+                except (_json.JSONDecodeError, TypeError):
+                    print(text)
+            else:
+                print(text)
+        return None
+
+    @magic_arguments()
+    @argument("--view", default="general", metavar="VIEW",
+              help="general|interconnection|action|package|tree")
+    @argument("names", nargs="+", help="element name(s) to visualize")
+    @line_magic
+    def sysml_viz(self, line: str):
+        """%sysml_viz NAME [--view VIEW] — PlantUML view of a named element."""
+        args = parse_argstring(self.sysml_viz, line)
+        if self.model is None:
+            print("sysml: no model loaded — run a %%sysml cell first")
+            return None
+
+        from sysmlpy import plantuml as pl
+
+        views = {
+            "general": pl.as_general_view,
+            "interconnection": pl.as_interconnection_view,
+            "action": pl.as_action_flow_view,
+            "package": pl.as_package_view,
+            "tree": pl.as_tree_diagram,
+        }
+        view = args.view.lower()
+        func = views.get(view)
+        if func is None:
+            print(f"sysml: unknown view {args.view!r}; "
+                  f"one of {', '.join(views)}")
+            return None
+        for name in args.names:
+            results = self.model.find(name)
+            if not results:
+                print(f"sysml: no elements named {name!r}")
+                continue
+            for r in results:
+                try:
+                    print(func(r, style="bw"))
+                except Exception as e:
+                    print(f"sysml: could not render {name!r}: {e}")
+        return None
+
+
+def load_ipython_extension(ipython):
+    magics = SysMLMagics(ipython)
+    ipython.register_magics(magics)
+    ipython.user_ns.setdefault("_sysml_magics", magics)