sysmlpy 0.30.2__tar.gz → 0.31.3__tar.gz

sysmlpy-0.30.2/README.md → sysmlpy-0.31.3/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.4
+Name: sysmlpy
+Version: 0.31.3
+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: graph
+Provides-Extra: kuzu
+Requires-Dist: antlr4-python3-runtime (>=4.13)
+Requires-Dist: kuzu (>=0.7,<0.12) ; extra == "kuzu"
+Requires-Dist: networkx (>=3.0) ; extra == "graph"
+Requires-Dist: pint (>=0.24)
+Requires-Dist: pyyaml (>=6.0)
+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/)
 
@@ -14,6 +38,10 @@ The project had diverged so much from sysml2py that a new name, sysmlpy, was sel
 
 ![Lines of Code Over Time](loc_history.svg)
 
+**v0.31.0:** Documentation overhaul — all docs rewritten to showcase the modern public API. New Model Parsing and Model Navigation sections. Semantic Analysis updated with `AnalysisResult`. Grammar round-trip: 77/77 (100%). 211 core tests passing.
+
+**v0.31.1:** Fixed `pyproject.toml` for CI compatibility — removed duplicate version and invalid `allow_zero_version` from `[project]` table.
+
 **v0.28.0:** Complete Gap 4 coverage — Block Definition Diagram (BDD), Internal Block Diagram (IBD), Parametric Diagram, and Package Diagram views. All 6 specialized SysML v2 view types now implemented (144 PlantUML tests). IBD shows flow/connection arrows with endpoint extraction. Parametric view extracts constraint parameters with types. Package diagram renders nested folder-style hierarchy.
 
 **v0.27.0:** General View (GV), Package View, and three GridView specializations (Tabular View, Data Value Tabular View, Relationship Matrix View) with PlantUML, Markdown, and HTML output. 108 PlantUML tests. All 68+ `NotImplementedError` stubs in `grammar/classes.py` replaced with graceful handling.
