rhapsody-cli 0.1.0__tar.gz

rhapsody_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 melodypapa
+
+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.

rhapsody_cli-0.1.0/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: rhapsody-cli
+Version: 0.1.0
+Summary: Pythonic wrapper around the IBM Rhapsody COM API, mirroring the Rhapsody Java API
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywin32>=306; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: black<25,>=24.1; extra == "dev"
+Requires-Dist: mypy<2,>=1.8; extra == "dev"
+Provides-Extra: cli
+Requires-Dist: tabulate>=0.9; extra == "cli"
+Requires-Dist: rich>=13.0; extra == "cli"
+Dynamic: license-file
+
+# rhapsody-cli
+
+[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://github.com/user/rhapsody-cli)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://www.microsoft.com/windows)
+
+A Pythonic, object-oriented wrapper around the IBM Rhapsody COM API for
+Windows. Method names and class hierarchy mirror the Rhapsody Java API
+(`com.telelogic.rhapsody.core`) exactly, so existing Rhapsody Java API
+knowledge and documentation transfer directly.
+
+## Features
+
+- **Complete API Mirroring**: Method names and signatures match the Rhapsody Java API exactly
+- **Object-Oriented Design**: Clean Python classes wrapping COM objects with proper type hints
+- **Comprehensive Element Support**: 50+ Rhapsody element types wrapped with full method coverage
+- **CLI Tools**: Command-line utilities for element management, I/O operations, and project handling
+- **Multi-Level Path Navigation**: Navigate hierarchical model structures using `/` or `\` separators
+- **Bulk Operations**: Add multiple elements, query recursively, and delete with safety confirmations
+- **Robust Error Handling**: Automatic COM error translation with user-friendly exception messages
+- **Mocked Testing**: Full test suite runs without Rhapsody installation or license
+- **Type Safety**: Strict mypy checking with comprehensive type annotations
+- **Cross-Instance Support**: Manage multiple simultaneous Rhapsody instances in the same process
+
+## Requirements
+
+- Windows with a licensed IBM Rhapsody installation (COM automation is
+  Windows-only)
+- Python 3.8+
+- `pywin32` (automatically installed on Windows)
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install rhapsody-cli
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev,cli]"
+```
+
+This installs:
+- **Core dependencies**: `pywin32` (Windows COM support)
+- **CLI dependencies**: `tabulate`, `rich` (table formatting and colored output)
+- **Dev dependencies**: `pytest`, `pytest-cov`, `ruff`, `black`, `mypy` (testing and linting)
+
+## Usage
+
+### Python API
+
+```python
+from rhapsody_cli import RhapsodyApplication
+
+# Attaches to a running Rhapsody instance, or launches a new one if none
+# is running.
+app = RhapsodyApplication.connect()
+
+# Open an existing project
+project = app.open_project(r"C:\Models\MyProject.rpy")
+
+# Create a new package
+package = project.addPackage("Sensors")
+
+# Add classes with attributes and operations
+sensor_class = package.addClass("TemperatureSensor")
+sensor_class.addAttribute("currentTemperature")
+sensor_class.addOperation("readTemperature")
+
+# Navigate existing elements
+for cls in project.get_nested_elements_by_meta_class("Class", 1):  # recursive
+    print(f"Class: {cls.get_name()}")
+    for attr in cls.get_attributes():
+        print(f"  Attribute: {attr.get_name()}")
+
+# Save and quit
+project.save()
+app.quit()
+```
+
+### Command-Line Interface
+
+The CLI provides three main command groups:
+
+#### Element Management
+
+```bash
+# Add elements with multi-level paths
+rhapsody-cli element add --type class --path "Sensors/TemperatureSensor"
+rhapsody-cli element add --type actor --path "System/User" --name "AdminUser"
+
+# View element details (supports JSON, CSV, table output)
+rhapsody-cli element view --path "Sensors/TemperatureSensor" --output json
+
+# Query elements with pattern matching
+rhapsody-cli element query "Sensor*" --output table
+rhapsody-cli element query --path "Sensors" --recursive
+
+# Delete elements with safety confirmation
+rhapsody-cli element delete "Sensors/OldSensor"
+```
+
+#### Project Management
+
+```bash
+# Create a new project
+rhapsody-cli project create --location "C:\Models" --name "NewProject"
+
+# Open existing project
+rhapsody-cli project open --file "C:\Models\MyProject.rpy"
+
+# Attach to active project in running Rhapsody
+rhapsody-cli project attach
+```
+
+#### I/O Operations
+
+```bash
+# Export model to various formats
+rhapsody-cli io export --format json --output model.json
+
+# Import model data
+rhapsody-cli io import --file import_data.json
+```
+
+### Global Options
+
+```bash
+# Enable verbose logging
+rhapsody-cli --verbose element query
+
+# Specify output format
+rhapsody-cli --output json element view --path " MyClass"
+```
+
+### Multi-Instance Support
+
+```python
+from rhapsody_cli import RhapsodyApplication
+
+# Manage multiple simultaneous Rhapsody instances
+app1 = RhapsodyApplication.attach()  # Attach to first instance
+app2 = RhapsodyApplication.launch()  # Launch second instance
+
+project1 = app1.open_project("project1.rpy")
+project2 = app2.open_project("project2.rpy")
+
+# Each instance operates independently
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all unit tests (554 tests, no Rhapsody installation required)
+pytest tests/unit
+
+# Run with coverage
+pytest --cov=rhapsody_cli --cov-report=html
+
+# Run integration tests (requires running Rhapsody with open project)
+pytest tests/integration
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint code
+ruff check src/ tests/
+
+# Type check
+mypy src/ tests/
+
+# All checks in one
+pytest && ruff check src/ tests/ && black --check src/ tests/ && mypy src/ tests/
+```
+
+### Test Coverage
+
+- **554 unit tests** covering all wrapped methods and edge cases
+- **Mocked COM objects** (`tests/fakes.py`) - no Rhapsody installation required
+- **Integration tests** for real COM automation verification
+- **Branch coverage** tracking with 80% minimum threshold
+
+## Architecture
+
+### Core Design
+
+The package follows a systematic wrapping pattern:
+
+1. **Connection Layer**: `RhapsodyApplication` manages COM connections
+2. **Wrapping Pattern**: Each wrapper stores `_com` and delegates all calls
+3. **Type Registry**: Central registry maps Rhapsody types to Python wrappers
+4. **Automatic Fallback**: Unknown types fall back to generic `RPModelElement`
+5. **Collection Wrapping**: `RPCollection` provides Pythonic iteration
+
+### Class Hierarchy
+
+Mirrors the Rhapsody Java API hierarchy:
+
+```
+RPModelElement (wraps IRPModelElement - base for all model elements)
+└─ RPUnit (wraps IRPUnit - elements that can be saved as files)
+   ├─ RPProject (wraps IRPProject)
+   ├─ RPPackage (wraps IRPPackage)
+   ├─ RPClassifier (wraps IRPClassifier)
+   │  ├─ RPClass (wraps IRPClass)
+   │  ├─ RPActor (wraps IRPActor)
+   │  ├─ RPUseCase (wraps IRPUseCase)
+   │  └─ ... (15+ classifier types)
+   └─ ... (50+ total wrapped element types)
+```
+
+### Adding New Element Types
+
+Supporting new Rhapsody element types is mechanical:
+
+1. Define a wrapper class inheriting from the appropriate base
+2. Implement methods delegating to `self._com`
+3. Register in the type registry with `register_wrapper()`
+4. Add unit tests following the established pattern
+
+## Documentation
+
+### Building Documentation Locally
+
+The project uses **Sphinx** with the **ReadTheDocs theme** to generate comprehensive documentation including API reference, user guides, and examples.
+
+#### Install Documentation Dependencies
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+This installs:
+- `sphinx>=4.0.0` - Documentation generator
+- `sphinx-rtd-theme>=1.0.0` - ReadTheDocs theme
+- `myst-parser>=0.18.0` - Markdown support for Sphinx
+
+#### Generate HTML Documentation
+
+```bash
+# Navigate to docs directory
+cd docs
+
+# Build HTML documentation
+make html
+
+# On Windows (PowerShell)
+.\make.bat html
+```
+
+The generated documentation will be in `docs/_build/html/`.
+
+#### View Documentation Locally
+
+```bash
+# Open the main documentation page
+start docs/_build/html/index.html        # Windows
+open docs/_build/html/index.html         # macOS
+xdg-open docs/_build/html/index.html     # Linux
+```
+
+#### Alternative Build Formats
+
+```bash
+# Build PDF documentation (requires LaTeX)
+make latexpdf
+
+# Build coverage report (checks documentation coverage)
+make coverage
+
+# View all available build formats
+make help
+```
+
+#### Documentation Structure
+
+- **Design Document**: `docs/superpowers/specs/2026-07-06-rhapsody-cli-com-api-design.md`
+- **API Reference**: `docs/api/` - auto-generated from docstrings using Sphinx autodoc
+- **User Guide**: `docs/user_guide/` - comprehensive usage tutorials
+- **Examples**: `docs/examples/` - advanced workflow examples
+- **Code Guidelines**: `docs/CODE_GUIDELINES.md` - development standards
+
+#### Deploying to ReadTheDocs
+
+To deploy documentation to [ReadTheDocs.io](https://readthedocs.io):
+
+1. **Create ReadTheDocs Project**: Import your GitHub repository at https://readthedocs.io
+2. **Configure Build Settings**:
+   - Python interpreter: Python 3.x
+   - Requirements file: `docs/requirements.txt`
+   - Configuration file: `docs/conf.py`
+3. **Enable Auto-Build**: ReadTheDocs automatically rebuilds on every push to main branch
+4. **Access Online Docs**: Your documentation will be available at `https://rhapsody-cli.readthedocs.io`
+
+#### Sphinx Configuration Features
+
+The `docs/conf.py` configuration includes:
+- **Autodoc extension**: Automatically generates API docs from Python docstrings
+- **Napoleon extension**: Parses Google-style and NumPy-style docstrings
+- **Myst parser**: Enables Markdown support alongside reStructuredText
+- **Intersphinx**: Links to Python standard library documentation
+- **Coverage checking**: Validates all modules are documented
+- **Type hints**: Displays type annotations in documentation
+
+## Supported Rhapsody Elements
+
+The package currently wraps **50+ element types** including:
+
+**Containment Elements**: Project, Package, Profile, Module, Configuration, Node, Component, ComponentInstance, Collaboration
+
+**Classifier Elements**: Class, Actor, UseCase, InterfaceItem, Stereotype, Statechart, Operation, AssociationClass
+
+**Relation Elements**: Relation, Instance, Dependency, Generalization, Hyperlink, AssociationRole
+
+**Leaf Elements**: Attribute, Tag, Requirement, Variable, Annotation, Constraint, EnumerationLiteral, Diagram, Comment
+
+Plus **hundreds of generic methods** from `RPModelElement` available on all element types.
+
+## Contributing
+
+See [Contributing Guide](docs/contributing.rst) for:
+
+- Code style guidelines
+- Test requirements
+- Documentation standards
+- Pull request process
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### v0.1.0 (2026-07-09)
+
+- Initial release with 50+ wrapped Rhapsody element types
+- Complete CLI tools for element, project, and I/O operations
+- Multi-level path navigation with `/` and `\` separator support
+- Comprehensive test suite (554 unit tests) with mocked COM objects
+- Strict type checking with mypy
+- Sphinx documentation with API reference and user guides
+
+## Limitations
+
+- **Windows-only**: Rhapsody COM automation is Windows-only
+- **Requires Rhapsody License**: Actual COM calls require licensed Rhapsody installation
+- **Not all 160+ interfaces**: Core ~50 types wrapped; others fall back to generic wrapper
+- **No Design Manager**: Deprecated Design Manager features not supported
+
+## Comparison with Rhapsody Java API
+
+| Aspect | Java API | rhapsody-cli |
+|--------|----------|--------------|
+| Method Names | `getName()` | `get_name()` ✓ |
+| Class Hierarchy | `IRPClass extends IRPClassifier` | `RPClass(RPClassifier)` ✓ |
+| Collections | `IRPCollection` | `RPCollection` ✓ |
+| Error Handling | COM errors | `RhapsodyRuntimeException` ✓ |
+| Type Safety | Checked at compile | mypy strict mode ✓ |
+| Testing | Requires Rhapsody | Mocked COM objects ✓ |
+
+## Support
+
+- **Issues**: GitHub Issues for bug reports and feature requests
+- **Documentation**: Full API docs at `docs/api/` and user guide at `docs/user_guide/`
+- **Examples**: Advanced usage patterns in `docs/examples/`