# Public API — `mgf-vm-interchange`

> ⚠️ **This file documents `main` HEAD.** Names listed here may be
> unreleased. To learn what your installed wheel actually ships, run
> `pip show mgf-vm-interchange` and compare against the `__version__`
> field at the top of `PUBLIC_API.json`. The git tag matching the
> published version is authoritative.

This document is the **contract list** for `mgf-vm-interchange`. Every
name listed below is a public name that consumers MAY depend on. The
contract terms are defined in
[`mgf-common`'s `docs/standards/API_DESIGN.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/API_DESIGN.md).
In short:

- **Stability tiers:**
  - `experimental` — MAY change shape in any MINOR release (the 0.x
    window keeps everything experimental in practice).
  - `stable` — follows the deprecation cycle; removal only in MAJOR.
  - `deprecated` — slated for removal; emits `DeprecationWarning`.
- **Names not listed below are private.** Anything underscore-prefixed
  is internal and MAY change without notice.
- **The 0.x window applies** (AP-03): per SemVer 0.x semantics, MINOR
  releases MAY break the public API. Pin tightly:
  `mgf-vm-interchange = ">=0.1,<0.2"`.

The machine-readable companion is
[`PUBLIC_API.json`](PUBLIC_API.json) (rule AP-10 / DOC-08), generated
by [`tools/generate_public_api_json.py`](tools/generate_public_api_json.py)
and pinned against this file + `__all__` by
`tests/unit/test_public_api_pin.py`.

---

## `mgf.vm.interchange`

The package facade — the one-stop import surface. Re-exports the
seven names below from the submodules.

| Name | Tier | Description |
|---|---|---|
| `import_ova` | **experimental** (v0.1.0) | Import an OVA archive and define a new VM on the given provider. See `mgf.vm.interchange.importer`. |
| `export_ova` | **experimental** (v0.1.0) | Pack a VM into an OVA archive. See `mgf.vm.interchange.exporter`. |
| `parse_ovf` | **experimental** (v0.1.0) | Parse OVF XML (string or file path) into an `OVFDescriptor`. See `mgf.vm.interchange.ovf`. |
| `serialize_ovf` | **experimental** (v0.1.0) | Render an `OVFDescriptor` to OVF XML. See `mgf.vm.interchange.ovf`. |
| `OVFDescriptor` | **experimental** (v0.1.0) | Parsed / to-be-written OVF descriptor (name, OS, vCPU, memory, disks, NICs, networks). |
| `OVFDisk` | **experimental** (v0.1.0) | One disk referenced from the OVF descriptor. |
| `OVFNIC` | **experimental** (v0.1.0) | One network interface described in the OVF. |

## `mgf.vm.interchange.ovf`

OVF descriptor parser and writer, plus the typed data model and the
DMTF namespace / CIM resource-type constants.

| Name | Tier | Description |
|---|---|---|
| `parse_ovf` | **experimental** (v0.1.0) | Parse OVF XML from a string or file path; raises `ImportExportError` on any structural problem. Untrusted input is routed through `defusedxml` (DTD ban + size cap). |
| `serialize_ovf` | **experimental** (v0.1.0) | Render an `OVFDescriptor` to a pretty-printed OVF XML string accepted by `virt-v2v` / `ovftool` / VirtualBox. |
| `OVFDescriptor` | **experimental** (v0.1.0) | Frozen-ish dataclass of the descriptor fields; all numeric fields are native types. |
| `OVFDisk` | **experimental** (v0.1.0) | Disk record: `disk_id`, `file_ref`, `file_href`, `capacity_bytes`, `format_uri`. |
| `OVFNIC` | **experimental** (v0.1.0) | NIC record: `name`, `model`, `connection`. |
| `NSMAP` | **experimental** (v0.1.0) | Prefix→URI map for the OVF / RASD / VSSD / XSI namespaces used on serialization. |
| `OVF_NS` | **experimental** (v0.1.0) | The DMTF OVF envelope namespace URI. |
| `RASD_NS` | **experimental** (v0.1.0) | The CIM ResourceAllocationSettingData namespace URI. |
| `VSSD_NS` | **experimental** (v0.1.0) | The CIM VirtualSystemSettingData namespace URI. |
| `RESOURCE_TYPE_CPU` | **experimental** (v0.1.0) | CIM ResourceType value for CPU (3). |
| `RESOURCE_TYPE_MEMORY` | **experimental** (v0.1.0) | CIM ResourceType value for memory (4). |
| `RESOURCE_TYPE_ETHERNET` | **experimental** (v0.1.0) | CIM ResourceType value for an Ethernet adapter (10). |
| `RESOURCE_TYPE_DISK` | **experimental** (v0.1.0) | CIM ResourceType value for a disk (17). |

## `mgf.vm.interchange.importer`

OVA → libvirt-domain import pipeline.

| Name | Tier | Description |
|---|---|---|
| `import_ova` | **experimental** (v0.1.0) | Open an OVA, parse its OVF, safely extract + convert each disk (zip-slip / symlink rejected via `mgf.vm.common.safe_tar`), build minimal domain XML, and call `provider.define_domain`. Returns `ImportResult`. Wrapped in an `ova.import` OTel span. |
| `build_domain_xml` | **experimental** (v0.1.0) | Build a minimal libvirt domain XML from an `OVFDescriptor` + converted disk paths (virtio everything; defaults floor memory at 64 MiB). |
| `ImportResult` | **experimental** (v0.1.0) | Summary of a successful import: `handle`, `descriptor`, `converted_disks`. |

## `mgf.vm.interchange.exporter`

libvirt-domain → OVA export pipeline.

| Name | Tier | Description |
|---|---|---|
| `export_ova` | **experimental** (v0.1.0) | Read the domain XML (parsed `untrusted=True`), convert each qcow2 disk to streamOptimized vmdk, render the OVF, and pack a POSIX tar OVA. Refuses to overwrite an existing destination. Returns `ExportResult`. Wrapped in an `ova.export` OTel span. |
| `ExportResult` | **experimental** (v0.1.0) | Summary of a successful export: `destination`, `descriptor`, `exported_disks`. |
