kumiho.space

Space module for Kumiho asset management.

This module provides the Space class, which represents hierarchical containers for organizing items within a project. Spaces form the folder structure of the Kumiho asset hierarchy.

Example

Working with spaces:

import kumiho

project = kumiho.get_project("film-2024")

# Create space hierarchy
chars = project.create_space("characters")
heroes = chars.create_space("heroes")
villains = chars.create_space("villains")

# Create items in spaces
hero_model = heroes.create_item("main-hero", "model")

# Navigate space hierarchy
parent = heroes.get_parent_space()  # Returns chars
children = chars.get_child_spaces()  # Returns [heroes, villains]

class kumiho.space.Space[source]

Bases: KumihoObject

A hierarchical container for organizing items in Kumiho.

Spaces form the folder structure within a project. They can contain other spaces (subspaces) and items, allowing you to organize assets in a meaningful hierarchy.

Spaces are identified by their full path (e.g., “/project/characters/heroes”) and can store custom metadata.

path

The full path of the space (e.g., “/project/assets”).

Type:: str

name

The name of this space (last component of path).

Type:: str

type

The type of space (“root” for project-level, “sub” for nested).

Type:: str

created_at

ISO timestamp when the space was created.

Type:: Optional[str]

author

The user ID who created the space.

Type:: str

metadata

Custom metadata key-value pairs.

Type:: Dict[str, str]

username

Display name of the creator.

Type:: str

Example

Creating and navigating spaces:

import kumiho

project = kumiho.get_project("my-project")

# Create a space
assets = project.create_space("assets")

# Create subspaces
models = assets.create_space("models")
textures = assets.create_space("textures")

# Create items
chair = models.create_item("chair", "model")

# List items with filters
all_models = models.get_items()
wood_textures = textures.get_items(name_filter="wood*")

# Navigate hierarchy
parent = models.get_parent_space()  # Returns assets
project = models.get_project()  # Returns my-project

__init__(pb_space, client)[source]

Initialize a Space from a protobuf response.

Parameters:

pb_space (SpaceResponse) – The protobuf SpaceResponse message.
client (_Client) – The client instance for making API calls.

Return type:

None

__repr__()[source]

Return a string representation of the Space.

Return type:: str

create_space(name)[source]

Create a new subspace within this space.

Parameters:: name (str) – The name of the new subspace.
Returns:: The newly created Space object.
Return type:: Space

Example

>>> assets = project.create_space("assets")
>>> models = assets.create_space("models")
>>> textures = assets.create_space("textures")

get_space(name)[source]

Get an existing subspace by name.

Parameters:: name (str) – The name of the subspace (not full path).
Returns:: The Space object.
Return type:: Space
Raises:: grpc.RpcError – If the space is not found.

Example

>>> assets = project.get_space("assets")
>>> models = assets.get_space("models")

get_spaces(recursive=False)[source]

List child spaces under this space.

Parameters:: 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

>>> # Direct children only
>>> children = space.get_spaces()

>>> # All nested spaces
>>> all_spaces = space.get_spaces(recursive=True)

create_item(item_name, kind)[source]

Create a new item within this space.

Items are versioned assets that can contain multiple artifacts. The combination of name and kind must be unique within the space.

Parameters:

item_name (str) – The name of the item (e.g., “hero-character”).
kind (str) – The kind of item (e.g., “model”, “texture”, “workflow”).

Returns:

The newly created Item object.

Return type:

Item

Example

>>> models = project.get_space("models")
>>> chair = models.create_item("office-chair", "model")
>>> wood = textures.create_item("oak-wood", "texture")

create_bundle(bundle_name, metadata=None)[source]

Create a new bundle within this space.

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 space.
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 project.

Example:

>>> # Create a bundle for a character bundle
>>> assets = project.get_space("assets")
>>> bundle = assets.create_bundle("character-bundle")
>>>
>>> # Add items to the bundle
>>> hero = assets.get_item("hero", "model")
>>> bundle.add_member(hero)

