Skip to content

Projects API

The ProjectsAPI client provides methods for managing Incus projects.

Usage

from incus_sdk import Client

async with Client() as client:
    # List all projects
    projects = await client.projects.list()

    # Get a project by name
    project = await client.projects.get("default")

    # Create a new project
    await client.projects.create(
        name="my-project",
        config={
            "features.images": "true",
            "features.profiles": "true"
        },
        description="My custom project"
    )

    # Update a project
    await client.projects.update(
        "my-project",
        {
            "config": {
                "features.networks": "true"
            }
        }
    )

    # Delete a project
    await client.projects.delete("my-project")

Class Documentation

API client for Incus projects.

Source code in incus_sdk/api/projects.py 
 11
 12
 13
 14
 15
 16
 17
 18
 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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class ProjectsAPI:
    """API client for Incus projects."""

    def __init__(self, client: APIClient):
        """
        Initialize a new ProjectsAPI client.

        Args:
            client: The base API client.
        """
        self.client = client

    async def list(self, recursion: int = 1) -> List[Project]:
        """
        List all projects.

        Args:
            recursion: Level of recursion for the response.

        Returns:
            List[Project]: List of projects.
        """
        params = {"recursion": recursion}
        response = await self.client.get("/1.0/projects", params=params)

        projects = []
        for project_data in response.get("metadata", []):
            projects.append(Project(client=self, **project_data))

        return projects

    async def get(self, name: str) -> Project:
        """
        Get a project by name.

        Args:
            name: Name of the project.

        Returns:
            Project: The project.
        """
        response = await self.client.get(f"/1.0/projects/{name}")
        return Project(client=self, **response.get("metadata", {}))

    async def create(
        self, name: str, config: Dict[str, Any] = None, description: str = None
    ) -> Dict[str, Any]:
        """
        Create a new project.

        Args:
            name: Name of the project.
            config: Project configuration.
            description: Description of the project.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {"name": name}

        if config:
            data["config"] = config
        if description:
            data["description"] = description

        return await self.client.post("/1.0/projects", data=data)

    async def update(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """
        Update a project.

        Args:
            name: Name of the project.
            config: New configuration.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.patch(f"/1.0/projects/{name}", data=config)

    async def replace(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """
        Replace a project configuration.

        Args:
            name: Name of the project.
            config: New configuration.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.put(f"/1.0/projects/{name}", data=config)

    async def delete(self, name: str) -> Dict[str, Any]:
        """
        Delete a project.

        Args:
            name: Name of the project.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.delete(f"/1.0/projects/{name}")

    async def rename(self, name: str, new_name: str) -> Dict[str, Any]:
        """
        Rename a project.

        Args:
            name: Current name of the project.
            new_name: New name for the project.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {"name": new_name}

        return await self.client.post(f"/1.0/projects/{name}", data=data)

    async def state(self, name: str) -> Dict[str, Any]:
        """
        Get the state of a project.

        Args:
            name: Name of the project.

        Returns:
            Dict[str, Any]: The project state.
        """
        response = await self.client.get(f"/1.0/projects/{name}/state")
        return response.get("metadata", {})

__init__(client)

Initialize a new ProjectsAPI client.

Parameters:

Name Type Description Default
client APIClient

The base API client.

 required
Source code in incus_sdk/api/projects.py 
14
15
16
17
18
19
20
21
def __init__(self, client: APIClient):
    """
    Initialize a new ProjectsAPI client.

    Args:
        client: The base API client.
    """
    self.client = client

create(name, config=None, description=None) async

Create a new project.

Parameters:

Name Type Description Default
name str

Name of the project.

 required
config Dict[str, Any]

Project configuration.

 None
description str

Description of the project.

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/projects.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
async def create(
    self, name: str, config: Dict[str, Any] = None, description: str = None
) -> Dict[str, Any]:
    """
    Create a new project.

    Args:
        name: Name of the project.
        config: Project configuration.
        description: Description of the project.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {"name": name}

    if config:
        data["config"] = config
    if description:
        data["description"] = description

    return await self.client.post("/1.0/projects", data=data)

delete(name) async

Delete a project.

Parameters:

Name Type Description Default
name str

Name of the project.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/projects.py 
104
105
106
107
108
109
110
111
112
113
114
async def delete(self, name: str) -> Dict[str, Any]:
    """
    Delete a project.

    Args:
        name: Name of the project.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.delete(f"/1.0/projects/{name}")

get(name) async

Get a project by name.

Parameters:

Name Type Description Default
name str

Name of the project.

 required

Returns:

Name Type Description
Project Project

The project.
Source code in incus_sdk/api/projects.py 
42
43
44
45
46
47
48
49
50
51
52
53
async def get(self, name: str) -> Project:
    """
    Get a project by name.

    Args:
        name: Name of the project.

    Returns:
        Project: The project.
    """
    response = await self.client.get(f"/1.0/projects/{name}")
    return Project(client=self, **response.get("metadata", {}))

list(recursion=1) async

List all projects.

Parameters:

Name Type Description Default
recursion int

Level of recursion for the response.

 1

Returns:

Type Description
List[Project]

List[Project]: List of projects.
Source code in incus_sdk/api/projects.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
async def list(self, recursion: int = 1) -> List[Project]:
    """
    List all projects.

    Args:
        recursion: Level of recursion for the response.

    Returns:
        List[Project]: List of projects.
    """
    params = {"recursion": recursion}
    response = await self.client.get("/1.0/projects", params=params)

    projects = []
    for project_data in response.get("metadata", []):
        projects.append(Project(client=self, **project_data))

    return projects

rename(name, new_name) async

Rename a project.

Parameters:

Name Type Description Default
name str

Current name of the project.

 required
new_name str

New name for the project.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/projects.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
async def rename(self, name: str, new_name: str) -> Dict[str, Any]:
    """
    Rename a project.

    Args:
        name: Current name of the project.
        new_name: New name for the project.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {"name": new_name}

    return await self.client.post(f"/1.0/projects/{name}", data=data)

replace(name, config) async

Replace a project configuration.

Parameters:

Name Type Description Default
name str

Name of the project.

 required
config Dict[str, Any]

New configuration.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/projects.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
async def replace(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
    """
    Replace a project configuration.

    Args:
        name: Name of the project.
        config: New configuration.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.put(f"/1.0/projects/{name}", data=config)

state(name) async

Get the state of a project.

Parameters:

Name Type Description Default
name str

Name of the project.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The project state.
Source code in incus_sdk/api/projects.py 
131
132
133
134
135
136
137
138
139
140
141
142
async def state(self, name: str) -> Dict[str, Any]:
    """
    Get the state of a project.

    Args:
        name: Name of the project.

    Returns:
        Dict[str, Any]: The project state.
    """
    response = await self.client.get(f"/1.0/projects/{name}/state")
    return response.get("metadata", {})

update(name, config) async

Update a project.

Parameters:

Name Type Description Default
name str

Name of the project.

 required
config Dict[str, Any]

New configuration.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/projects.py 
78
79
80
81
82
83
84
85
86
87
88
89
async def update(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
    """
    Update a project.

    Args:
        name: Name of the project.
        config: New configuration.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.patch(f"/1.0/projects/{name}", data=config)

Methods

list

async def list(recursion: int = 1) -> List[Project]

List all projects.

Parameters: - recursion: Level of recursion for the response (default: 1).

Returns: - A list of Project objects.

get

async def get(name: str) -> Project

Get a project by name.

Parameters: - name: Name of the project.

Returns: - A Project object.

create

async def create(
    name: str, 
    config: Dict[str, Any] = None, 
    description: str = None
) -> Dict[str, Any]

Create a new project.

Parameters: - name: Name of the project. - config: Project configuration as a dictionary (optional). - description: Description of the project (optional).

Returns: - The operation response as a dictionary.

Example:

# Create a project with specific features enabled
await client.projects.create(
    name="production",
    config={
        "features.images": "true",
        "features.profiles": "true",
        "features.storage.volumes": "true",
        "features.networks": "true",
        "restricted": "true"
    },
    description="Production environment"
)

update

async def update(
    name: str, 
    config: Dict[str, Any]
) -> Dict[str, Any]

Update a project.

Parameters: - name: Name of the project. - config: New configuration as a dictionary.

Returns: - The operation response as a dictionary.

Note: This method performs a partial update of the project configuration, only modifying the specified fields.

replace

async def replace(
    name: str, 
    config: Dict[str, Any]
) -> Dict[str, Any]

Replace a project configuration.

Parameters: - name: Name of the project. - config: New configuration as a dictionary.

Returns: - The operation response as a dictionary.

Note: This method replaces the entire project configuration with the provided configuration.

delete

async def delete(
    name: str
) -> Dict[str, Any]

Delete a project.

Parameters: - name: Name of the project.

Returns: - The operation response as a dictionary.

rename

async def rename(
    name: str, 
    new_name: str
) -> Dict[str, Any]

Rename a project.

Parameters: - name: Current name of the project. - new_name: New name for the project.

Returns: - The operation response as a dictionary.

state

async def state(
    name: str
) -> Dict[str, Any]

Get the state of a project.

Parameters: - name: Name of the project.

Returns: - The project state as a dictionary.

Example:

# Get the state of a project
state = await client.projects.state("default")
print(f"Resources: {state.get('resources')}")