"""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 ( ClusterDict, ClusterNetworkDict, ClusterNodeDict, ClusterStorageDict, 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) == { "id": str | None, "name": str | None, "quorate": bool | None, "nodes": list[ClusterNodeDict], "storages": list[ClusterStorageDict], "networks": list[ClusterNetworkDict], } def test_node(self): hints = get_type_hints(ClusterNodeDict) 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, } def test_storage(self): assert get_type_hints(ClusterStorageDict) == { "name": str, "type": str, "shared": bool, "content": list[str], "nodes": list[str], "total": int | None, "used": int | None, } 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 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