ADCM-6283: Prepare an example of interaction with a host (#85)

tests/integration/examples/conftest.py

@@ -4,7 +4,7 @@
 
 from adcm_aio_client import ADCMSession, Credentials
 from adcm_aio_client.client import ADCMClient
-from adcm_aio_client.objects import Bundle, Cluster, Host
+from adcm_aio_client.objects import Bundle, Cluster, Host, HostProvider
 from tests.integration.setup_environment import ADCMContainer
 
 REQUEST_KWARGS: dict = {"timeout": 10, "retry_interval": 1, "retry_attempts": 1}
@@ -40,10 +40,14 @@ async def example_cluster(admin_client: ADCMClient) -> AsyncGenerator[Cluster, N
 
 
 @pytest_asyncio.fixture()
-async def three_hosts(admin_client: ADCMClient, simple_hostprovider_bundle: Bundle) -> list[Host]:
-    provider = await admin_client.hostproviders.create(bundle=simple_hostprovider_bundle, name="Hostprovider")
+async def example_hostprovider(admin_client: ADCMClient, simple_hostprovider_bundle: Bundle) -> HostProvider:
+    return await admin_client.hostproviders.create(bundle=simple_hostprovider_bundle, name="Example hostprovider")
+
+
+@pytest_asyncio.fixture()
+async def three_hosts(admin_client: ADCMClient, example_hostprovider: HostProvider) -> list[Host]:
     names = {"host-1", "host-2", "host-3"}
     for name in names:
-        await admin_client.hosts.create(hostprovider=provider, name=name)
+        await admin_client.hosts.create(hostprovider=example_hostprovider, name=name)
 
     return await admin_client.hosts.filter(name__in=names)

tests/integration/examples/test_host.py

@@ -0,0 +1,63 @@
+import pytest
+
+from adcm_aio_client.client import ADCMClient
+from adcm_aio_client.errors import ObjectDoesNotExistError
+from adcm_aio_client.objects import Cluster, Host, HostProvider
+
+pytestmark = [pytest.mark.asyncio]
+
+
+async def test_host(admin_client: ADCMClient, example_cluster: Cluster, example_hostprovider: HostProvider) -> None:
+    """
+    Service (`client.hosts`) API Examples:
+        - creating a host
+        - retrieval with filtering / all hosts
+        - iteration through all hosts
+        - adding host to cluster
+        - turning on maintenance mode
+        - refreshing host's data
+        - host removal
+    """
+
+    client = admin_client
+    cluster = example_cluster
+    hostprovider = example_hostprovider
+
+    # Create new host
+    host = await client.hosts.create(hostprovider=hostprovider, name="Example-host")
+
+    # Get all hosts
+    all_hosts: list[Host] = await client.hosts.all()  # noqa: F841
+
+    # Iterate through all hosts
+    async for host in client.hosts.iter():  # noqa: B007
+        pass
+
+    # Get all hosts of hostprovider
+    hosts: list[Host] = await client.hosts.filter(hostprovider__eq=hostprovider)
+
+    name_not_exists = "Non-existent-host"
+
+    # Get host or `None` if no object is found
+    none_host: None = await client.hosts.get_or_none(name__eq=name_not_exists)  # pyright: ignore[reportAssignmentType]  # noqa: F841
+
+    # Get error trying to get non-existent host
+    with pytest.raises(ObjectDoesNotExistError, match="No objects found with the given filter."):
+        await client.hosts.get(name__eq=name_not_exists)
+
+    # Get all hosts, which name contains `host`
+    hosts: list[Host] = await client.hosts.filter(name__contains="host")  # noqa: F841
+
+    # Add host to cluster with allowed maintenance mode
+    await cluster.hosts.add(host=host)
+
+    # Turn on host's maintenance mode
+    host_mm = await host.maintenance_mode
+    await host_mm.on()
+
+    # Sync host data with remote state
+    await host.refresh()
+
+    # Delete host after removing it from cluster
+    await cluster.hosts.remove(host=host)
+    await host.delete()