kumiho.item

Item module for Kumiho asset management.

This module provides the Item class, which represents a versioned asset in the Kumiho system. Items are the core entities that get versioned, and each revision can have multiple artifacts (file references).

Example

Working with items and revisions:

import kumiho

# Get an item
item = kumiho.get_item("kref://my-project/models/hero.model")

# Create a new revision
v1 = item.create_revision(metadata={"artist": "john"})

# Add artifacts to the revision
v1.create_artifact("mesh", "/assets/hero_v1.fbx")
v1.create_artifact("rig", "/assets/hero_v1_rig.fbx")

# Tag the revision
v1.tag("approved")

# Get all revisions
for revision in item.get_revisions():
    print(f"v{revision.number}: {revision.tags}")

class kumiho.item.Item[source]

Bases: KumihoObject

A versioned asset in the Kumiho system.

Items represent assets that can have multiple revisions, such as 3D models, textures, workflows, or any other type of creative content. Each item belongs to a space and is identified by a combination of name and kind.

The item’s kref (Kumiho Reference) is a URI that uniquely identifies it: kref://project/space/item.kind

kref

The unique reference URI for this item.

Type:: Kref

name

The full name including kind (e.g., “hero.model”).

Type:: str

item_name

The base name of the item (e.g., “hero”).

Type:: str

kind

The kind of item (e.g., “model”, “texture”).

Type:: str

created_at

ISO timestamp when the item was created.

Type:: Optional[str]

author

The user ID who created the item.

Type:: str

metadata

Custom metadata key-value pairs.

Type:: Dict[str, str]

deprecated

Whether the item is deprecated.

Type:: bool

username

Display name of the creator.

Type:: str

Example

Basic item operations:

import kumiho

# Get item by kref
item = kumiho.get_item("kref://film/chars/hero.model")

# Create revisions
v1 = item.create_revision()
v2 = item.create_revision(metadata={"notes": "Updated mesh"})

# Get specific revision
v1 = item.get_revision(1)
latest = item.get_latest_revision()

# Get revision by tag
approved = item.get_revision_by_tag("approved")

# Get revision at a specific time
historical = item.get_revision_by_time("202312011200")

# Set metadata
item.set_metadata({"status": "final", "priority": "high"})

# Deprecate the item
item.set_deprecated(True)

__init__(pb_item, client)[source]

Initialize an Item from a protobuf response.

Parameters:

pb_item (ItemResponse) – The protobuf ItemResponse message.
client (_Client) – The client instance for making API calls.

Return type:

None

__repr__()[source]

Return a string representation of the Item.

Return type:: str

create_revision(metadata=None, number=0)[source]

Create a new revision of this item.

Revisions are automatically numbered sequentially. Each revision starts with the “latest” tag, which moves to the newest revision.

Parameters:

metadata (Optional[Dict[str, str]]) – Optional metadata for the revision (e.g., artist notes, render settings, software versions).
number (int) – Specific revision number to use. If 0 (default), auto-assigns the next available number.

Returns:

The newly created Revision object.

Return type:

Revision

Example

>>> # Auto-numbered revision
>>> v1 = item.create_revision()
>>> v2 = item.create_revision(metadata={"artist": "jane"})

>>> # Specific revision number (use with caution)
>>> v5 = item.create_revision(number=5)

get_revisions()[source]

Get all revisions of this item.

Returns:: A list of Revision objects, ordered by revision number.
Return type:: List[Revision]

Example

>>> revisions = item.get_revisions()
>>> for v in revisions:
...     print(f"v{v.number}: created {v.created_at}")

get_revision(revision_number)[source]

Get a specific revision by its number.

Parameters:: revision_number (int) – The revision number to retrieve (1-based).
Returns:: The Revision object if found, None otherwise.
Return type:: Optional[Revision]

Example

>>> v3 = item.get_revision(3)
>>> if v3:
...     artifacts = v3.get_artifacts()

get_latest_revision()[source]

Get the latest revision of this item.

