Identifiers¶

The identifiers module defines typed ID wrappers using typing.NewType. These are thin wrappers over str (UUID v4 values) that give the type-checker a way to enforce that, for example, a NodeId cannot be passed where a GraphId is expected.

Why typed IDs?¶

Without typed IDs, all entity identifiers are plain str, and bugs like the following are invisible to the type-checker:

# BUG: passing a graph_id where a node_id is expected
engine.remove_node(graph_id=workspace_id, node_id=graph_id)  # silently wrong

With NewType, static analysis tools (mypy, Pyright) catch this at development time.

Types¶

Factory Functions¶

Each NewType has a corresponding factory that generates a fresh UUID:

from knowledge_platform.core.identifiers import (
    new_workspace_id, new_graph_id, new_node_id, new_edge_id,
)

ws_id = new_workspace_id()  # WorkspaceId("3f2504e0-4f89-11d3-9a0c-0305e82c3301")
g_id  = new_graph_id()      # GraphId("...")

API Reference¶

new_edge_id() -> EdgeId

30
31
32

def new_edge_id() -> EdgeId:
    """Generate a fresh :class:`EdgeId`."""
    return EdgeId(str(uuid.uuid4()))

new_graph_id() -> GraphId

20
21
22

def new_graph_id() -> GraphId:
    """Generate a fresh :class:`GraphId`."""
    return GraphId(str(uuid.uuid4()))

new_node_id() -> NodeId

25
26
27

def new_node_id() -> NodeId:
    """Generate a fresh :class:`NodeId`."""
    return NodeId(str(uuid.uuid4()))

new_workspace_id() -> WorkspaceId

15
16
17

def new_workspace_id() -> WorkspaceId:
    """Generate a fresh :class:`WorkspaceId`."""
    return WorkspaceId(str(uuid.uuid4()))