kumiho.kref

Kref module for Kumiho artifact references.

This module provides the Kref class, which represents a Kumiho Artifact Reference—a URI-based unique identifier for any object in the Kumiho system.

Kref Format:

The kref URI follows this pattern:

kref://project/space/item.kind?r=REVISION&a=ARTIFACT

Components:

• project: The project name

• space: The space path (can be nested: space/subspace)

• item.kind: Item name and kind separated by dot

• ?r=REVISION: Optional revision number (default: 1)

• &a=ARTIFACT: Optional artifact name

Examples

Item kref:

kref://film-2024/characters/hero.model

Revision kref:

kref://film-2024/characters/hero.model?r=3

Artifact kref:

kref://film-2024/characters/hero.model?r=3&a=mesh

Usage:

import kumiho
from kumiho import Kref

# Parse a kref
kref = Kref("kref://project/models/hero.model?r=2&a=mesh")

# Extract components
print(kref.get_space())        # "project/models"
print(kref.get_item_name())    # "hero.model"
print(kref.get_kind())         # "model"
print(kref.get_revision())     # 2
print(kref.get_artifact_name()) # "mesh"

# Use as string
print(f"Reference: {kref}")  # Works like a string

exception kumiho.kref.KrefValidationError

Bases: ValueError

Raised when a Kref URI is invalid or contains malicious patterns.

kumiho.kref.validate_kref(uri)

Validate a Kref URI for security and correctness.

Checks for: - Proper kref:// scheme - No path traversal patterns (..) - No control characters - Valid path segment format

Parameters:

uri (str) – The kref URI to validate.

Raises:

KrefValidationError – If the URI is invalid or contains malicious patterns.

Return type:

None

Example:

from kumiho.kref import validate_kref, KrefValidationError

try:
    validate_kref("kref://project/space/item.kind?r=1")
except KrefValidationError as e:
    print(f"Invalid kref: {e}")

kumiho.kref.is_valid_kref(uri)

Check if a Kref URI is valid without raising exceptions.

Parameters:

uri (str) – The kref URI to validate.

Return type:

bool

Returns:

True if the URI is valid, False otherwise.

Example:

from kumiho.kref import is_valid_kref

if is_valid_kref("kref://project/space/item.kind"):
    print("Valid!")

class kumiho.kref.Kref

Bases: str

A Kumiho Artifact Reference (URI-based unique identifier).

Kref is a subclass of str, so it behaves like a string but provides utility methods for parsing and extracting components from the URI.

The kref format is:

kref://project/space/item.kind?r=REVISION&a=ARTIFACT

uri

The URI string (for backward compatibility).

Type:

str

Example:

from kumiho import Kref

# Create from string
kref = Kref("kref://my-project/assets/hero.model?r=2")

# Use as string (since Kref extends str)
print(kref)  # kref://my-project/assets/hero.model?r=2

# Parse components
print(kref.get_space())    # "my-project/assets"
print(kref.get_revision()) # 2

# Compare with strings
if kref == "kref://my-project/assets/hero.model?r=2":
    print("Match!")

Note

Since Kref is a string subclass, you can use it anywhere a string is expected. All string methods work normally.

static __new__(cls, uri, *, validate=True)

Create a new Kref instance.

Parameters:

• uri (str) – The kref URI string.

• validate (bool) – Whether to validate the URI (default: True). Set to False for trusted internal sources.

Returns:

A Kref instance that is also a string.

Return type:

Kref

Raises:

KrefValidationError – If validate=True and the URI is invalid.

Example

>>> kref = Kref("kref://project/space/item.kind?r=1")
>>> isinstance(kref, str)
True

classmethod from_pb(pb_kref)

Create a Kref from a protobuf message.

This is used for krefs received from the server, which are trusted.

Parameters:

pb_kref (Kref) – The protobuf Kref message.

Returns:

A Kref instance.

Return type:

Kref

property uri: str

Get the URI string.

This property exists for backward compatibility with older code that accessed .uri directly.

Returns:

The kref URI string.

Return type:

str

to_pb()

Convert to a protobuf Kref object.

Used internally for gRPC communication.

Returns:

A protobuf Kref message.

Return type:

kumiho_pb2.Kref

get_path()

Extract the path component from the URI.

Returns the part after kref:// and before any query parameters.

Returns:

The path (e.g., “project/space/item.kind”).

Return type:

str

Example

>>> Kref("kref://project/models/hero.model?r=1").get_path()
'project/models/hero.model'

get_space()

Extract the space path from the URI.

Returns the path up to but not including the item name.

Returns:

The space path (e.g., “project/models”).

Return type:

str

Example

>>> Kref("kref://project/models/hero.model").get_space()
'project/models'

get_item_name()

Extract the item name with kind from the URI.

Returns:

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

Return type:

str

Example

>>> Kref("kref://project/models/hero.model").get_item_name()
'hero.model'

get_kind()

Extract the item kind from the URI.

Returns:

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

Return type:

str

Example

>>> Kref("kref://project/models/hero.model").get_kind()
'model'

get_revision()

Extract the revision number from the URI query string.

Returns:

The revision number, or 1 if not specified.

Return type:

int

Example

>>> Kref("kref://project/models/hero.model?r=3").get_revision()
3
>>> Kref("kref://project/models/hero.model").get_revision()
1

get_artifact_name()

Extract the artifact name from the URI query string.

Returns:

The artifact name if present, None otherwise.

Return type:

Optional[str]

Example

>>> Kref("kref://project/models/hero.model?r=1&a=mesh").get_artifact_name()
'mesh'
>>> Kref("kref://project/models/hero.model?r=1").get_artifact_name()
None

__repr__()

Return a developer-friendly string representation.

Return type:

str

__eq__(other)

Compare with another Kref or string.

Return type:

bool

Parameters:

other (object)

__hash__()

Return hash for use in sets and dicts.

Return type:

int