sysmlpy 0.30.0__tar.gz → 0.30.2__tar.gz

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.30.0
+Version: 0.30.2
 Summary: SysML v2.0 Parser
 License: MIT License
          

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "sysmlpy"
-version = "0.30.0"
+version = "0.30.2"
 description = "SysML v2.0 Parser"
 authors = [
   { name="Jon R. Fox (mycr0ft)", email="jon.fox@drfox.com" },
@@ -114,7 +114,7 @@ build_command = "pip install poetry && poetry build"
 
 [tool.poetry]
 name = "sysmlpy"
-version = "0.30.0"
+version = "0.30.2"
 description = ""
 authors = ["Jon R. Fox (mycr0ft) <jon.fox@drfox.com>"]
 readme = "README.md"

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/src/sysmlpy/__init__.py

@@ -8,7 +8,7 @@ Uses the ANTLR4 parser for full SysML v2 grammar support.
 """
 
 __all__ = [
-    "load", "loads", "load_grammar", "load_antlr", "load_grammar_antlr",
+    "load", "loads", "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",
@@ -17,10 +17,11 @@ __all__ = [
     "as_general_view", "as_package_view", "as_package_diagram_view", "as_block_definition_view", "as_internal_block_diagram",
     "as_parametric_view", "as_requirement_view",
     "as_tabular_view", "as_data_value_tabular_view", "as_relationship_matrix_view",
-    "analyze", "SemanticIssue", "SemanticAnalyzer",
+    "analyze", "AnalysisResult", "SemanticIssue", "SemanticAnalyzer",
+    "SysMLSyntaxError",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.30.0"
+__version__ = "0.30.2"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,
@@ -35,6 +36,7 @@ from sysmlpy.navigate import Searchable
 from sysmlpy.store import Store, InMemoryStore, NetworkXStore, KuzuStore, CayleyStore, create_store, new_id
 
 from sysmlpy.usage import ureg
+from sysmlpy.antlr_parser import SysMLSyntaxError
 
 
 def load_grammar(s, debug=False):
@@ -95,15 +97,14 @@ def load_grammar(s, debug=False):
         
         return result
     except antlr_parser.SysMLSyntaxError as e:
-        print("ANTLR4 returned the following error: {}".format(e))
         raise
 
 
-def load(fp):
+def load(fp) -> Model:
     """SysML load from file pointer
 
     Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
-    a SysML v2.0 document) to a Python dictionary object.
+    a SysML v2.0 document) to a Model object.
 
     Parameters
     ----------
@@ -112,8 +113,8 @@ def load(fp):
 
     Returns
     -------
-    dict
-        Dictionary version structured utilizing SysML v2.0 grammar
+    Model
+        Model instance structured utilizing SysML v2.0 grammar
 
     Raises
     ------
@@ -131,7 +132,7 @@ def load(fp):
     return loads(fp.read())
 
 
-def loads(s: str, library=None):
+def loads(s: str, library=None) -> Model:
     """Loads a model from string.
 
     This shortcut function allows a user to build a model from a string by
@@ -146,10 +147,36 @@ def loads(s: str, library=None):
         The SysML v2 source code to parse.
     library : str or Path, optional
         Path to SysML v2 library files for resolving imports.
+
+    Returns
+    -------
+    Model
+        Model instance built from the SysML source.
     """
     return Model().load(s, library=library)
 
 
+def parse(s: str, library=None):
+    """Parse SysML source, returning (model, errors) rather than raising.
+
+    Parameters
+    ----------
+    s : str
+        The SysML v2 source code to parse.
+    library : str or Path, optional
+        Path to SysML v2 library files for resolving imports.
+
+    Returns
+    -------
+    tuple[Model | None, list[str]]
+        ``(Model, [])`` on success, ``(None, [error_lines])`` on syntax error.
+    """
+    try:
+        return loads(s, library=library), []
+    except SysMLSyntaxError as e:
+        return None, str(e).splitlines()
+
+
 def load_grammar_antlr(fp, debug=False, library=None):
     """SysML load from file pointer using ANTLR4 parser.
 
@@ -195,15 +222,14 @@ def load_grammar_antlr(fp, debug=False, library=None):
     try:
         return antlr_visitor.parse_to_dict(s, library=library)
     except antlr_parser.SysMLSyntaxError as e:
-        print("ANTLR4 returned the following error: {}".format(e))
         raise
 
 
-def load_antlr(fp):
+def load_antlr(fp) -> Model:
     """SysML load from file pointer using ANTLR4 parser.
 
     Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
