kumiho.project

Project module for Kumiho asset management.

This module provides the Project class, which represents the top-level container for organizing assets in Kumiho. Projects serve as namespaces that contain spaces, items, revisions, and artifacts.

Example

Creating and working with projects:

import kumiho

# Create a new project
project = kumiho.create_project("film-2024", "Feature film VFX assets")

# Create space structure
chars = project.create_space("characters")
envs = project.create_space("environments")

# Create items within spaces
hero = chars.create_item("hero", "model")

# List all spaces
for space in project.get_spaces(recursive=True):
    print(space.path)

class kumiho.project.Project

Bases: KumihoObject

A Kumiho project—the top-level container for assets.

Projects are the root of the Kumiho hierarchy. Each project has its own namespace for spaces and items, and manages access control and settings independently.

Projects support both public and private access modes, allowing you to share assets publicly or restrict them to authenticated users.

project_id

The unique identifier for this project.

Type:

str

name

The URL-safe name of the project (e.g., “film-2024”).

Type:

str

description

Human-readable description of the project.

Type:

str

created_at

ISO timestamp when the project was created.

Type:

Optional[str]

updated_at

ISO timestamp of the last update.

Type:

Optional[str]

deprecated

Whether the project is deprecated (soft-deleted).

Type:

bool

allow_public

Whether anonymous read access is enabled.

Type:

bool

Example

Basic project operations:

import kumiho

# Get existing project
project = kumiho.get_project("my-project")

# Create spaces
assets = project.create_space("assets")
shots = project.create_space("shots")

# Navigate to nested spaces
char_space = project.get_space("assets/characters")

# List all spaces recursively
for space in project.get_spaces(recursive=True):
    print(f"  {space.path}")

# Update project settings
project.set_public(True)  # Enable public access
project.update(description="Updated description")

# Soft delete (deprecate)
project.delete()

# Hard delete (permanent)
project.delete(force=True)

__init__(pb, client)

Initialize a Project from a protobuf response.

Parameters:

• pb (ProjectResponse) – The protobuf ProjectResponse message.

• client (_Client) – The client instance for making API calls.

Return type:

None

__repr__()

Return a string representation of the Project.

Return type:

str

create_space(name, parent_path=None)

Create a space within this project.

Parameters:

• name (str) – The name of the space to create.

• parent_path (Optional[str]) – Optional parent path. If not provided, creates the space at the project root (e.g., “/project-name”).

Returns:

The newly created Space object.

Return type:

Space

Example

>>> project = kumiho.get_project("film-2024")
>>> # Create at root
>>> chars = project.create_space("characters")
>>> # Create nested space
>>> heroes = project.create_space("heroes", parent_path="/film-2024/characters")

create_bundle(bundle_name, parent_path=None, metadata=None)

Create a new bundle within this project.

Bundles are special items that aggregate other items. They provide a way to group related items together and maintain an audit trail of membership changes through revision history.

Parameters:

• bundle_name (str) – The name of the bundle. Must be unique within the parent space.

• parent_path (Optional[str]) – Optional parent path for the bundle. If not provided, creates the bundle at the project root (/{project_name}).

• metadata (Optional[Dict[str, str]]) – Optional key-value metadata for the bundle.

Returns:

The newly created Bundle object with kind “bundle”.

Return type:

Bundle

Raises:

grpc.RpcError – If the bundle name is already taken or if there is a connection error.

See also

Bundle: The Bundle class. create_bundle(): Create bundle in a space.

Example:

>>> project = kumiho.get_project("film-2024")
>>> # Create at project root
>>> bundle = project.create_bundle("release-bundle")
>>>
>>> # Create in specific space
>>> bundle = project.create_bundle(
...     "character-bundle",
...     parent_path="/film-2024/assets"
... )
>>>
>>> # Add items to the bundle
>>> hero = project.get_space("models").get_item("hero", "model")
>>> bundle.add_member(hero)

create_item(item_name, kind, parent_path=None, metadata=None)

Create a new item within this project.

Parameters:

• item_name (str) – The name of the item. Must be unique within the parent space combined with the kind.

• kind (str) – The type/kind of the item (e.g., “model”, “texture”).

• parent_path (Optional[str]) – Optional parent path for the item. If not provided, creates the item at the project root (/{project_name}).

