magogi/prod/: flotilla-libvirt-0.2.0 metadata and description

Simple index

Flotilla's libvirt adapter (formerly mgf-vm-libvirt) — implements flotilla-core's HypervisorBackend and StorageBackend against libvirt / KVM / QEMU.

author Bassam Alsanie, flotilla-libvirt contributors
classifiers
  • Development Status :: 2 - Pre-Alpha
  • Intended Audience :: Developers
  • License :: OSI Approved :: Apache Software 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 flotilla, kvm, libvirt, mgf, qemu, virtualization, vm
license Apache-2.0
license_file
  • LICENSE
  • NOTICE
metadata_version 2.5
project_urls
  • Documentation, https://codeberg.org/magogi-admin/flotilla-docs
  • Source, https://codeberg.org/magogi-admin/flotilla-libvirt
requires_dist
  • defusedxml<0.8,>=0.7
  • flotilla-core<0.3,>=0.2
  • libvirt-python>=9.0
  • mgf-common<1.0,>=0.41
  • hypothesis<7,>=6.100; extra == 'dev'
  • import-linter<3,>=2.0; extra == 'dev'
  • mgf-test-supervisor<0.2,>=0.1.2; extra == 'dev'
  • mypy<2,>=1.10; extra == 'dev'
  • pytest-cov<7,>=5.0; extra == 'dev'
  • pytest-timeout<3,>=2.3; extra == 'dev'
  • pytest<9,>=8.0; extra == 'dev'
  • ruff<0.16,>=0.4; extra == 'dev'
  • types-defusedxml<0.8,>=0.7; extra == 'dev'
  • mgf-common[standards]<1.0,>=0.46; extra == 'standards'
requires_python >=3.11

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

File Tox results History
flotilla_libvirt-0.2.0-py3-none-any.whl
Size
100 KB
Type
Python Wheel
Python
3
flotilla_libvirt-0.2.0.tar.gz
Size
313 KB
Type
Source

flotilla-libvirt

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

Renamed (D25 W3, 0.2.0): this library was mgf-vm-libvirt (import mgf.vm.libvirt). Install flotilla-libvirt and import mgf.flotilla.libvirt. The old distribution name still installs: its 0.2.0 release is a thin alias that warns once and resolves to the same modules, and it is removed at flotilla-libvirt 0.4.0.

Field Value
Status Pre-0.1.0. Phase 0 of the vm-vmanager-app roadmap.
Federation sibling. Depends on mgf-common>=0.41,<1.0 + flotilla-core>=0.2,<0.3.
Conformance level. L2 — Standard. Per-rule ledger: docs/inprogress/MGF_STANDARDS_CONFORMANCE.md.
License. Apache-2.0.
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:

flotilla-docs — ~/PycharmProjects/flotilla-docs/ · Codeberg: flotilla-docs

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

If you're here to use this adapter, you import flotilla-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 flotilla-docs/ROADMAP.md Stream B.)

src/mgf/flotilla/libvirt/
├── __init__.py
├── py.typed
├── adapter.py         # LibvirtAdapter: HypervisorBackend + StorageBackend
├── xml/               # VmSpec ↔ libvirt domain XML translation (contained here)
├── errors.py          # libvirt → flotilla-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 flotilla-core. It MUST pass the mgf.flotilla.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 flotilla-libvirt

Use:

from mgf.flotilla.libvirt import LibvirtAdapter

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

Develop

cd ~/PycharmProjects/flotilla-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 flotilla-docs/DEV-LOOP.md (opt in with LIBVIRT=1).

Federation context

flotilla-libvirt is a federation sibling. Depends on mgf-common (foundation) and flotilla-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