| Name | maqet JSON |
| Version |
0.0.11
JSON |
| download |
| home_page | None |
| Summary | M4x0n's QEMU Tool - A Python-based QEMU automation framework for VM running |
| upload_time | 2025-10-14 20:45:13 |
| maintainer | Max Rogol |
| docs_url | None |
| author | Max Rogol |
| requires_python | >=3.12 |
| license | None |
| keywords |
qemu
virtualization
vm
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MAQET
**Warning:** Most of the code was written using AI. This product is a work in progress and should not be used in production environments under any circumstances.
**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
GNU General Public License v2.0 - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "maqet",
"maintainer": "Max Rogol",
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "qemu, virtualization, vm",
"author": "Max Rogol",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b0/3b/0e114d8c2d28301bafff7d42a60ccd2c42a8348d16dc55710586c095c777/maqet-0.0.11.tar.gz",
"platform": null,
"description": "# MAQET\n\n**Warning:** Most of the code was written using AI. This product is a work in progress and should not be used in production environments under any circumstances.\n\n**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.\n\n## Quick Start\n\n### Installation\n\n```bash\npip install maqet\n```\n\n**Optional Dependencies:**\n\n- `psutil` - Enhanced process management and validation (recommended)\n\n ```bash\n pip install psutil\n ```\n\n Without psutil, basic PID tracking still works but ownership validation is skipped.\n\n### Core Concept\n\nWrite once, use everywhere. A single method becomes a CLI command, Python API, and configuration option:\n\n```python\n@api_method(cli_name=\"start\", description=\"Start a virtual machine\", category=\"vm\")\ndef start(self, vm_id: str, detach: bool = False):\n \"\"\"Start a virtual machine.\"\"\"\n # Single implementation\n```\n\nThis automatically creates:\n\n- **CLI**: `maqet start myvm --detach`\n- **Python API**: `maqet.start(\"myvm\", detach=True)`\n- **Config**: VM settings only (no commands in YAML)\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Create a VM\nmaqet add --config config.yaml --name myvm\n\n# Start VM\nmaqet start myvm\n\n# List all VMs\nmaqet ls\n\n# Check VM status\nmaqet status myvm\n\n# Execute QMP command\nmaqet qmp myvm system_powerdown\n\n# Remove VM\nmaqet rm myvm --force\n```\n\n### Python API\n\n```python\nfrom maqet import Maqet\n\nmaqet = Maqet()\n\n# Create and start VM\nvm_id = maqet.add(name='myvm', memory='4G', cpu=2)\nmaqet.start(vm_id)\n\n# Manage VM\nstatus = maqet.status(vm_id)\nmaqet.qmp(vm_id, 'system_powerdown')\nmaqet.rm(vm_id, force=True)\n```\n\n### Configuration Files\n\n```yaml\n# config.yaml - VM configuration only\nname: myvm\nbinary: /usr/bin/qemu-system-x86_64\nmemory: 4G\ncpu: 2\nstorage:\n - name: hdd\n size: 20G\n type: qcow2\n interface: virtio\n```\n\n```bash\n# Use configuration file\nmaqet add --config config.yaml\nmaqet start myvm --detach\n```\n\n**Configuration Features:**\n\n- Deep-merge multiple config files\n- Lists are concatenated (storage, network)\n- Command-line args override config values\n- Full QEMU argument support\n\nSee [Configuration Guide](docs/user-guide/configuration.md) for details.\n\n## Core Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `add` | Create new VM | `maqet add --config config.yaml --name myvm` |\n| `start` | Start VM | `maqet start myvm` |\n| `stop` | Stop VM | `maqet stop myvm --force` |\n| `rm` | Remove VM | `maqet rm myvm --force` |\n| `ls` | List VMs | `maqet ls --status running` |\n| `status` | Show VM status | `maqet status myvm` |\n| `apply` | Apply configuration | `maqet apply myvm --memory 8G` |\n| `snapshot` | Manage snapshots | `maqet snapshot myvm create hdd snap1` |\n\n### QMP Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `qmp keys` | Send key combination | `maqet qmp keys myvm ctrl alt f2` |\n| `qmp type` | Type text to VM | `maqet qmp type myvm \"hello world\"` |\n| `qmp screendump` | Take screenshot | `maqet qmp screendump myvm screenshot.ppm` |\n| `qmp pause` | Pause VM | `maqet qmp pause myvm` |\n| `qmp resume` | Resume VM | `maqet qmp resume myvm` |\n| `qmp device-add` | Hot-plug device | `maqet qmp device-add myvm usb-storage` |\n| `qmp device-del` | Hot-unplug device | `maqet qmp device-del myvm usb1` |\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `-v, --verbose` | Increase verbosity (-v, -vv, -vvv) |\n| `-q, --quiet` | Suppress non-error output |\n| `--data-dir` | Override data directory |\n| `--log-file` | Enable file logging |\n\n## Documentation\n\n### Full Documentation\n\n- **[Documentation Index](docs/README.md)** - Complete documentation portal\n- **[Architecture](docs/architecture/)** - Internal architecture and design\n- **[Development](docs/development/)** - Contributing and development guides\n- **[Deployment](docs/deployment/)** - Production deployment\n- **[Reference](docs/reference/)** - Technical references\n\n### Architecture\n\n- **Unified API System** - Single methods generate CLI, Python API, and config\n- **State Management** - SQLite backend with XDG compliance\n- **QEMU Integration** - Full QMP protocol support\n- **Storage System** - QCOW2, Raw, VirtFS support with snapshots\n\nSee [QEMU Internal Architecture](docs/architecture/QEMU_INTERNAL_ARCHITECTURE.md) for details.\n\n### Development\n\n```bash\n# Run tests\npython tests/run_tests.py\n\n# Run pre-commit checks\npre-commit run --all-files\n```\n\nSee [Testing Guide](docs/development/TESTING.md) for details on running tests and contributing.\n\n### Roadmap\n\nSee [Roadmap](docs/development/ROADMAP.md) and [Future Features](docs/development/FUTURE_FEATURES.md) for planned improvements.\n\n## Features\n\n- **Write Once, Use Everywhere** - Single method for CLI, API, and config\n- **XDG Compliant** - Follows Linux directory standards\n- **Production Ready** - Security hardened, tested, robust error handling\n- **Full QMP Support** - Complete QEMU Machine Protocol integration\n- **Snapshot Management** - Create, load, list, and delete snapshots\n- **Hot-plug Support** - Add/remove devices while VM is running\n\n## Contributing\n\nContributions welcome! See [Development Guide](docs/development/) for contributing guidelines.\n\n## License\n\nGNU General Public License v2.0 - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "M4x0n's QEMU Tool - A Python-based QEMU automation framework for VM running",
"version": "0.0.11",
"project_urls": {
"Documentation": "https://gitlab.com/m4x0n_24/maqet/blob/main/README.md",
"Issues": "https://gitlab.com/m4x0n_24/maqet/issues",
"Repository": "https://gitlab.com/m4x0n_24/maqet"
},
"split_keywords": [
"qemu",
" virtualization",
" vm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c8ed07e30d84ae0dbe829bd79673e8d67c4ce03d3c8f04d6695e1602ee49a89b",
"md5": "b002babc8dd22fef72246dd55e7848fa",
"sha256": "ffb0eec2803c65228db96ce03d9b1c645bbb2cce5e878997b02f227e28c33feb"
},
"downloads": -1,
"filename": "maqet-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b002babc8dd22fef72246dd55e7848fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 202472,
"upload_time": "2025-10-14T20:45:10",
"upload_time_iso_8601": "2025-10-14T20:45:10.355779Z",
"url": "https://files.pythonhosted.org/packages/c8/ed/07e30d84ae0dbe829bd79673e8d67c4ce03d3c8f04d6695e1602ee49a89b/maqet-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b03b0e114d8c2d28301bafff7d42a60ccd2c42a8348d16dc55710586c095c777",
"md5": "2a41d5932a1f62cf36ccae62b7cbdfdc",
"sha256": "530c80c463e4babbb0eadf5a4468f44259044f89701ea4d59b3a1f1cfa9f15af"
},
"downloads": -1,
"filename": "maqet-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "2a41d5932a1f62cf36ccae62b7cbdfdc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 318446,
"upload_time": "2025-10-14T20:45:13",
"upload_time_iso_8601": "2025-10-14T20:45:13.731151Z",
"url": "https://files.pythonhosted.org/packages/b0/3b/0e114d8c2d28301bafff7d42a60ccd2c42a8348d16dc55710586c095c777/maqet-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 20:45:13",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "m4x0n_24",
"gitlab_project": "maqet",
"lcname": "maqet"
}