get_items(item_name_filter='', kind_filter='')[source]

List items within this space with optional filtering.

Parameters:

item_name_filter (str) – Filter by item name. Supports wildcards.
kind_filter (str) – Filter by item kind.

Returns:

A list of Item objects matching the filters.

Return type:

List[Item]

Example

>>> # All items in space
>>> items = space.get_items()

>>> # Only models
>>> models = space.get_items(kind_filter="model")

>>> # Items starting with "hero"
>>> heroes = space.get_items(item_name_filter="hero*")

get_item(item_name, kind)[source]

Get a specific item by name and kind.

Parameters:

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

Returns:

The Item object.

Return type:

Item

Raises:

grpc.RpcError – If the item is not found.

Example

>>> chair = models.get_item("office-chair", "model")
>>> revisions = chair.get_revisions()

get_bundle(bundle_name)[source]

Get a bundle by name from this space.

This is a convenience method that fetches a bundle item and returns it as a Bundle object with bundle-specific methods like add_member(), get_members(), etc.

Parameters:: bundle_name (str) – The name of the bundle.
Returns:: The Bundle object.
Return type:: Bundle
Raises:: grpc.RpcError – If the bundle is not found.

Example

>>> bundle = space.get_bundle("character-bundle")
>>> members = bundle.get_members()
>>> for member in members:
...     print(member.item_kref)

set_metadata(metadata)[source]

Set or update metadata for this space.

Metadata is a dictionary of string key-value pairs that can store any custom information about the space.

Parameters:: metadata (Dict[str, str]) – Dictionary of metadata to set. Existing keys are overwritten, new keys are added.
Returns:: The updated Space object.
Return type:: Space

Example

>>> space.set_metadata({
...     "department": "modeling",
...     "supervisor": "jane.doe",
...     "status": "active"
... })

set_attribute(key, value)[source]

Set a single metadata attribute.

This allows granular updates to metadata without replacing the entire metadata map.

Parameters:

key (str) – The attribute key to set.
value (str) – The attribute value.

Returns:

True if the attribute was set successfully.

Return type:

bool

Example

>>> space.set_attribute("department", "modeling")
True

get_attribute(key)[source]

Get a single metadata attribute.

Parameters:: key (str) – The attribute key to retrieve.
Return type:: Optional[str]
Returns:: The attribute value if it exists, None otherwise.

Example

>>> space.get_attribute("department")
"modeling"

delete_attribute(key)[source]

Delete a single metadata attribute.

Parameters:: key (str) – The attribute key to delete.
Returns:: True if the attribute was deleted successfully.
Return type:: bool

Example

>>> space.delete_attribute("old_field")
True

delete(force=False)[source]

Delete this space.

Parameters:: force (bool) – If True, force deletion even if the space contains items. If False (default), deletion fails if space is not empty.
Raises:: grpc.RpcError – If deletion fails (e.g., space not empty and force=False).
Return type:: None

Example

>>> # Delete empty space
>>> empty_space.delete()

>>> # Force delete space with contents
>>> old_space.delete(force=True)

get_parent_space()[source]

Get the parent space of this space.

Returns:

The parent Space object, or None if this is: a project-level root space.

Return type:

Optional[Space]

Example

>>> heroes = project.get_space("characters/heroes")
>>> chars = heroes.get_parent_space()  # Returns "characters" space
>>> root = chars.get_parent_space()  # Returns None (project root)

get_child_spaces()[source]

Get immediate child spaces of this space.

This is a convenience method equivalent to get_spaces(recursive=False).

Returns:: A list of direct child Space objects.
Return type:: List[Space]

Example

>>> assets = project.get_space("assets")
>>> children = assets.get_child_spaces()
>>> for child in children:
...     print(child.name)

get_project()[source]

Get the project that contains this space.

Returns:: The parent Project object.
Return type:: Project

Example

>>> space = kumiho.get_item("kref://my-project/assets/hero.model").get_space()
>>> project = space.get_project()
>>> print(project.name)
my-project