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

Simple index Newer version available

Flotilla's VM core (formerly mgf-vm-core) — pure VM-domain library: state machine, VmSpec, contracts, fakes. The stable core of the Flotilla VM manager.

author Bassam Alsanie, flotilla-core 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 :: Software Development :: Libraries
  • 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-core
requires_dist
  • mgf-common<1.0,>=0.41
  • pydantic<3,>=2.6
  • pyyaml<7,>=6.0
  • 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-pyyaml<7,>=6.0; 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_core-0.2.0-py3-none-any.whl
Size
224 KB
Type
Python Wheel
Python
3
flotilla_core-0.2.0.tar.gz
Size
379 KB
Type
Source

flotilla-core

Formerly flotilla-core — renamed under the Flotilla product name (D25). The old distribution name and import path (mgf.flotilla.core) keep working through the flotilla-core compat distribution, with one DeprecationWarning, until flotilla-core 0.4.0; see CHANGELOG.md 0.2.0.

The pure VM-domain library for the Magogi Foundation distributed vm-vmanager-app. State machine, engine-neutral VmSpec, the three Protocol contracts, the shipped fakes, the conformance suite. No engine deps — no libvirt, no Firecracker, no mgf-hrb.

The stable core that every adapter implements for and every client depends on.

Field Value
Status Pre-0.1.0. Phase 0 of the vm-vmanager-app roadmap.
Federation sibling. Cornerstone: mgf-common>=0.38,<0.39.
Conformance level. L2 — Standard. Per-rule ledger: docs/inprogress/MGF_STANDARDS_CONFORMANCE.md. Design rationale: STANDARDS_NOTE.md.
License. Apache-2.0.
Python. 3.11 / 3.12 / 3.13.

Where the docs live

Everything load-bearing about this library — what it does, why it exists, what its contracts mean, how it relates to the rest of the system — lives in the dedicated Flotilla docs repo:

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

Specifically:

What Where
End-to-end architecture flotilla-docs/ARCHITECTURE.md
Component inventory + this library's role flotilla-docs/COMPONENTS.md
The decision register (D-B2 = this split) flotilla-docs/DECISIONS.md
The four-Protocol spec — required reading flotilla-docs/component-specs/contracts.md
The roadmap (Phase 0 Stream A = this library) flotilla-docs/ROADMAP.md
The test strategy (mgf.flotilla.core.conformance suite) flotilla-docs/TESTING.md
The dev loop (make dev) flotilla-docs/DEV-LOOP.md
Glossary flotilla-docs/GLOSSARY.md

If you're reading this and you want to implement an adapter, the relevant spec is flotilla-docs/component-specs/contracts.md — read it first. It's the contract.

What this library contains

(Phase 0 — see flotilla-docs/ROADMAP.md.)

src/mgf/flotilla/core/
├── __init__.py        # public re-exports (AP-01)
├── py.typed
├── domain.py          # VmSpec, VmStatus, VmState, IsolationLevel, ID types
├── state_machine.py   # VmLifecycleStateMachine
├── contracts.py       # HypervisorBackend, StorageBackend, DeviceBackend, LifecycleObserver
├── exceptions.py      # VmManagerError taxonomy (D-G3)
├── fakes/             # FakeHypervisorBackend, FakeStorageBackend, FakeDeviceBackend (D-F3)
├── conformance/       # the cross-adapter test suite (TESTING.md Tier 2)
└── testing/           # shared pytest fixtures + helpers

The fakes are first-class shipping artifacts (per D-F3) — used by every downstream library's tests and by the dev loop. They live in the package proper, not in tests/.

The conformance suite is the contract enforced. Every adapter implementation runs it against the real engine on the other side of the boundary. See tests/conformance/ for the runner skeleton and flotilla-docs/component-specs/contracts.md §10 for the catalogue of named scenarios.

What this library does NOT contain

That is the wrap-don't-marry discipline. See D-B2 in flotilla-docs/DECISIONS.md.

Install (consumer)

pip install flotilla-core

Or as an editable install for local development against sibling checkouts:

uv pip install -e ~/PycharmProjects/flotilla-core

Develop

cd ~/PycharmProjects/flotilla-core
uv venv --python 3.12
uv sync --extra dev
uv run pytest -q             # unit
uv run mypy --strict src/    # types
uv run ruff check src tests  # style
uv run lint-imports          # layering (D-H4)

All four gates must be green for any PR (mgf-common standards-default).

For the full system dev loop (this library + adapters + the agent + CP + clients), see flotilla-docs/DEV-LOOP.md.

Federation context

flotilla-core is a federation sibling (per mgf-common's federation strategy). It depends only on mgf-common; it is depended on by every other Flotilla library (flotilla-*, formerly mgf-vm-*) and by every vm-vmanager-* application.

Per federation discipline:

Reporting issues