sysmlpy 0.1.0__py3-none-any.whl

sysmlpy/__init__.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+SysML v2 Python Library
+
+A pure Python implementation for parsing SysML v2.0 models.
+Uses the ANTLR4 parser for full SysML v2 grammar support.
+"""
+
+__all__ = [
+    "load", "loads", "load_grammar", "load_antlr", "load_grammar_antlr",
+    "Searchable",
+    "Store", "InMemoryStore", "NetworkXStore", "create_store", "new_id",
+]
+__author__ = "Jon Fox"
+__version__ = "0.12.1"
+
+from sysmlpy.usage import (
+    Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,
+    State, Constraint, Connection, Flow, Calculation, Enumeration,
+    Allocation, Metadata, Rendering, Individual, FlowDef,
+    View, Viewpoint, Concern,
+    Case, AnalysisCase, VerificationCase,
+)
+
+from sysmlpy.definition import Model, Package
+from sysmlpy.navigate import Searchable
+from sysmlpy.store import Store, InMemoryStore, NetworkXStore, create_store, new_id
+
+from sysmlpy.usage import ureg
+
+
+def load_grammar(s, debug=False):
+    """SysML load from string to dictionary
+
+    Deserialize a string containing a SysML v2.0 document to a Python dictionary.
+
+    Parameters
+    ----------
+    s : str or _io.TextIOWrapper
+        String instance of SysML v2.0 document or file pointer
+
+    Returns
+    -------
+    dict
+        Dictionary version structured utilizing SysML v2.0 grammar
+
+    Raises
+    ------
+    TypeError
+        Input was not str or file
+    """
+    import sysmlpy.antlr_visitor as antlr_visitor
+    import sysmlpy.antlr_parser as antlr_parser
+    import io
+
+    # Handle file pointer or string
+    if isinstance(s, io.TextIOWrapper):
+        s = s.read()
+    elif not isinstance(s, str):
+        raise TypeError(
+            f"the SysML object must be str or file, not {s.__class__.__name__}"
+        )
+
+    # Wrap in package if not starting with 'package' for parsing
+    s_stripped = s.strip()
+    needs_unwrap = not s_stripped.startswith('package')
+    if needs_unwrap:
+        s = f'package __implicit__ {{ {s_stripped} }}'
+
+    try:
+        result = antlr_visitor.parse_to_dict(s)
+        
+        # If we wrapped, we need to return a format compatible with what the tests expect
+        # The grammar classes expect "PackageBodyElement" as the top-level name
+        if needs_unwrap:
+            # Navigate to Package body ownedRelationship
+            pkg_member = result['ownedRelationship'][0]
+            pkg_elem = pkg_member['ownedRelatedElement']
+            pkg = pkg_elem['ownedRelatedElement']
+            body = pkg['body']
+            
+            # Return in PackageBodyElement format (no Package wrapper)
+            return {
+                "name": "PackageBodyElement",
+                "ownedRelationship": body['ownedRelationship']
+            }
+        
+        return result
+    except antlr_parser.SysMLSyntaxError as e:
+        print("ANTLR4 returned the following error: {}".format(e))
+        raise
+
+
+def load(fp):
+    """SysML load from file pointer
+
+    Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
+    a SysML v2.0 document) to a Python dictionary object.
+
+    Parameters
+    ----------
+    fp : _io.TextIOWrapper
+        File pointer to SysML v2.0 document
+
+    Returns
+    -------
+    dict
+        Dictionary version structured utilizing SysML v2.0 grammar
+
+    Raises
+    ------
+    TypeError
+        Input was not _io.TextIOWrapper
+    """
+    import io
+
+    if not isinstance(fp, io.TextIOWrapper):
+        raise TypeError(
+            f"the SysML object must be _io.TextIOWrapper, "
+            f"not {fp.__class__.__name__}"
+        )
+
+    return loads(fp.read())
+
+
+def loads(s: str, library=None):
+    """Loads a model from string.
+
+    This shortcut function allows a user to build a model from a string by
+    first instantiating a base model class which builds out a default namespace
+    and then that model loads all elements underneath.
+
+    Uses the ANTLR4 parser.
+
+    Parameters
+    ----------
+    s : str
+        The SysML v2 source code to parse.
+    library : str or Path, optional
+        Path to SysML v2 library files for resolving imports.
+    """
+    return Model().load(s, library=library)
+
+
+def load_grammar_antlr(fp, debug=False, library=None):
+    """SysML load from file pointer using ANTLR4 parser.
+
+    Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
+    a SysML v2.0 document) or ``s`` (a ``str`` instance containing a SysML
+    v2.0 document) to a Python dictionary object using the ANTLR4 parser.
+
+    Parameters
+    ----------
+    fp : _io.TextIOWrapper or str
+        File pointer to SysML v2.0 document or string instance of SysML v2.0
+        document
+    debug : bool
+        Enable debug output.
+    library : str or Path, optional
+        Path to SysML v2 library files for resolving imports.
+
+    Returns
+    -------
+    dict
+        Dictionary version structured utilizing SysML v2.0 grammar
+
+    Raises
+    ------
+    TypeError
+        Input was not _io.TextIOWrapper or str
+
+    """
+    import io
+    import sysmlpy.antlr_visitor as antlr_visitor
+    import sysmlpy.antlr_parser as antlr_parser
+
+    if isinstance(fp, io.TextIOWrapper):
+        s = fp.read()
+    elif isinstance(fp, str):
+        s = fp
+    else:
+        raise TypeError(
+            f"the SysML object must be _io.TextIOWrapper or str "
+            f"not {fp.__class__.__name__}"
+        )
+
+    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):
+    """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.
+
+    Parameters
+    ----------
+    fp : _io.TextIOWrapper
+        File pointer to SysML v2.0 document
+
+    Returns
+    -------
+    dict
+        Dictionary version structured utilizing SysML v2.0 grammar
+
+    Raises
+    ------
+    TypeError
+        Input was not _io.TextIOWrapper
+    """
+    import io
+
+    if not isinstance(fp, io.TextIOWrapper):
+        raise TypeError(
+            f"the SysML object must be _io.TextIOWrapper, "
+            f"not {fp.__class__.__name__}"
+        )
+
+    return loads(fp.read())
+
+

sysmlpy/__main__.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Command line interface for sysmlpy."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from sysmlpy import loads
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="sysmlpy",
+        description="Parse SysML v2 files and display their Python representation"
+    )
+    parser.add_argument(
+        "file",
+        type=str,
+        help="Path to the SysML v2 file to parse"
+    )
+    parser.add_argument(
+        "--python",
+        action="store_true",
+        help="Display the Python repr() representation of the parsed model"
+    )
+    parser.add_argument(
+        "-l", "--library",
+        type=str,
+        help="Path to SysML v2 library files to use for parsing"
+    )
+    parser.add_argument(
+        "--dump",
+        action="store_true",
+        help="Display the SysML text output (dump format)"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Display the dictionary/JSON representation"
+    )
+
+    args = parser.parse_args()
+
+    file_path = Path(args.file)
+    if not file_path.exists():
+        print(f"Error: File '{args.file}' not found.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with open(file_path, 'r') as f:
+            content = f.read()
+    except IOError as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        model = loads(content, library=args.library)
+    except Exception as e:
+        print(f"Error parsing SysML file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        from sysmlpy import load_grammar
+        grammar_dict = load_grammar(content)
+        import json
+        print(json.dumps(grammar_dict, indent=2))
+    elif args.dump:
+        print(model.dump())
+    else:
+        # Default or --python flag: show repr()
+        print(repr(model))
+
+if __name__ == "__main__":
+    main()

sysmlpy/antlr/README.md

@@ -0,0 +1,146 @@
+# ANTLR4 Parser for SysML v2
+
+## Overview
+
+sysmlpy now includes an experimental **ANTLR4-based parser** as an alternative to the textX parser. This provides a pure Python implementation that can parse SysML v2.0 using grammars derived from the official OMG specification.
+
+## Why ANTLR4?
+
+The original textX parser requires manual conversion from the official XText grammar (used in the OMG SysML v2 Pilot Implementation). This is labor-intensive and can drift from the official specification.
+
+The ANTLR4 approach:
+- Uses grammars auto-generated from the official OMG KEBNF specification
+- Grammar version tracks the OMG release (e.g., v2026.03.0 for 2026-03 release)
+- Provides a pure Python alternative to Java/TypeScript-based SysMLv2 parsers
+
+## Project Structure
+
+```
+src/sysmlpy/
+├── antlr_parser.py       # Core ANTLR4 parsing functions
+├── antlr_visitor.py      # Convert parse tree to Python classes
+├── antlr/                 # Generated ANTLR4 parser (auto-generated)
+│   ├── SysMLv2Lexer.py
+│   ├── SysMLv2Parser.py
+│   ├── SysMLv2ParserVisitor.py
+│   └── ...
+└── grammar/antlr4/         # Grammar source files
+    ├── SysMLv2Lexer.g4
+    ├── SysMLv2Parser.g4
+    └── examples/          # Test files
+```
+
+## Usage
+
+### Using the ANTLR4 Parser
+
+```python
+from sysmlpy import load_antlr, loads, load_grammar
+
+# Load from file
+with open('model.sysml', 'r') as f:
+    model = load_antlr(f)
+
+# Load from string
+model = loads('''
+package VehicleModel {
+    part def Vehicle {
+        attribute mass : Real;
+    }
+}
+''')
+
+# Get raw grammar dictionary
+grammar_dict = load_grammar('package Test;')
+
+# Print the model
+print(model.dump())
+```
+
+### Round-trip Support
+
+The ANTLR4 parser supports round-trip parsing:
+
+```python
+from sysmlpy import loads
+
+# Parse SysML
+model = loads('package Test { part def Vehicle; }')
+
+# Dump to string
+output = model.dump()
+
+# Parse again - should produce identical output
+model2 = loads(output)
+assert output == model2.dump()
+```
+
+### Choosing the Parser
+
+All public API functions now use the ANTLR4 parser:
+
+```python
+from sysmlpy import loads  # ANTLR4-based (default)
+```
+
+## Grammar Sources
+
+The ANTLR4 grammar is sourced from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar), which automatically generates ANTLR4 grammars from the OMG SysML v2 specification KEBNF files.
+
+- **Current grammar version:** v2026.03.0
+- **OMG release:** 2026-03
+- **Source:** [Systems-Modeling/SysML-v2-Release](https://github.com/Systems-Modeling/SysML-v2-Release)
+
+## What's Supported
+
+The following SysML v2 constructs work with the ANTLR4 parser:
+
+- Package definitions
+- Part definitions and usages
+- Attribute definitions and usages
+- Item definitions and usages
+- Port definitions and usages
+- Requirement definitions
+- Use case definitions
+
+## Known Limitations
+
+1. **Some complex elements** - Requirements, UseCases, and Ports with full bodies may have partial support
+2. **Round-trip fidelity** - Some whitespace/formatting differences may occur
+3. **Grammar drift** - The auto-generated grammar may have minor differences from the official OMG specification
+
+## Updating the Grammar
+
+To update to a newer OMG release:
+
+```bash
+# Download the latest grammar release from daltskin/sysml-v2-grammar
+# Or regenerate from the OMG KEBNF specification
+
+# Regenerate the Python parser
+java -jar antlr-4.13.2-complete.jar -Xexact-output-dir \
+    -o src/sysmlpy/antlr \
+    -visitor -listener -Dlanguage=Python3 \
+    src/sysmlpy/grammar/antlr4/SysMLv2Lexer.g4 \
+    src/sysmlpy/grammar/antlr4/SysMLv2Parser.g4
+```
+
+## Comparison: textX vs ANTLR4
+
+| Feature | textX | ANTLR4 |
+|---------|-------|--------|
+| Grammar source | Manual XText conversion | Auto-generated from OMG KEBNF |
+| Grammar updates | Labor-intensive | Automated |
+| Parse performance | Good | Good |
+| Error messages | Good | Excellent |
+| Python-only | Yes | Yes |
+| Round-trip support | Full | Partial |
+| Specification tracking | Manual | Automatic |
+
+## Future Work
+
+1. Complete support for all SysML v2 constructs
+2. Improve round-trip fidelity
+3. Add conformance tests against OMG test suite
+4. Consider making ANTLR4 the default parser
+5. Remove textX dependency once ANTLR4 is stable