magogi/prod/: mgf-vm-libvirt-0.1.5 metadata and description

Simple index Newer version available

Magogi Foundation libvirt adapter — implements mgf-vm-core's HypervisorBackend and StorageBackend against libvirt / KVM / QEMU.

author Bassam Alsanie, mgf-vm-libvirt contributors
classifiers
  • Development Status :: 2 - Pre-Alpha
  • Intended Audience :: Developers
  • License :: OSI Approved :: MIT License
  • Operating System :: POSIX :: Linux
  • Programming Language :: Python :: 3
  • Programming Language :: Python :: 3.11
  • Programming Language :: Python :: 3.12
  • Programming Language :: Python :: 3.13
  • Topic :: System :: Emulators
description_content_type text/markdown
keywords kvm, libvirt, mgf, qemu, virtualization, vm
license MIT
license_file
  • LICENSE
metadata_version 2.4
project_urls
  • Documentation, https://codeberg.org/magogi-admin/vm-vmanager-docs
  • Source, https://codeberg.org/magogi-admin/mgf-vm-libvirt
requires_dist
  • defusedxml<0.8,>=0.7
  • libvirt-python>=9.0
  • mgf-common<0.46,>=0.41
  • mgf-vm-core<0.2,>=0.1.5
  • hypothesis<7,>=6.100; extra == 'dev'
  • import-linter<3,>=2.0; extra == 'dev'
  • mypy<2,>=1.10; extra == 'dev'
  • pytest-cov<7,>=5.0; extra == 'dev'
  • pytest<9,>=8.0; extra == 'dev'
  • ruff<1,>=0.4; extra == 'dev'
  • types-defusedxml<0.8,>=0.7; extra == 'dev'
requires_python >=3.11

Because this project isn't in the mirror_whitelist, no releases from root/pypi are included.

File Tox results History
mgf_vm_libvirt-0.1.5-py3-none-any.whl
Size
74 KB
Type
Python Wheel
Python
3

mgf-vm-libvirt

The libvirt adapter for the Magogi Foundation distributed vm-vmanager-app. Implements mgf-vm-core's HypervisorBackend and StorageBackend Protocols against libvirt / KVM / QEMU. The wrap (not marry) of libvirt.

Field Value
Status Pre-0.1.0. Phase 0 of the vm-vmanager-app roadmap.
Federation sibling. Depends on mgf-common>=0.38,<0.39 + mgf-vm-core>=0.1,<0.2.
Conformance level. L2 — Standard. Per-rule ledger: docs/inprogress/MGF_STANDARDS_CONFORMANCE.md.
License. MIT.
Python. 3.11 / 3.12 / 3.13.
System dep. python3-libvirt from apt (ABI-matched to host libvirtd).

Where the docs live

Everything load-bearing — what this adapter does, why it exists, what its conformance obligations are — lives in the central docs:

vm-vmanager-docs — ~/PycharmProjects/vm-vmanager-docs/ · Codeberg: vm-vmanager-docs

What Where
End-to-end architecture vm-vmanager-docs/ARCHITECTURE.md
The contracts this adapter implements vm-vmanager-docs/component-specs/contracts.md — §3 (Hypervisor), §4 (Storage)
Decision register (D-B2 = the split; D-F4 = storage separability) vm-vmanager-docs/DECISIONS.md
Roadmap (Phase 0 Stream B) vm-vmanager-docs/ROADMAP.md
Test strategy + integration tier vm-vmanager-docs/TESTING.md
Dev loop (LIBVIRT=1 opt-in) vm-vmanager-docs/DEV-LOOP.md

If you're here to use this adapter, you import mgf-vm-core's contracts and instantiate this adapter against them. If you're here to extend this adapter, the spec is contracts.md — that is the contract.

What this library contains

(Phase 0 — see vm-vmanager-docs/ROADMAP.md Stream B.)

src/mgf/vm/libvirt/
├── __init__.py
├── py.typed
├── adapter.py         # LibvirtAdapter: HypervisorBackend + StorageBackend
├── xml/               # VmSpec ↔ libvirt domain XML translation (contained here)
├── errors.py          # libvirt → mgf-vm-core exceptions translation (EH-02)
└── _internal/         # private helpers; not importable by consumers

Containment principle. Libvirt's sprawling domain XML and its thin Python binding ergonomics stay in this library. They never leak above the adapter. Anything you see in xml/ and the libvirt-python import sites is the price; everything else above this adapter — vm-core, the SDK, the clients — sees clean typed Python.

The adapter's surface is exactly the union of HypervisorBackend + StorageBackend from mgf-vm-core. It MUST pass the mgf.vm.core.conformance suite against a real libvirtd. See tests/integration/ for the runner.

Install (consumer)

sudo apt install python3-libvirt libvirt-daemon-system   # the system binding + daemon
pip install mgf-vm-libvirt

Use:

from mgf.vm.libvirt import LibvirtAdapter

adapter = LibvirtAdapter("qemu:///system")
domain_id = adapter.define(spec)
adapter.start(domain_id)

Develop

cd ~/PycharmProjects/mgf_vm_libvirt
uv venv --python 3.12 --system-site-packages         # pick up python3-libvirt
uv sync --extra dev
uv run pytest -q -m "not integration"                # unit only
uv run pytest -q -m integration                       # vs containerized libvirtd
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports

For the integration tier you'll need Docker (for the libvirtd container). The fixtures live in tests/integration/conftest.py.

For the full system dev loop, see vm-vmanager-docs/DEV-LOOP.md (opt in with LIBVIRT=1).

Federation context

mgf-vm-libvirt is a federation sibling. Depends on mgf-common (foundation) and mgf-vm-core (the contracts). Depended on by vm-vmanager-agent (which composes it with the mgf-hrb client to form the per-host kernel).

Per federation discipline:

Reporting issues