@@ -57,44 +85,60 @@ Documentation can be found [here.](https://mycr0ft.github.io/sysmlpy/)
 
 ### Basic Usage
 
-The code below will create a part called Stage 1, with a shortname of <'3.1'>
-referencing a specific requirement or document. It has a mass attribute of 100
-kg. It has a thrust attribute of 1000 N. These attributes are created and placed
-as a child of the part. Next, we recall the part value for thrust and add 199 N.
-Finally, we can dump the output from this class.
-```
-  from sysmlpy import Attribute, Part, ureg
+Build models programmatically using the public API:
+
+```python
+from sysmlpy import Part, Item, Attribute, ureg
+
+# Create a sensor part with children
+sensor = Part(name="sensor")
+camera = Part(name="camera")
+lens = Item(name="lens")
+mass = Attribute(name="mass")
+mass.set_value(100 * ureg.kilogram)
 
-  a = Attribute(name='mass')
-  a.set_value(100 * ureg.kilogram)
-  b = Attribute(name='thrust')
-  b.set_value(1000 * ureg.newton)
-  c = Part(name="Stage_1", shortname="'3.1'")
-  c._set_child(a)
-  c._set_child(b)
-  v = "Stage_1.thrust"
-  c._get_child(v).set_value(c._get_child(v).get_value() + 199 * ureg.newton)
-  print(c.dump())
+camera.add_child(mass)
+sensor.add_child(camera)
+sensor.add_child(lens)
+
+print(sensor.dump())
+# → part sensor {
+# →    part camera {
+# →       attribute mass = 100 [kilogram];
+# →    }
+# →    item lens;
+# → }
+
+# Navigate children by name
+found = sensor.find_one("camera")
+print(found.name)  # → camera
+
+# Iterate over children
+for child in sensor:
+    print(child.name)
+
+# Check containment
+"camera" in sensor  # → True
 ```
 
 It will output the following:
 ```
-  part <'3.1'> Stage_1 {
+part <'3.1'> Stage_1 {
     attribute mass= 100 [kilogram];
     attribute thrust= 1199.0 [newton];
-  }
+}
 ```
 
 The package is able to handle Items, Parts, and Attributes.
 
-```
+```python
 a = Part(name='camera')
 b = Item(name='lens')
 d = Attribute(name='mass')
 c = Part(name='sensor')
-c._set_child(a)
-c._set_child(b)
-a._set_child(d)
+c.add_child(a)
+c.add_child(b)
+a.add_child(d)
 print(c.dump())
 ```
 
@@ -158,6 +202,87 @@ print(r3.dump())
 # → ref :>> payload : Person;
 ```
 
+## Model Parsing
+
+```python
+from sysmlpy import loads, parse
+
+# loads() — raises on syntax error
+model = loads("package P { part def Engine; }")
+
+# parse() — returns (model, errors) tuple, never raises
+model, errors = parse("package P { part def Engine; }")
+assert errors == []
+
+model, errors = parse("invalid @@ syntax")
+assert model is None
+assert len(errors) > 0
+```
+
+## Model Navigation
+
+Every parsed model element supports search, iteration, and containment checks:
+
+```python
+from sysmlpy import loads, Part
+
+model = loads("""
+package Vehicle {
+    part def Engine;
+    part engine1 : Engine { attribute mass = 100 [kg]; }
+    part chassis { part wheel1; part wheel2; }
+}
+""")
+
+# find() — returns list of matching elements (empty list if none)
+parts = model.find(sysml_type="part")
+assert len(parts) >= 3
+
+# find_one() — returns single element or None
+engine = model.find_one("engine1")
+assert engine is not None
+
+missing = model.find_one("DoesNotExist")
+assert missing is None   # no IndexError!
+
+# find_one() raises LookupError if multiple matches
+# model.find_one("wheel")  → LookupError: 2 matches
+
+# Container protocol — iterate, length, containment
+for child in model:
+    print(child.name)
+
+len(model)         # → number of direct children
+"Vehicle" in model  # → True (checks child names)
+
+# __str__ returns SysML text
+print(str(model))
+# → package Vehicle { ... }
+
+# Typed property accessors
+model.packages        # direct Package children
+model.parts           # direct Part children
+model.actions         # direct Action children
+```
+
+All search methods accept `sysml_type=` (keyword string or class) and `recursive=`:
+
+```python
+from sysmlpy import Part
+
+# By string keyword
+model.find(sysml_type="action")
+
+# By class
+model.find(sysml_type=Part)
+
+# Non-recursive (direct children only)
+model.find("engine1", recursive=False)
+
+# Legacy type= keyword still works (emits DeprecationWarning)
+model.find(type="action")
+```
+
 ## Grammar Round-Trip
 
 `loads()` parses SysML v2 text and `classtree()` converts the result back to text. This round-trip is the basis for the grammar test suite.
@@ -193,7 +318,7 @@ tree = classtree(model)
 print(tree.dump())
 ```
 
-**61 of 77 grammar round-trip tests pass** (61/77). All 61 non-control-flow tests pass (100%). The 16 deferred tests require action control-flow node classes (`IfNode`, `WhileLoopNode`, `ControlNode`, `SendNode`, `AcceptNode`, `TerminateNode`) not yet ported to `grammar/classes.py`. 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, and trade studies.
+**All 77 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), and trade studies.
 
 ## Semantic Analysis
 
@@ -213,10 +338,33 @@ model = loads("""
     }
 """)
 
-issues = analyze(model)
-for issue in issues:
+result = analyze(model)
+
+# Iterate issues (backward-compatible with list)
+for issue in result:
     print(f"[{issue.severity}] {issue.code}: {issue.message}")
 # → [error] UNDEFINED_SYMBOL: Undefined symbol 'Wheel' referenced in Part 'myWheel'
