"""A hypervisor says which cluster it belongs to, and what that cluster holds. A Proxmox node is one member of a cluster and can read the whole of it; a vCenter manages several clusters and standalone hosts at once; a standalone host is a cluster of one. One getter serves all three: ``get_clusters()`` lists every cluster the connection can see, each with its nodes, its storages and its networks, and which nodes see which. What a caller does with that (placement, headroom, identity) is the caller's. A new VM can be placed on a named node (``create_vm_from_cloud_init(node=…)``), so a manager that runs several hosts takes the caller's choice instead of making its own. The declarations sit under ``TYPE_CHECKING`` (see test_role_contracts), so the signatures are read from the source rather than from the class. """ from __future__ import annotations import ast import inspect from typing import NotRequired, get_type_hints import napalm_device_types.hypervisor as hypervisor_module from napalm_device_types import ( BackupDict, BackupJobDict, BackupServerRefDict, ClusterDict, ClusterNetworkDict, ClusterNodeDict, ClusterStorageDict, HAResourceDict, HypervisorDriver, ) def _declared(name: str) -> ast.FunctionDef: tree = ast.parse(inspect.getsource(hypervisor_module)) for node in ast.walk(tree): if isinstance(node, ast.FunctionDef) and node.name == name: return node raise AssertionError(f"HypervisorDriver does not declare {name}()") class TestClusterListing: def test_is_declared(self): fn = _declared("get_clusters") assert ast.unparse(fn.returns) == "list[ClusterDict]" def test_absent_until_a_driver_implements_it(self): """netOrk probes capabilities with hasattr; a hypervisor that cannot describe its cluster must not seem to.""" assert not hasattr(HypervisorDriver, "get_clusters") class TestClusterShape: def test_cluster(self): assert get_type_hints(ClusterDict, include_extras=True) == { "id": str | None, "name": str | None, "quorate": bool | None, "nodes": list[ClusterNodeDict], "storages": list[ClusterStorageDict], "networks": list[ClusterNetworkDict], "ha_resources": NotRequired[list[HAResourceDict] | None], "backup_jobs": NotRequired[list[BackupJobDict] | None], "backups": NotRequired[list[BackupDict] | None], } def test_cluster_keys_added_later_stay_optional(self): """A driver written before HA and backups were part of the report stays valid.""" assert ClusterDict.__required_keys__ == frozenset( {"id", "name", "quorate", "nodes", "storages", "networks"} ) def test_node(self): hints = get_type_hints(ClusterNodeDict, include_extras=True) assert hints == { "name": str, "status": str, "local": bool, "maintenance": bool | None, "cpu_threads": int | None, "cpu_cores": int | None, "cpu_model": str | None, "cpu_flags": list[str] | None, "cpu_usage": float | None, "memory_total": int | None, "memory_used": int | None, "votes": NotRequired[int | None], } assert "votes" not in ClusterNodeDict.__required_keys__ def test_storage(self): hints = get_type_hints(ClusterStorageDict, include_extras=True) assert hints == { "name": str, "type": str, "shared": bool, "content": list[str], "nodes": list[str], "total": int | None, "used": int | None, "backup_server": NotRequired[BackupServerRefDict | None], } # A driver written before backup servers were part of the report stays valid. assert "backup_server" not in ClusterStorageDict.__required_keys__ def test_network(self): hints = get_type_hints(ClusterNetworkDict, include_extras=True) assert hints == { "name": str, "kind": str, "vlan_aware": bool, "fixed_vlan_tag": NotRequired[int | None], "nodes": list[str], } assert ClusterNetworkDict.__required_keys__ == frozenset( {"name", "kind", "vlan_aware", "nodes"} ) class TestHAAndBackupShapes: def test_ha_resource(self): hints = get_type_hints(HAResourceDict, include_extras=True) assert hints == { "vmid": int, "kind": str, "requested": str, "status": str | None, "node": str | None, "group": NotRequired[str | None], "rules": list[str], } assert HAResourceDict.__required_keys__ == frozenset( {"vmid", "kind", "requested", "status", "node", "rules"} ) def test_backup_job(self): assert get_type_hints(BackupJobDict) == { "id": str, "enabled": bool, "schedule": str | None, "storage": str | None, "mode": str | None, "all": bool, "vmids": list[int], "exclude": list[int], "pool": str | None, "node": str | None, } def test_backup(self): assert get_type_hints(BackupDict) == { "vmid": int, "storage": str, "time": int, "size": int | None, "count": int, } class TestCreateVmTakesANode: def test_node_is_an_optional_keyword(self): fn = _declared("create_vm_from_cloud_init") kwonly = { arg.arg: default for arg, default in zip(fn.args.kwonlyargs, fn.args.kw_defaults, strict=True) } assert "node" in kwonly default = kwonly["node"] assert isinstance(default, ast.Constant) and default.value is None