Skip to content

Client

The Client class is the main entry point for the Incus Python SDK. It provides access to all the API clients and methods for connecting to the Incus API.

Usage

from incus_sdk import Client

# Create a client
client = Client()

# Connect to the Incus API
await client.connect()

# Use the client
info = await client.get_server_info()
print(f"API version: {info.get('metadata', {}).get('api_version')}")

# Disconnect from the Incus API
await client.disconnect()

Alternatively, you can use the client as an async context manager:

from incus_sdk import Client

async with Client() as client:
    info = await client.get_server_info()
    print(f"API version: {info.get('metadata', {}).get('api_version')}")

Client Class

Main client for Incus API.

Source code in incus_sdk/client.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class Client:
    """Main client for Incus API."""

    def __init__(
        self,
        endpoint: str = None,
        cert: Optional[Tuple[str, str]] = None,
        verify: bool = True,
        project: str = None,
        timeout: int = 30,
    ):
        """
        Initialize a new Incus client.

        Args:
            endpoint: The Incus API endpoint URL.
            cert: Client certificate and key as a tuple (cert_path, key_path).
            verify: Whether to verify SSL certificates.
            project: The project to use.
            timeout: Request timeout in seconds.
        """
        self.api = APIClient(
            endpoint=endpoint,
            cert=cert,
            verify=verify,
            project=project,
            timeout=timeout,
        )

        # Initialize API clients
        self.instances = InstancesAPI(self.api)
        self.images = ImagesAPI(self.api)
        self.certificates = CertificatesAPI(self.api)
        self.networks = NetworksAPI(self.api)
        self.profiles = ProfilesAPI(self.api)
        self.storage_pools = StoragePoolsAPI(self.api)
        self.cluster = ClusterAPI(self.api)
        self.operations = OperationsAPI(self.api)
        self.projects = ProjectsAPI(self.api)

    async def __aenter__(self):
        """Enter the async context manager."""
        await self.connect()
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Exit the async context manager."""
        await self.disconnect()

    async def connect(self):
        """Connect to the Incus API."""
        await self.api.connect()

    async def disconnect(self):
        """Disconnect from the Incus API."""
        await self.api.disconnect()

    async def get_server_info(self) -> Dict[str, Any]:
        """
        Get information about the server.

        Returns:
            Dict[str, Any]: Server information.
        """
        return await self.api.get("/1.0")

    async def get_resources(self) -> Dict[str, Any]:
        """
        Get server resources.

        Returns:
            Dict[str, Any]: Server resources.
        """
        return await self.api.get("/1.0/resources")

    async def wait_for_operation(
        self, operation_id: str, timeout: int = 60
    ) -> Dict[str, Any]:
        """
        Wait for an operation to complete.

        Args:
            operation_id: The operation ID.
            timeout: Timeout in seconds.

        Returns:
            Dict[str, Any]: The operation result.
        """
        return await self.operations.wait(operation_id, timeout)

__aenter__() async

Enter the async context manager.

Source code in incus_sdk/client.py 
59
60
61
62
async def __aenter__(self):
    """Enter the async context manager."""
    await self.connect()
    return self

__aexit__(exc_type, exc_val, exc_tb) async

Exit the async context manager.

Source code in incus_sdk/client.py 
64
65
66
async def __aexit__(self, exc_type, exc_val, exc_tb):
    """Exit the async context manager."""
    await self.disconnect()

__init__(endpoint=None, cert=None, verify=True, project=None, timeout=30)

Initialize a new Incus client.

Parameters:

Name Type Description Default
endpoint str

The Incus API endpoint URL.

 None
cert Optional[Tuple[str, str]]

Client certificate and key as a tuple (cert_path, key_path).

 None
verify bool

Whether to verify SSL certificates.

 True
project str

The project to use.

 None
timeout int

Request timeout in seconds.

 30
Source code in incus_sdk/client.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def __init__(
    self,
    endpoint: str = None,
    cert: Optional[Tuple[str, str]] = None,
    verify: bool = True,
    project: str = None,
    timeout: int = 30,
):
    """
    Initialize a new Incus client.

    Args:
        endpoint: The Incus API endpoint URL.
        cert: Client certificate and key as a tuple (cert_path, key_path).
        verify: Whether to verify SSL certificates.
        project: The project to use.
        timeout: Request timeout in seconds.
    """
    self.api = APIClient(
        endpoint=endpoint,
        cert=cert,
        verify=verify,
        project=project,
        timeout=timeout,
    )

    # Initialize API clients
    self.instances = InstancesAPI(self.api)
    self.images = ImagesAPI(self.api)
    self.certificates = CertificatesAPI(self.api)
    self.networks = NetworksAPI(self.api)
    self.profiles = ProfilesAPI(self.api)
    self.storage_pools = StoragePoolsAPI(self.api)
    self.cluster = ClusterAPI(self.api)
    self.operations = OperationsAPI(self.api)
    self.projects = ProjectsAPI(self.api)

connect() async

Connect to the Incus API.

Source code in incus_sdk/client.py 
68
69
70
async def connect(self):
    """Connect to the Incus API."""
    await self.api.connect()

disconnect() async

Disconnect from the Incus API.

Source code in incus_sdk/client.py 
72
73
74
async def disconnect(self):
    """Disconnect from the Incus API."""
    await self.api.disconnect()

get_resources() async

Get server resources.

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: Server resources.
Source code in incus_sdk/client.py 
85
86
87
88
89
90
91
92
async def get_resources(self) -> Dict[str, Any]:
    """
    Get server resources.

    Returns:
        Dict[str, Any]: Server resources.
    """
    return await self.api.get("/1.0/resources")

get_server_info() async

Get information about the server.

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: Server information.
Source code in incus_sdk/client.py 
76
77
78
79
80
81
82
83
async def get_server_info(self) -> Dict[str, Any]:
    """
    Get information about the server.

    Returns:
        Dict[str, Any]: Server information.
    """
    return await self.api.get("/1.0")

wait_for_operation(operation_id, timeout=60) async

Wait for an operation to complete.

Parameters:

Name Type Description Default
operation_id str

The operation ID.

 required
timeout int

Timeout in seconds.

 60

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation result.
Source code in incus_sdk/client.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
async def wait_for_operation(
    self, operation_id: str, timeout: int = 60
) -> Dict[str, Any]:
    """
    Wait for an operation to complete.

    Args:
        operation_id: The operation ID.
        timeout: Timeout in seconds.

    Returns:
        Dict[str, Any]: The operation result.
    """
    return await self.operations.wait(operation_id, timeout)

API Clients

The Incus Python SDK provides several API clients for interacting with different aspects of the Incus API. These clients are accessible as attributes of the Client class.

Attribute Type Description
instances InstancesAPI API client for managing instances (containers and virtual machines)
images ImagesAPI API client for managing images
networks NetworksAPI API client for managing networks
profiles ProfilesAPI API client for managing profiles
storage_pools StoragePoolsAPI API client for managing storage pools and volumes
certificates CertificatesAPI API client for managing certificates
cluster ClusterAPI API client for managing clusters
operations OperationsAPI API client for managing operations
projects ProjectsAPI API client for managing projects

Client Methods

connect

async def connect()

Connect to the Incus API. This method is called automatically when using the client as an async context manager.

disconnect

async def disconnect()

Disconnect from the Incus API. This method is called automatically when using the client as an async context manager.

get_server_info

async def get_server_info() -> Dict[str, Any]

Get information about the Incus server.

Returns: - A dictionary containing server information.

get_resources

async def get_resources() -> Dict[str, Any]

Get information about the resources available on the Incus server.

Returns: - A dictionary containing resource information.

wait_for_operation

async def wait_for_operation(operation_id: str, timeout: int = 60) -> Dict[str, Any]

Wait for an operation to complete.

Parameters: - operation_id: The ID of the operation to wait for. - timeout: The maximum time to wait in seconds (default: 60).

Returns: - A dictionary containing the operation result.

Raises: - IncusOperationTimeout: If the operation does not complete within the timeout. - IncusOperationFailed: If the operation fails.