+
+# Separated by severity
+for err in result.errors:
+    print(f"ERROR: {err.message}")
+
+for warn in result.warnings:
+    print(f"WARNING: {warn.message}")
+
+# Boolean check: True when no errors (warnings are OK)
+if result:
+    print("Model is semantically valid!")
+else:
+    print(f"Found {len(result.errors)} error(s) — fix before proceeding")
+
+# Raise on errors
+result.raise_on_errors()  # ValueError if any errors exist
+
+# Strict mode: raise immediately on any error
+result = analyze(model, strict=True)
+# → ValueError: Semantic errors found:
+#     [UNDEFINED_SYMBOL] Undefined symbol 'Wheel' referenced in Part 'myWheel'
 ```
 
 ### Symbol Resolution
@@ -654,3 +802,4 @@ See [`docs/plantuml-examples/`](docs/plantuml-examples/) for all rendered exampl
 
 ## License
 sysmlpy is released under the MIT license, hence allowing commercial use of the library.
+

sysmlpy-0.30.2/PKG-INFO → sysmlpy-0.31.3/README.md

@@ -1,48 +1,3 @@
-Metadata-Version: 2.4
-Name: sysmlpy
-Version: 0.30.2
-Summary: SysML v2.0 Parser
-License: MIT License
-         
-         Copyright (c) 2023-2026 Westfall-io
-         Copyright (c) 2026 Jon R. Fox
-         
-         Permission is hereby granted, free of charge, to any person obtaining a copy
-         of this software and associated documentation files (the "Software"), to deal
-         in the Software without restriction, including without limitation the rights
-         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-         copies of the Software, and to permit persons to whom the Software is
-         furnished to do so, subject to the following conditions:
-         
-         The above copyright notice and this permission notice shall be included in all
-         copies or substantial portions of the Software.
-         
-         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-         SOFTWARE.
-License-File: LICENSE
-Author: Jon R. Fox (mycr0ft)
-Author-email: jon.fox@drfox.com
-Requires-Python: >=3.7
-Classifier: Development Status :: 3 - Alpha
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Provides-Extra: graph
-Provides-Extra: kuzu
-Requires-Dist: antlr4-python3-runtime (>=4.13)
-Requires-Dist: kuzu (>=0.7,<0.12) ; extra == "kuzu"
-Requires-Dist: networkx (>=3.0) ; extra == "graph"
-Requires-Dist: pint (>=0.24)
-Requires-Dist: pyyaml (>=6.0)
-Project-URL: Bug Tracker, https://github.com/mycr0ft/sysmlpy/issues
-Project-URL: Homepage, https://github.com/mycr0ft/sysmlpy
-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/)
 
@@ -59,6 +14,10 @@ The project had diverged so much from sysml2py that a new name, sysmlpy, was sel
 
 ![Lines of Code Over Time](loc_history.svg)
 
+**v0.31.0:** Documentation overhaul — all docs rewritten to showcase the modern public API. New Model Parsing and Model Navigation sections. Semantic Analysis updated with `AnalysisResult`. Grammar round-trip: 77/77 (100%). 211 core tests passing.
+
+**v0.31.1:** Fixed `pyproject.toml` for CI compatibility — removed duplicate version and invalid `allow_zero_version` from `[project]` table.
+
 **v0.28.0:** Complete Gap 4 coverage — Block Definition Diagram (BDD), Internal Block Diagram (IBD), Parametric Diagram, and Package Diagram views. All 6 specialized SysML v2 view types now implemented (144 PlantUML tests). IBD shows flow/connection arrows with endpoint extraction. Parametric view extracts constraint parameters with types. Package diagram renders nested folder-style hierarchy.
 
 **v0.27.0:** General View (GV), Package View, and three GridView specializations (Tabular View, Data Value Tabular View, Relationship Matrix View) with PlantUML, Markdown, and HTML output. 108 PlantUML tests. All 68+ `NotImplementedError` stubs in `grammar/classes.py` replaced with graceful handling.
@@ -102,44 +61,60 @@ Documentation can be found [here.](https://mycr0ft.github.io/sysmlpy/)
 
 ### Basic Usage
 
-The code below will create a part called Stage 1, with a shortname of <'3.1'>
-referencing a specific requirement or document. It has a mass attribute of 100
-kg. It has a thrust attribute of 1000 N. These attributes are created and placed
-as a child of the part. Next, we recall the part value for thrust and add 199 N.
-Finally, we can dump the output from this class.
-```
-  from sysmlpy import Attribute, Part, ureg
+Build models programmatically using the public API:
+
+```python
+from sysmlpy import Part, Item, Attribute, ureg
+
+# Create a sensor part with children
+sensor = Part(name="sensor")
+camera = Part(name="camera")
+lens = Item(name="lens")
+mass = Attribute(name="mass")
+mass.set_value(100 * ureg.kilogram)
 
-  a = Attribute(name='mass')
-  a.set_value(100 * ureg.kilogram)
-  b = Attribute(name='thrust')
-  b.set_value(1000 * ureg.newton)
-  c = Part(name="Stage_1", shortname="'3.1'")
-  c._set_child(a)
-  c._set_child(b)
-  v = "Stage_1.thrust"
-  c._get_child(v).set_value(c._get_child(v).get_value() + 199 * ureg.newton)
-  print(c.dump())
+camera.add_child(mass)
+sensor.add_child(camera)
+sensor.add_child(lens)
+
+print(sensor.dump())
+# → part sensor {
+# →    part camera {
+# →       attribute mass = 100 [kilogram];
+# →    }
+# →    item lens;
+# → }
+
+# Navigate children by name
+found = sensor.find_one("camera")
+print(found.name)  # → camera
+
+# Iterate over children
+for child in sensor:
+    print(child.name)
+
+# Check containment
+"camera" in sensor  # → True
 ```
 
 It will output the following:
 ```
-  part <'3.1'> Stage_1 {
+part <'3.1'> Stage_1 {
     attribute mass= 100 [kilogram];
     attribute thrust= 1199.0 [newton];
-  }
+}
 ```
 
 The package is able to handle Items, Parts, and Attributes.
 