• metadata (Optional[Dict[str, str]]) – Optional key-value metadata for the item.

Returns:

The newly created Item object.

Return type:

Item

Raises:

grpc.RpcError – If the item name/kind combination is already taken or if there is a connection error.

Example:

>>> project = kumiho.get_project("film-2024")
>>> # Create at project root
>>> item = project.create_item("hero", "model")
>>>
>>> # Create in specific space
>>> item = project.create_item(
...     "hero",
...     "texture",
...     parent_path="/film-2024/assets"
... )

get_item(item_name, kind, parent_path=None)

Get an existing item within this project.

Parameters:

• item_name (str) – The name of the item.

• kind (str) – The type/kind of the item (e.g., “model”, “texture”).

• parent_path (Optional[str]) – Optional parent path. If not provided, looks in the project root (/{project_name}).

Returns:

The Item object.

Return type:

Item

Raises:

grpc.RpcError – If the item is not found.

Example:

>>> project = kumiho.get_project("film-2024")
>>> # Get from project root
>>> item = project.get_item("hero", "model")
>>>
>>> # Get from specific space
>>> item = project.get_item(
...     "hero",
...     "texture",
...     parent_path="/film-2024/assets"
... )

get_bundle(bundle_name, parent_path=None)

Get an existing bundle within this project.

Parameters:

• bundle_name (str) – The name of the bundle.

• parent_path (Optional[str]) – Optional parent path. If not provided, looks in the project root (/{project_name}).

Returns:

The Bundle object.

Return type:

Bundle

Raises:

• ValueError – If the item exists but is not a bundle.

• grpc.RpcError – If the bundle is not found.

Example:

>>> project = kumiho.get_project("film-2024")
>>> # Get from project root
>>> bundle = project.get_bundle("release-bundle")
>>>
>>> # Get from specific space
>>> bundle = project.get_bundle(
...     "character-bundle",
...     parent_path="/film-2024/assets"
... )
>>> members = bundle.get_members()

delete(force=False)

Delete or deprecate this project.

Parameters:

force (bool) – If True, permanently delete the project and all its contents. If False (default), mark as deprecated.

Returns:

Response indicating success or failure.

Return type:

StatusResponse

Warning

Force deletion is irreversible and removes all spaces, items, revisions, artifacts, and edges within the project.

Example

>>> project = kumiho.get_project("old-project")
>>> # Soft delete (can be recovered)
>>> project.delete()
>>> # Hard delete (permanent)
>>> project.delete(force=True)

set_public(public)

Set whether this project allows anonymous read access.

Parameters:

public (bool) – True to enable public access, False to require authentication for all access.

Returns:

The updated Project object.

Return type:

Project

Example

>>> project.set_public(True)  # Enable public access
>>> project.set_public(False)  # Require authentication

update(description=None, allow_public=None)

Update project properties.

Parameters:

• description (Optional[str]) – New description for the project.

• allow_public (Optional[bool]) – New public access setting.

Returns:

The updated Project object.

Return type:

Project

Example

>>> project.update(
...     description="Updated project description",
...     allow_public=True
... )

get_space(name, parent_path=None)

Get an existing space within this project.

Parameters:

• name (str) – The name of the space, or an absolute path starting with “/”.

• parent_path (Optional[str]) – Optional parent path if name is a relative name.

Returns:

The Space object.

Return type:

Space

Raises:

grpc.RpcError – If the space is not found.

Example

>>> # Get by absolute path
>>> space = project.get_space("/film-2024/characters")

>>> # Get by relative name (from project root)
>>> space = project.get_space("characters")

>>> # Get nested space with parent path
>>> heroes = project.get_space("heroes", parent_path="/film-2024/characters")

get_spaces(parent_path=None, recursive=False)

List spaces within this project.

Parameters:

• parent_path (Optional[str]) – Optional path to start from. Defaults to project root.

• recursive (bool) – If True, include all nested spaces. If False (default), only direct children.

Returns:

A list of Space objects.

Return type:

List[Space]

Example

>>> # List direct children only
>>> spaces = project.get_spaces()
>>> for s in spaces:
...     print(s.name)

>>> # List all spaces recursively
>>> all_spaces = project.get_spaces(recursive=True)
>>> for s in all_spaces:
...     print(s.path)