maqet 0.0.1.4__tar.gz → 0.0.5__tar.gz

maqet-0.0.5/LICENSE

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

maqet-0.0.5/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include docs *.md
+recursive-include maqet *.yaml *.yml
+recursive-exclude docs/development *
+recursive-exclude qemu *
+recursive-exclude tests *
+recursive-exclude . __pycache__
+recursive-exclude . *.pyc
+recursive-exclude . *.pyo
+recursive-exclude . *.log
+exclude CLAUDE.md
+exclude test_config.yaml
+exclude main.py
+exclude test.py

maqet-0.0.5/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: maqet
+Version: 0.0.5
+Summary: M4x0n's QEMU Tool - A Python-based QEMU automation framework for VM running
+Author: Max Rogol
+Maintainer: Max Rogol
+License-Expression: MIT
+Project-URL: Repository, https://github.com/m4x0n/maqet
+Project-URL: Documentation, https://github.com/m4x0n/maqet/blob/main/README.md
+Project-URL: Issues, https://github.com/m4x0n/maqet/issues
+Keywords: qemu,virtualization,vm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-benedict>=0.33.2
+Requires-Dist: PyYAML>=6.0.2
+Provides-Extra: qemu
+Requires-Dist: qemu.qmp>=3.0.0; extra == "qemu"
+Provides-Extra: tables
+Requires-Dist: tabulate>=0.9.0; extra == "tables"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-testmon; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tabulate>=0.9.0; extra == "dev"
+Dynamic: license-file
+
+# MAQET
+
+**MAQET** (M4x0n's QEMU Tool) is a VM management system that implements unified API generation. Methods decorated with `@api_method` automatically become CLI commands, Python API methods, and configuration-driven calls.
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install maqet
+```
+
+**Optional Dependencies:**
+
+- `psutil` - Enhanced process management and validation (recommended)
+
+  ```bash
+  pip install psutil
+  ```
+
+  Without psutil, basic PID tracking still works but ownership validation is skipped.
+
+### Core Concept
+
+Write once, use everywhere. A single method becomes a CLI command, Python API, and configuration option:
+
+```python
+@api_method(cli_name="start", description="Start a virtual machine", category="vm")
+def start(self, vm_id: str, detach: bool = False):
+    """Start a virtual machine."""
+    # Single implementation
+```
+
+This automatically creates:
+
+- **CLI**: `maqet start myvm --detach`
+- **Python API**: `maqet.start("myvm", detach=True)`
+- **Config**: VM settings only (no commands in YAML)
+
+## Usage
+
+### Command Line Interface
+
+```bash
+# Create a VM
+maqet add --config config.yaml --name myvm
+
+# Start VM
+maqet start myvm
+
+# List all VMs
+maqet ls
+
+# Check VM status
+maqet status myvm
+
+# Execute QMP command
+maqet qmp myvm system_powerdown
+
+# Remove VM
+maqet rm myvm --force
+```
+
+### Python API
+
+```python
+from maqet import Maqet
+
+maqet = Maqet()
+
+# Create and start VM
+vm_id = maqet.add(name='myvm', memory='4G', cpu=2)
+maqet.start(vm_id)
+
+# Manage VM
+status = maqet.status(vm_id)
+maqet.qmp(vm_id, 'system_powerdown')
+maqet.rm(vm_id, force=True)
+```
+
+### Configuration Files
+
+```yaml
+# config.yaml - VM configuration only
+name: myvm
+binary: /usr/bin/qemu-system-x86_64
+memory: 4G
+cpu: 2
+storage:
+  - name: hdd
+    size: 20G
+    type: qcow2
+    interface: virtio
+```
+
+```bash
+# Use configuration file
+maqet add --config config.yaml
+maqet start myvm --detach
+```
+
+**Configuration Features:**
+
+- Deep-merge multiple config files
+- Lists are concatenated (storage, network)
+- Command-line args override config values
+- Full QEMU argument support
+
+See [Configuration Guide](docs/user-guide/configuration.md) for details.
+
+## Core Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `add` | Create new VM | `maqet add --config config.yaml --name myvm` |
+| `start` | Start VM | `maqet start myvm` |
+| `stop` | Stop VM | `maqet stop myvm --force` |
+| `rm` | Remove VM | `maqet rm myvm --force` |
+| `ls` | List VMs | `maqet ls --status running` |
+| `status` | Show VM status | `maqet status myvm` |
+| `apply` | Apply configuration | `maqet apply myvm --memory 8G` |
+| `snapshot` | Manage snapshots | `maqet snapshot myvm create hdd snap1` |
+
+### QMP Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `qmp keys` | Send key combination | `maqet qmp keys myvm ctrl alt f2` |
+| `qmp type` | Type text to VM | `maqet qmp type myvm "hello world"` |
+| `qmp screendump` | Take screenshot | `maqet qmp screendump myvm screenshot.ppm` |
+| `qmp pause` | Pause VM | `maqet qmp pause myvm` |
+| `qmp resume` | Resume VM | `maqet qmp resume myvm` |
+| `qmp device-add` | Hot-plug device | `maqet qmp device-add myvm usb-storage` |
+| `qmp device-del` | Hot-unplug device | `maqet qmp device-del myvm usb1` |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Increase verbosity (-v, -vv, -vvv) |
+| `-q, --quiet` | Suppress non-error output |
+| `--data-dir` | Override data directory |
+| `--log-file` | Enable file logging |
+
+## Documentation
+
+### Full Documentation
+
+- **[Documentation Index](docs/README.md)** - Complete documentation portal
+- **[Architecture](docs/architecture/)** - Internal architecture and design
+- **[Development](docs/development/)** - Contributing and development guides
+- **[Deployment](docs/deployment/)** - Production deployment
+- **[Reference](docs/reference/)** - Technical references
+
+### Architecture
+
+- **Unified API System** - Single methods generate CLI, Python API, and config
+- **State Management** - SQLite backend with XDG compliance
+- **QEMU Integration** - Full QMP protocol support
+- **Storage System** - QCOW2, Raw, VirtFS support with snapshots
+
+See [QEMU Internal Architecture](docs/architecture/QEMU_INTERNAL_ARCHITECTURE.md) for details.
+
+### Development
+
+```bash
+# Run tests
+python tests/run_tests.py
+
+# Run pre-commit checks
+pre-commit run --all-files
+```
+
+See [Testing Guide](docs/development/TESTING.md) for details on running tests and contributing.
+
+### Roadmap
+
+See [Roadmap](docs/development/ROADMAP.md) and [Future Features](docs/development/FUTURE_FEATURES.md) for planned improvements.
+
+## Features
+
+- **Write Once, Use Everywhere** - Single method for CLI, API, and config
+- **XDG Compliant** - Follows Linux directory standards
+- **Production Ready** - Security hardened, tested, robust error handling
+- **Full QMP Support** - Complete QEMU Machine Protocol integration
+- **Snapshot Management** - Create, load, list, and delete snapshots
+- **Hot-plug Support** - Add/remove devices while VM is running
+
+## Contributing
+
+Contributions welcome! See [Development Guide](docs/development/) for contributing guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

maqet-0.0.5/README.md

@@ -0,0 +1,195 @@
+# MAQET
+
+**MAQET** (M4x0n's QEMU Tool) is a VM management system that implements unified API generation. Methods decorated with `@api_method` automatically become CLI commands, Python API methods, and configuration-driven calls.
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install maqet
+```
+
+**Optional Dependencies:**
+
+- `psutil` - Enhanced process management and validation (recommended)
+
+  ```bash
+  pip install psutil
+  ```
+
+  Without psutil, basic PID tracking still works but ownership validation is skipped.
+
+### Core Concept
+
+Write once, use everywhere. A single method becomes a CLI command, Python API, and configuration option:
+
+```python
+@api_method(cli_name="start", description="Start a virtual machine", category="vm")
+def start(self, vm_id: str, detach: bool = False):
+    """Start a virtual machine."""
+    # Single implementation
+```
+
+This automatically creates:
+
+- **CLI**: `maqet start myvm --detach`
+- **Python API**: `maqet.start("myvm", detach=True)`
+- **Config**: VM settings only (no commands in YAML)
+
+## Usage
+
+### Command Line Interface
+
+```bash
+# Create a VM
+maqet add --config config.yaml --name myvm
+
+# Start VM
+maqet start myvm
+
+# List all VMs
+maqet ls
+
+# Check VM status
+maqet status myvm
+
+# Execute QMP command
+maqet qmp myvm system_powerdown
+
+# Remove VM
+maqet rm myvm --force
+```
+
+### Python API
+
+```python
+from maqet import Maqet
+
+maqet = Maqet()
+
+# Create and start VM
+vm_id = maqet.add(name='myvm', memory='4G', cpu=2)
+maqet.start(vm_id)
+
+# Manage VM
+status = maqet.status(vm_id)
+maqet.qmp(vm_id, 'system_powerdown')
+maqet.rm(vm_id, force=True)
+```
+
+### Configuration Files
+
+```yaml
+# config.yaml - VM configuration only
+name: myvm
+binary: /usr/bin/qemu-system-x86_64
+memory: 4G
+cpu: 2
+storage:
+  - name: hdd
+    size: 20G
+    type: qcow2
+    interface: virtio
+```
+
+```bash
+# Use configuration file
+maqet add --config config.yaml
+maqet start myvm --detach
+```
+
+**Configuration Features:**
+
+- Deep-merge multiple config files
+- Lists are concatenated (storage, network)
+- Command-line args override config values
+- Full QEMU argument support
+
+See [Configuration Guide](docs/user-guide/configuration.md) for details.
+
+## Core Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `add` | Create new VM | `maqet add --config config.yaml --name myvm` |
+| `start` | Start VM | `maqet start myvm` |
+| `stop` | Stop VM | `maqet stop myvm --force` |
+| `rm` | Remove VM | `maqet rm myvm --force` |
+| `ls` | List VMs | `maqet ls --status running` |
+| `status` | Show VM status | `maqet status myvm` |
+| `apply` | Apply configuration | `maqet apply myvm --memory 8G` |
+| `snapshot` | Manage snapshots | `maqet snapshot myvm create hdd snap1` |
+
+### QMP Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `qmp keys` | Send key combination | `maqet qmp keys myvm ctrl alt f2` |
+| `qmp type` | Type text to VM | `maqet qmp type myvm "hello world"` |
+| `qmp screendump` | Take screenshot | `maqet qmp screendump myvm screenshot.ppm` |
+| `qmp pause` | Pause VM | `maqet qmp pause myvm` |
+| `qmp resume` | Resume VM | `maqet qmp resume myvm` |
+| `qmp device-add` | Hot-plug device | `maqet qmp device-add myvm usb-storage` |
+| `qmp device-del` | Hot-unplug device | `maqet qmp device-del myvm usb1` |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Increase verbosity (-v, -vv, -vvv) |
+| `-q, --quiet` | Suppress non-error output |
+| `--data-dir` | Override data directory |
+| `--log-file` | Enable file logging |
+
+## Documentation
+
+### Full Documentation
+
+- **[Documentation Index](docs/README.md)** - Complete documentation portal
+- **[Architecture](docs/architecture/)** - Internal architecture and design
+- **[Development](docs/development/)** - Contributing and development guides
+- **[Deployment](docs/deployment/)** - Production deployment
+- **[Reference](docs/reference/)** - Technical references
+
+### Architecture
+
+- **Unified API System** - Single methods generate CLI, Python API, and config
+- **State Management** - SQLite backend with XDG compliance
+- **QEMU Integration** - Full QMP protocol support
+- **Storage System** - QCOW2, Raw, VirtFS support with snapshots
+
+See [QEMU Internal Architecture](docs/architecture/QEMU_INTERNAL_ARCHITECTURE.md) for details.
+
+### Development
+
+```bash
+# Run tests
+python tests/run_tests.py
+
+# Run pre-commit checks
+pre-commit run --all-files
+```
+
+See [Testing Guide](docs/development/TESTING.md) for details on running tests and contributing.
+
+### Roadmap
+
+See [Roadmap](docs/development/ROADMAP.md) and [Future Features](docs/development/FUTURE_FEATURES.md) for planned improvements.
+
+## Features
+
+- **Write Once, Use Everywhere** - Single method for CLI, API, and config
+- **XDG Compliant** - Follows Linux directory standards
+- **Production Ready** - Security hardened, tested, robust error handling
+- **Full QMP Support** - Complete QEMU Machine Protocol integration
+- **Snapshot Management** - Create, load, list, and delete snapshots
+- **Hot-plug Support** - Add/remove devices while VM is running
+
+## Contributing
+
+Contributions welcome! See [Development Guide](docs/development/) for contributing guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

maqet-0.0.5/docs/README.md

@@ -0,0 +1,81 @@
+# MAQET Documentation
+
+This directory contains comprehensive documentation for the MAQET project, organized by topic and purpose.
+
+## Quick Navigation
+
+### For Users
+
+- [User Guide](user-guide/) - Installation, configuration, and usage instructions
+- [API Reference](api/) - Python API documentation
+
+### For Developers
+
+- [Development Guide](../CLAUDE.md) - Claude Code instructions, coding standards
+- [Testing Guide](development/TESTING.md) - How to run and write tests
+- [Architecture Documentation](architecture/) - System design and decisions
+
+### For Architecture Review
+
+- [Architecture Audit Report](architecture/ARCHITECTURE_AUDIT_REPORT.md) - Comprehensive Phase 5 review
+- [Architectural Decisions](architecture/ARCHITECTURAL_DECISIONS.md) - 23 key design decisions
+- [Per-VM Process Architecture](architecture/PER_VM_PROCESS_ARCHITECTURE.md) - Core architecture specification
+
+## Directory Structure
+
+```
+docs/
+├── README.md                    (this file)
+├── architecture/                Architecture specifications and design docs
+│   ├── ARCHITECTURAL_DECISIONS.md
+│   ├── ARCHITECTURAL_REVIEW.md
+│   ├── ARCHITECTURE_AUDIT_REPORT.md
+│   ├── DAEMON_ARCHITECTURE_RESEARCH.md
+│   ├── PERSISTENT_QEMUMACHINE_ARCHITECTURE.md
+│   └── PER_VM_PROCESS_ARCHITECTURE.md
+├── development/                 Development process and implementation docs
+│   ├── phases/                  Phase implementation summaries
+│   └── reports/                 Technical reports and fixes
+├── deployment/                  Deployment guides
+├── user-guide/                  End-user documentation
+├── reference/                   API and CLI reference
+└── api/                        Generated API documentation
+
+../                              (Repository root)
+├── README.md                    Project overview and quick start
+└── CLAUDE.md                   Development guide for Claude Code
+```
+
+## Document Categories
+
+### Architecture (architecture/)
+
+Core system design documents - specification, decisions, audit results
+
+### Development Phases (development/phases/)
+
+Phase-by-phase implementation summaries
+
+### Technical Reports (development/reports/)
+
+Specific fixes, cleanups, and technical investigations
+
+## Key Documents by Purpose
+
+### Understanding the Architecture
+
+1. Start with [PER_VM_PROCESS_ARCHITECTURE.md](architecture/PER_VM_PROCESS_ARCHITECTURE.md)
+2. Review [ARCHITECTURAL_DECISIONS.md](architecture/ARCHITECTURAL_DECISIONS.md)
+3. Check [ARCHITECTURE_AUDIT_REPORT.md](architecture/ARCHITECTURE_AUDIT_REPORT.md) for implementation status
+
+### Contributing to Development
+
+1. Read [CLAUDE.md](../CLAUDE.md) for development guidelines
+2. Check [TESTING.md](development/TESTING.md) for testing procedures
+3. Review relevant phase documents for context
+
+### Debugging Issues
+
+1. Check [CODE_ISSUES_REPORT.md](development/reports/CODE_ISSUES_REPORT.md)
+2. Review specific fix reports
+3. Consult [CLAUDE.md](../CLAUDE.md) troubleshooting section