-```
+```python
 a = Part(name='camera')
 b = Item(name='lens')
 d = Attribute(name='mass')
 c = Part(name='sensor')
-c._set_child(a)
-c._set_child(b)
-a._set_child(d)
+c.add_child(a)
+c.add_child(b)
+a.add_child(d)
 print(c.dump())
 ```
 
@@ -203,6 +178,87 @@ print(r3.dump())
 # → ref :>> payload : Person;
 ```
 
+## Model Parsing
+
+```python
+from sysmlpy import loads, parse
+
+# loads() — raises on syntax error
+model = loads("package P { part def Engine; }")
+
+# parse() — returns (model, errors) tuple, never raises
+model, errors = parse("package P { part def Engine; }")
+assert errors == []
+
+model, errors = parse("invalid @@ syntax")
+assert model is None
+assert len(errors) > 0
+```
+
+## Model Navigation
+
+Every parsed model element supports search, iteration, and containment checks:
+
+```python
+from sysmlpy import loads, Part
+
+model = loads("""
+package Vehicle {
+    part def Engine;
+    part engine1 : Engine { attribute mass = 100 [kg]; }
+    part chassis { part wheel1; part wheel2; }
+}
+""")
+
+# find() — returns list of matching elements (empty list if none)
+parts = model.find(sysml_type="part")
+assert len(parts) >= 3
+
+# find_one() — returns single element or None
+engine = model.find_one("engine1")
+assert engine is not None
+
+missing = model.find_one("DoesNotExist")
+assert missing is None   # no IndexError!
+
+# find_one() raises LookupError if multiple matches
+# model.find_one("wheel")  → LookupError: 2 matches
+
+# Container protocol — iterate, length, containment
+for child in model:
+    print(child.name)
+
+len(model)         # → number of direct children
+"Vehicle" in model  # → True (checks child names)
+
+# __str__ returns SysML text
+print(str(model))
+# → package Vehicle { ... }
+
+# Typed property accessors
+model.packages        # direct Package children
+model.parts           # direct Part children
+model.actions         # direct Action children
+```
+
+All search methods accept `sysml_type=` (keyword string or class) and `recursive=`:
+
+```python
+from sysmlpy import Part
+
+# By string keyword
+model.find(sysml_type="action")
+
+# By class
+model.find(sysml_type=Part)
+
+# Non-recursive (direct children only)
+model.find("engine1", recursive=False)
+
+# Legacy type= keyword still works (emits DeprecationWarning)
+model.find(type="action")
+```
+
 ## Grammar Round-Trip
 
 `loads()` parses SysML v2 text and `classtree()` converts the result back to text. This round-trip is the basis for the grammar test suite.