The latest revision is the one with the “latest” tag, or if none exists, the revision with the highest number.

Returns:

The latest Revision object, or None if no: revisions exist.

Return type:

Optional[Revision]

Example

>>> latest = item.get_latest_revision()
>>> if latest:
...     print(f"Latest: v{latest.number}")

get_space()[source]

Get the space that contains this item.

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

Example

>>> item = kumiho.get_item("kref://project/chars/hero.model")
>>> space = item.get_space()
>>> print(space.path)  # "/project/chars"

get_project()[source]

Get the project that contains this item.

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

Example

>>> project = item.get_project()
>>> print(project.name)

get_revision_by_tag(tag)[source]

Get a revision by its tag.

Common tags include “latest”, “published”, “approved”, etc. Custom tags can be applied to revisions using Revision.tag().

Parameters:: tag (str) – The tag to search for.
Returns:: The Revision object if found, None otherwise.
Return type:: Optional[Revision]

Example

>>> approved = item.get_revision_by_tag("approved")
>>> published = item.get_revision_by_tag("published")

get_revision_by_time(time, tag=None)[source]

Get the revision that had a specific tag at a given time.

This is essential for reproducible builds and historical queries. By combining a tag (like “published”) with a timestamp, you can answer questions like “What was the published version on June 1st?”

Parameters:

time (Union[str, datetime]) – The time as a datetime object, or a string in either YYYYMMDDHHMM format (e.g., “202312251430”) or RFC3339 format (e.g., “2023-12-25T14:30:00Z”).
tag (Optional[str]) – Optional tag to filter by. Common values: - “published”: Find the published revision at that time - “approved”: Find the approved revision at that time - None (default): Find the latest revision at that time

Returns:

The Revision that had the specified tag: at that time, or None if not found.

Return type:

Optional[Revision]

Example

>>> from datetime import datetime, timezone

>>> # Get the published revision as of June 1st, 2024
>>> june_1 = datetime(2024, 6, 1, tzinfo=timezone.utc)
>>> rev = item.get_revision_by_time(june_1, tag="published")

>>> # Get whatever was latest at a specific time
>>> rev = item.get_revision_by_time("202312251430")

>>> # Using RFC3339 format with published tag
>>> rev = item.get_revision_by_time(
...     "2024-06-01T00:00:00Z",
...     tag="published"
... )

Note

This is particularly useful with the “published” tag since published revisions are immutable and represent stable, approved versions suitable for downstream consumption.

peek_next_revision()[source]

Get the next revision number that would be assigned.

This is useful for previewing revision numbers before creating revisions, such as for naming files or planning workflows.

Returns:: The next revision number.
Return type:: int

Example

>>> next_num = item.peek_next_revision()
>>> print(f"Next revision will be v{next_num}")

set_metadata(metadata)[source]

Set or update metadata for this item.

Metadata is merged with existing metadata—existing keys are overwritten and new keys are added.

Parameters:: metadata (Dict[str, str]) – Dictionary of metadata key-value pairs.
Returns:: The updated Item object.
Return type:: Item

Example

>>> item.set_metadata({
...     "status": "final",
...     "department": "modeling",
...     "complexity": "high"
... })

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

>>> item.set_attribute("status", "final")
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

>>> item.get_attribute("status")
"final"

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

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

delete(force=False)[source]

Delete this item.

Parameters:: force (bool) – If True, permanently delete the item and all its revisions. If False (default), deletion may fail if the item has revisions.
Raises:: grpc.RpcError – If deletion fails.
Return type:: None

Example

>>> # Delete item (fails if has revisions)
>>> item.delete()

>>> # Force delete with all revisions
>>> item.delete(force=True)

set_deprecated(status)[source]

Set the deprecated status of this item.

Deprecated items are hidden from default searches but remain accessible for historical reference.

Parameters:: status (bool) – True to deprecate, False to restore.
Return type:: None

Example

>>> item.set_deprecated(True)  # Hide from searches
>>> item.set_deprecated(False)  # Restore visibility