-    a SysML v2.0 document) to a Python dictionary object.
+    a SysML v2.0 document) to a Model object.
 
     Parameters
     ----------
@@ -212,8 +238,8 @@ def load_antlr(fp):
 
     Returns
     -------
-    dict
-        Dictionary version structured utilizing SysML v2.0 grammar
+    Model
+        Model instance structured utilizing SysML v2.0 grammar
 
     Raises
     ------
@@ -237,7 +263,7 @@ from sysmlpy.plantuml import (to_plantuml, PlantUMLGenerator,
     as_parametric_view, as_requirement_view,
     as_tabular_view, as_data_value_tabular_view, as_relationship_matrix_view)
 
-from sysmlpy.semantic import analyze, SemanticIssue, SemanticAnalyzer
+from sysmlpy.semantic import analyze, AnalysisResult, SemanticIssue, SemanticAnalyzer
 
 from sysmlpy.project import load_files, load_project, load_with_dependencies
 

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/src/sysmlpy/definition.py

@@ -203,7 +203,7 @@ class Model(Searchable):
         """
         return self.grammar.get_definition()
 
-    def dump(self):
+    def dump(self) -> str:
         """Serialize the model to SysML v2 textual notation.
 
         Returns
@@ -230,6 +230,13 @@ class Model(Searchable):
         self._ensure_body()
         return classtree(self._get_definition()).dump()
 
+    def __str__(self) -> str:
+        """Return the SysML v2 text representation of the model."""
+        try:
+            return self.dump()
+        except Exception:
+            return repr(self)
+
     def _set_child(self, child):
         """Add a child package or element to the model.
 
@@ -247,6 +254,23 @@ class Model(Searchable):
         child.parent = self
         return self
 
+    add_child = _set_child
+
+    def _get_child(self, featurechain):
+        """Retrieve a nested child by dot-separated name path.
+
+        Parameters
+        ----------
+        featurechain : str
+            Dot-separated path like "pkg.element".
+
+        Returns
+        -------
+        element or None
+            The matching child element, or None if not found.
+        """
+        return self
+
     def _get_child(self, featurechain):
         """Retrieve a nested child by dot-separated name path.
 
@@ -276,6 +300,8 @@ class Model(Searchable):
                 else:
                     return child._get_child(featurechain)
 
+    get_child = _get_child
+
     # ── Convenience functions ───────────────────────────────────────────
 
     def find_all(self, type=None, name=None):
@@ -452,6 +478,8 @@ class Package(Searchable):
 
         return self
 
+    set_name = _set_name
+
     def _get_name(self):
         """Retrieve the declared name from the package grammar.
 
@@ -479,6 +507,23 @@ class Package(Searchable):
         child.parent = self
         return self
 
+    add_child = _set_child
+
+    def _get_child(self, featurechain):
+        """Retrieve a nested child by dot-separated name path.
+
+        Parameters
+        ----------
+        featurechain : str
+            Dot-separated path like "pkg.element".
+
+        Returns
+        -------
+        element or None
+            The matching child element, or None if not found.
+        """
+        return self
+
     def _get_child(self, featurechain):
         """Retrieve a nested child by dot-separated name path.
 
@@ -509,6 +554,8 @@ class Package(Searchable):
                 else:
                     return child._get_child(featurechain)
 
+    get_child = _get_child
+
     def _ensure_body(self):
         """Rebuild the package grammar body from current children and imports.
 
@@ -572,7 +619,7 @@ class Package(Searchable):
 
         return package
 
-    def dump(self, child=None):
+    def dump(self, child=None) -> str:
         """Serialize the package to SysML v2 textual notation.
 
         Parameters
@@ -587,6 +634,13 @@ class Package(Searchable):
         """
         return classtree(self._get_definition(child=False)).dump()
 
+    def __str__(self) -> str:
+        """Return the SysML v2 text representation of the package."""
+        try:
+            return self.dump()
+        except Exception:
+            return repr(self)
+
     def add_import(self, namespace, visibility="private", recursive=False, membership=None):
         """Add an import declaration to this package.
 

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/src/sysmlpy/navigate.py

@@ -16,12 +16,12 @@ After parsing, every node in the public-API tree supports::
     model.actions           # direct Action children
 
     model.find('Focus')                    # by name, any depth
