kumiho.artifact

Artifact module for Kumiho asset management.

This module provides the Artifact class, which represents a file reference within a revision. Artifacts are the leaf nodes of the Kumiho hierarchy and point to actual files on local or network storage.

Kumiho follows a “BYO Storage” (Bring Your Own Storage) philosophy—it tracks file paths and metadata but does not upload or copy files.

Example

Working with artifacts:

import kumiho

# Get an artifact
artifact = kumiho.get_artifact(
    "kref://project/models/hero.model?r=1&a=mesh"
)

# Check the file location
print(f"File: {artifact.location}")

# Set metadata
artifact.set_metadata({
    "file_size": "125MB",
    "format": "FBX",
    "triangles": "2.5M"
})

# Navigate to parent objects
revision = artifact.get_revision()
item = artifact.get_item()

class kumiho.artifact.Artifact[source]

Bases: KumihoObject

A file reference within a revision in the Kumiho system.

Artifacts are the leaf nodes of the Kumiho hierarchy. They point to actual files on local disk, network storage, or cloud URIs. Kumiho tracks the path and metadata but does not upload or modify the files.

The artifact’s kref includes both revision and artifact name: kref://project/space/item.kind?r=1&a=artifact_name

kref

The unique reference URI for this artifact.

Type:: Kref

location

The file path or URI where the artifact is stored.

Type:: str

revision_kref

Reference to the parent revision.

Type:: Kref

item_kref

Reference to the parent item.

Type:: Optional[Kref]

created_at

ISO timestamp when the artifact was created.

Type:: Optional[str]

author

The user ID who created the artifact.

Type:: str

metadata

Custom metadata key-value pairs.

Type:: Dict[str, str]

deprecated

Whether the artifact is deprecated.

Type:: bool

username

Display name of the creator.

Type:: str

Example

Working with artifacts:

import kumiho

revision = kumiho.get_revision("kref://project/models/hero.model?r=1")

# Create artifacts
mesh = revision.create_artifact("mesh", "/assets/hero.fbx")
rig = revision.create_artifact("rig", "/assets/hero_rig.fbx")
textures = revision.create_artifact("textures", "smb://server/tex/hero/")

# Set metadata
mesh.set_metadata({
    "triangles": "2.5M",
    "format": "FBX 2020",
    "units": "centimeters"
})

# Set as default artifact
mesh.set_default()

# Get artifact by name
retrieved = revision.get_artifact("mesh")
print(f"Location: {retrieved.location}")

# Navigate hierarchy
item = mesh.get_item()
project = mesh.get_project()

__init__(pb_artifact, client)[source]

Initialize an Artifact from a protobuf response.

Parameters:

pb_artifact (ArtifactResponse) – The protobuf ArtifactResponse message.
client (_Client) – The client instance for making API calls.

Return type:

None

__repr__()[source]

Return a string representation of the Artifact.

Return type:: str

property name: str

Get the artifact name from its kref.

Returns:: The artifact name extracted from the kref URI.
Return type:: str

Example

>>> artifact = revision.get_artifact("mesh")
>>> print(artifact.name)  # "mesh"

set_metadata(metadata)[source]

Set or update metadata for this artifact.

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 Artifact object.
Return type:: Artifact

Example

>>> artifact.set_metadata({
...     "file_size": "125MB",
...     "format": "FBX 2020",
...     "triangles": "2.5M",
...     "software": "Maya 2024"
... })

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

>>> artifact.set_attribute("file_size", "125MB")
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

>>> artifact.get_attribute("file_size")
"125MB"

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

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

delete(force=False)[source]

Delete this artifact.

Parameters:: force (bool) – If True, force deletion. If False (default), normal deletion rules apply.
Raises:: grpc.RpcError – If deletion fails.
Return type:: None

Example

>>> artifact.delete()

set_deprecated(status)[source]

Set the deprecated status of this artifact.

Deprecated artifacts are hidden from default queries but remain accessible for historical reference.

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

Example

>>> artifact.set_deprecated(True)  # Hide from queries
>>> artifact.set_deprecated(False)  # Restore visibility

set_default()[source]

Set this artifact as the default for its revision.

The default artifact is used when resolving the revision’s kref without specifying an artifact name.

Example

>>> mesh = revision.create_artifact("mesh", "/assets/model.fbx")
>>> mesh.set_default()
>>> # Now resolving the revision kref returns this artifact's location

Return type:: None

get_revision()[source]

Get the parent revision of this artifact.

Returns:: The Revision object that contains this artifact.
Return type:: Revision

Example

>>> revision = artifact.get_revision()
>>> print(f"Revision {revision.number}")

get_item()[source]

Get the item that contains this artifact.

Returns:: The Item object.
Return type:: Item

Example

>>> item = artifact.get_item()
>>> print(item.item_name)

get_space()[source]

Get the space containing this artifact’s item.

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

Example

>>> space = artifact.get_space()
>>> print(space.path)

get_project()[source]

Get the project containing this artifact.

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

Example

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