@@ -238,7 +294,7 @@ tree = classtree(model)
 print(tree.dump())
 ```
 
-**61 of 77 grammar round-trip tests pass** (61/77). All 61 non-control-flow tests pass (100%). The 16 deferred tests require action control-flow node classes (`IfNode`, `WhileLoopNode`, `ControlNode`, `SendNode`, `AcceptNode`, `TerminateNode`) not yet ported to `grammar/classes.py`. 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, and trade studies.
+**All 77 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), and trade studies.
 
 ## Semantic Analysis
 
@@ -258,10 +314,33 @@ model = loads("""
     }
 """)
 
-issues = analyze(model)
-for issue in issues:
+result = analyze(model)
+
+# Iterate issues (backward-compatible with list)
+for issue in result:
     print(f"[{issue.severity}] {issue.code}: {issue.message}")
 # → [error] UNDEFINED_SYMBOL: Undefined symbol 'Wheel' referenced in Part 'myWheel'
+
+# Separated by severity
+for err in result.errors:
+    print(f"ERROR: {err.message}")
+
+for warn in result.warnings:
+    print(f"WARNING: {warn.message}")
+
+# Boolean check: True when no errors (warnings are OK)
+if result:
+    print("Model is semantically valid!")
+else:
+    print(f"Found {len(result.errors)} error(s) — fix before proceeding")
+
+# Raise on errors
+result.raise_on_errors()  # ValueError if any errors exist
+
+# Strict mode: raise immediately on any error
+result = analyze(model, strict=True)
+# → ValueError: Semantic errors found:
+#     [UNDEFINED_SYMBOL] Undefined symbol 'Wheel' referenced in Part 'myWheel'
 ```
 
 ### Symbol Resolution
@@ -699,4 +778,3 @@ See [`docs/plantuml-examples/`](docs/plantuml-examples/) for all rendered exampl
 
 ## License
 sysmlpy is released under the MIT license, hence allowing commercial use of the library.
-

sysmlpy-0.31.3/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+#requires = ["setuptools>=61.0"]
+#build-backend = "setuptools.build_meta"
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "sysmlpy"
+version = "0.31.3"
+description = ""
+authors = [{ name = "Jon R. Fox (mycr0ft)", email = "jon.fox@drfox.com" }]
+readme = "README.md"
+packages = [{ include = "sysmlpy", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+pint = ">=0.24"
+pyyaml = ">=6.0"
+antlr4-python3-runtime = ">=4.13"
+networkx = { version = ">=3.0", optional = true }
+kuzu = { version = ">=0.7,<0.12", optional = true }
+
+[tool.poetry.extras]
+graph = ["networkx"]
+kuzu = ["kuzu"]
+
+[tool.poetry.scripts]
+sysmlpy = "sysmlpy.__main__:main"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0,<9.0"
+

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

@@ -21,7 +21,7 @@ __all__ = [
     "SysMLSyntaxError",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.30.2"
+__version__ = "0.31.3"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,

{sysmlpy-0.30.2 → sysmlpy-0.31.3}/src/sysmlpy/grammar/classes.py

@@ -2555,8 +2555,7 @@ class ActionDefinition:
             output.append(self.prefix.dump())
         output.append(self.keyword)
         output.append(self.declaration.dump())
-        output.append(self.body.dump())
-        return " ".join(output)
+        return " ".join(filter(None, output)) + self.body.dump()
 
     def get_definition(self):
         output = {"name": self.__class__.__name__, "prefix": None}
@@ -4611,7 +4610,7 @@ class Definition:
             self.body = DefinitionBody()
 
     def dump(self):
-        return " ".join([self.declaration.dump(), self.body.dump()])
+        return "".join([self.declaration.dump(), self.body.dump()])
 
     def get_definition(self):
         return {