-    model.find(type='action')              # by type keyword, any depth
-    model.find('Focus', type='action')     # name + type
-    model.find(type=Action)               # by class
-    model.find('Focus', recursive=False)  # direct children only
+    model.find(sysml_type='action')        # by type keyword, any depth
+    model.find('Focus', sysml_type='action')  # name + type
+    model.find(sysml_type=Action)          # by class
+    model.find('Focus', recursive=False)   # direct children only
 
-    model.all('part')                      # shorthand for find(type='part')
+    model.all('part')                      # shorthand for find(sysml_type='part')
 
 Type strings
 ------------
@@ -188,17 +188,19 @@ class Searchable:
     # Search methods
     # ------------------------------------------------------------------
 
-    def find(self, name=None, *, type=None, recursive=True):
+    def find(self, name=None, *, sysml_type=None, type=None, recursive=True) -> "list[Searchable]":
         """Find model elements by name and/or SysML type.
 
         Parameters
         ----------
         name : str, optional
             Declared element name to match exactly.  ``None`` matches any name.
-        type : str or class, optional
+        sysml_type : str or class, optional
             SysML type to filter by.  Pass a string keyword (``'part'``,
             ``'action'``, …) or the corresponding class (``Part``,
             ``Action``, …).  ``None`` matches any type.
+        type : str or class, optional
+            Deprecated alias for ``sysml_type``.
         recursive : bool
             When ``True`` (default) the search descends recursively into
             every child that itself exposes a ``find`` method.
@@ -216,17 +218,25 @@ class Searchable:
 
         Find every action, top-level only::
 
-            model.find(type='action', recursive=False)
+            model.find(sysml_type='action', recursive=False)
 
         Find by class instead of string::
 
             from sysmlpy import Part
-            model.find(type=Part)
+            model.find(sysml_type=Part)
 
         Combine name and type::
 
-            model.find('engine', type='part')
+            model.find('engine', sysml_type='part')
         """
+        if type is not None and sysml_type is None:
+            import warnings
+            warnings.warn(
+                "find(type=...) is deprecated; use find(sysml_type=...) instead",
+                DeprecationWarning, stacklevel=2
+            )
+            sysml_type = type
+
         results = []
         for child in getattr(self, "children", []):
             # --- name gate ---
@@ -236,32 +246,34 @@ class Searchable:
                 name_ok = True
 
             # --- type gate ---
-            if type is None:
+            if sysml_type is None:
                 type_ok = True
-            elif isinstance(type, str):
-                type_ok = getattr(child, "sysml_type", None) == type
+            elif isinstance(sysml_type, str):
+                type_ok = getattr(child, "sysml_type", None) == sysml_type
             else:
-                type_ok = isinstance(child, type)
+                type_ok = isinstance(child, sysml_type)
 
             if name_ok and type_ok:
                 results.append(child)
 
             # --- recurse ---
             if recursive and hasattr(child, "find"):
-                results.extend(child.find(name=name, type=type, recursive=True))
+                results.extend(child.find(name=name, sysml_type=sysml_type, recursive=True))
 
         return results
 
-    def all(self, type, recursive=True):
-        """Return all elements of *type*, searching recursively by default.
+    def all(self, sysml_type, type=None, recursive=True) -> "list[Searchable]":
+        """Return all elements of *sysml_type*, searching recursively by default.
 
-        This is a convenience alias for ``find(type=type, recursive=recursive)``.
+        This is a convenience alias for ``find(sysml_type=sysml_type, recursive=recursive)``.
 
         Parameters
         ----------
-        type : str or class
+        sysml_type : str or class
             SysML type string (``'part'``, ``'action'``, …) or the
             corresponding class.
+        type : str or class, optional
+            Deprecated alias for ``sysml_type``.
         recursive : bool
             When ``True`` (default) the search descends into every child.
 
@@ -269,4 +281,63 @@ class Searchable:
         -------
         list
         """
-        return self.find(type=type, recursive=recursive)
+        if type is not None and sysml_type is None:
+            import warnings
+            warnings.warn(
+                "all(type=...) is deprecated; use all(sysml_type=...) instead",
+                DeprecationWarning, stacklevel=2
+            )
+            sysml_type = type
+        return self.find(sysml_type=sysml_type, recursive=recursive)
+
+    def find_one(self, name=None, *, sysml_type=None) -> "Searchable | None":
+        """Return the single matching element, or None if not found.
+
+        Raises LookupError if more than one match is found.
+        Use find() if you expect multiple results.
+        """
+        results = self.find(name, sysml_type=sysml_type)
+        if not results:
+            return None
+        if len(results) > 1:
+            raise LookupError(
+                f"find_one: {len(results)} matches for {name!r}, expected at most 1"
+            )
+        return results[0]
+
+    # ------------------------------------------------------------------
+    # Container protocol (__iter__, __len__, __contains__)
+    # ------------------------------------------------------------------
+
+    def __iter__(self):
+        """Iterate over direct children."""
+        return iter(self.children)
+
+    def __len__(self) -> int:
+        """Return the number of direct children."""
+        return len(self.children)
+
+    def __contains__(self, item) -> bool:
+        """True if item is a direct child, or if a string matches any child's name."""
+        if isinstance(item, str):
+            return any(getattr(c, 'name', None) == item for c in self.children)
+        return item in self.children
+
+    # ------------------------------------------------------------------
+    # Jupyter HTML representation
+    # ------------------------------------------------------------------
+
+    def _repr_html_(self) -> str:
+        """Jupyter-friendly collapsible HTML tree."""
+        def _render(elem, depth=0):
+            name = getattr(elem, 'name', '?')
+            stype = getattr(elem, 'sysml_type', type(elem).__name__)
+            is_def = getattr(elem, 'is_definition', False)
+            badge = f'<code style="color:#888;font-size:0.8em">{stype}{"_def" if is_def else ""}</code>'
+            children = getattr(elem, 'children', [])
+            if children:
+                inner = ''.join(_render(c, depth + 1) for c in children)
+                return (f'<details open><summary>{badge} <b>{name}</b></summary>'
+                        f'<div style="margin-left:1em">{inner}</div></details>')
+            return f'<div>{badge} {name}</div>'
+        return f'<div style="font-family:monospace">{_render(self)}</div>'

{sysmlpy-0.30.0 → sysmlpy-0.30.2}/src/sysmlpy/semantic.py

@@ -28,6 +28,38 @@ class SemanticIssue:
     reference: str = ""
 
 
+class AnalysisResult(list):
+    """A list of SemanticIssue with convenience accessors.
+
+    Backward-compatible with ``list[SemanticIssue]`` — existing code that
+    iterates or checks ``isinstance(result, list)`` continues to work.
+    """
+
+    @property
+    def errors(self) -> list[SemanticIssue]:
+        """Return only error-severity issues."""
+        return [i for i in self if i.severity == "error"]
+
+    @property
+    def warnings(self) -> list[SemanticIssue]:
+        """Return only warning-severity issues."""
+        return [i for i in self if i.severity == "warning"]
+
+    def raise_on_errors(self, message: str = "Semantic errors found") -> "AnalysisResult":
+        """Raise ValueError if any error-severity issues exist.
+
+        Returns self for chaining when no errors are present.
+        """
+        if self.errors:
+            details = "\n".join(f"  [{i.code}] {i.message}" for i in self.errors)
+            raise ValueError(f"{message}:\n{details}")
+        return self
+
+    def __bool__(self) -> bool:
+        """True when there are no errors (warnings are acceptable)."""
+        return len(self.errors) == 0
+
+
 # ---------------------------------------------------------------------------
 # Library Symbol Index
 # ---------------------------------------------------------------------------
@@ -2096,7 +2128,8 @@ def analyze(
     library: Path | Sequence[Path] | str | Sequence[str] | None = None,
     filename: str | Path | None = None,
     style_checks: bool = True,
-) -> list[SemanticIssue]:
+    strict: bool = False,
+) -> AnalysisResult:
     """Run semantic analysis on *model* and return issues.
 
     Parameters
@@ -2111,12 +2144,20 @@ def analyze(
     style_checks : bool
         If True (default), run stylistic checks (naming conventions,
         file-package matching). Set to False to skip warnings.
+    strict : bool
+        If True, raises ValueError when any error-severity issues are found.
+        Default False.
 
     Returns
     -------
-    list[SemanticIssue]
-        List of semantic issues found.
+    AnalysisResult
+        List of semantic issues found, wrapped in AnalysisResult for
+        convenient access to ``.errors`` and ``.warnings`` properties.
     """
-    return SemanticAnalyzer().analyze(
+    issues = SemanticAnalyzer().analyze(
         model, library=library, filename=filename, style_checks=style_checks
     )
+    result = AnalysisResult(issues)
+    if strict:
+        result.raise_on_errors()
+    return result