digitalhub 0.13.0b3__py3-none-any.whl → 0.14.9__py3-none-any.whl

digitalhub/entities/_base/runtime_entity/builder.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+from digitalhub.entities._commons.utils import KindAction
 from digitalhub.utils.exceptions import EntityError
 
 
@@ -13,16 +14,40 @@ class RuntimeEntityBuilder:
     """
 
     EXECUTABLE_KIND: str = None
-    TASKS_KINDS: dict = None
-    RUN_KIND: str = None
+    TASKS_KINDS: list[KindAction] = None
+    RUN_KINDS: list[KindAction] = None
 
     def __init__(self) -> None:
-        if self.EXECUTABLE_KIND is None:
-            raise EntityError("EXECUTABLE_KIND must be set")
-        if self.TASKS_KINDS is None:
-            raise EntityError("TASKS_KINDS must be set")
-        if self.RUN_KIND is None:
-            raise EntityError("RUN_KIND must be set")
+        self._validate()
+
+    def _validate(self) -> None:
+        """
+        Validate the entity.
+        """
+        for attr_name in ["EXECUTABLE_KIND", "TASKS_KINDS", "RUN_KINDS"]:
+            value = getattr(self, attr_name)
+            if value is None:
+                raise EntityError(f"{attr_name} must be set")
+
+        for attr_name in ["TASKS_KINDS", "RUN_KINDS"]:
+            self._instance_validation(getattr(self, attr_name))
+
+    def _instance_validation(self, attribute: list[KindAction]) -> None:
+        """
+        Validate if the attribute is a list of KindAction.
+
+        Parameters
+        ----------
+        attribute : list[KindAction]
+            Attribute to validate.
+        """
+        if not isinstance(attribute, list):
+            raise EntityError(f"{attribute} must be a list")
+        for i in attribute:
+            if not isinstance(i, KindAction):
+                raise EntityError(f"{attribute} must be a list of KindAction")
+            if i.kind is None:
+                raise EntityError(f"{attribute} must be a list of KindAction with kind set")
 
     def get_action_from_task_kind(self, task_kind: str) -> str:
         """
@@ -39,8 +64,8 @@ class RuntimeEntityBuilder:
             Action.
         """
         for task in self.TASKS_KINDS:
-            if task["kind"] == task_kind:
-                return task["action"]
+            if task.kind == task_kind:
+                return task.action
         msg = f"Task kind {task_kind} not allowed."
         raise EntityError(msg)
 
@@ -59,21 +84,30 @@ class RuntimeEntityBuilder:
             Task kinds.
         """
         for task in self.TASKS_KINDS:
-            if task["action"] == action:
-                return task["kind"]
+            if task.action == action:
+                return task.kind
         msg = f"Action {action} not allowed."
         raise EntityError(msg)
 
-    def get_run_kind(self) -> str:
+    def get_run_kind_from_action(self, action: str) -> str:
         """
-        Get run kind.
+        Get run kind from action.
+
+        Parameters
+        ----------
+        action : str
+            Action.
 
         Returns
         -------
         str
             Run kind.
         """
-        return self.RUN_KIND
+        for run in self.RUN_KINDS:
+            if run.action == action:
+                return run.kind
+        msg = f"Action {action} not allowed."
+        raise EntityError(msg)
 
     def get_executable_kind(self) -> str:
         """
@@ -95,8 +129,9 @@ class RuntimeEntityBuilder:
         list[str]
             All kinds.
         """
-        task_kinds = [i["kind"] for i in self.TASKS_KINDS]
-        return [self.EXECUTABLE_KIND, self.RUN_KIND, *task_kinds]
+        task_kinds = [i.kind for i in self.TASKS_KINDS]
+        run_kinds = [i.kind for i in self.RUN_KINDS]
+        return [self.EXECUTABLE_KIND, *run_kinds, *task_kinds]
 
     def get_all_actions(self) -> list[str]:
         """
@@ -107,4 +142,4 @@ class RuntimeEntityBuilder:
         list[str]
             All actions.
         """
-        return [i["action"] for i in self.TASKS_KINDS]
+        return [i.action for i in self.TASKS_KINDS]

digitalhub/entities/_base/unversioned/entity.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._base.context.entity import ContextEntity
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import context_processor
 
 if typing.TYPE_CHECKING:
     from digitalhub.entities._base.entity.metadata import Metadata

digitalhub/entities/_base/versioned/entity.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._base.context.entity import ContextEntity
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import context_processor
 
 if typing.TYPE_CHECKING:
     from digitalhub.entities._base.entity.metadata import Metadata

digitalhub/entities/_commons/enums.py

@@ -32,6 +32,7 @@ class Relationship(Enum):
     PRODUCEDBY = "produced_by"
     CONSUMES = "consumes"
     RUN_OF = "run_of"
+    STEP_OF = "step_of"
 
 
 class State(Enum):
@@ -63,37 +64,6 @@ class State(Enum):
     UPLOADING = "UPLOADING"
 
 
-class ApiCategories(Enum):
-    """
-    Entity categories.
-    """
-
-    BASE = "base"
-    CONTEXT = "context"
-
-
-class BackendOperations(Enum):
-    """
-    Backend operations.
-    """
-
-    CREATE = "create"
-    READ = "read"
-    READ_ALL_VERSIONS = "read_all_versions"
-    UPDATE = "update"
-    DELETE = "delete"
-    LIST = "list"
-    LIST_FIRST = "list_first"
-    STOP = "stop"
-    RESUME = "resume"
-    DATA = "data"
-    FILES = "files"
-    LOGS = "logs"
-    SEARCH = "search"
-    SHARE = "share"
-    METRICS = "metrics"
-
-
 class EntityKinds(Enum):
     """
     Entity kinds.

digitalhub/entities/_commons/metrics.py

@@ -13,7 +13,15 @@ MetricType = Union[float, int, list[Union[float, int]]]
 
 class Metric(BaseModel):
     """
-    Metric.
+    Pydantic model for validating metric values.
+
+    This model ensures that metric values are of the correct type,
+    accepting single numeric values or lists of numeric values.
+
+    Attributes
+    ----------
+    value : MetricType
+        The metric value, which can be a float, int, or list of floats/ints.
     """
 
     value: MetricType
@@ -21,17 +29,25 @@ class Metric(BaseModel):
 
 def validate_metric_value(value: Any) -> MetricType:
     """
-    Validate metric value.
+    Validate and convert a value to a proper metric type.
+
+    Uses Pydantic validation to ensure the input value conforms to
+    the MetricType specification (float, int, or list of floats/ints).
 
     Parameters
     ----------
     value : Any
-        The value to validate.
+        The value to validate and convert.
 
     Returns
     -------
     MetricType
-        The validated value.
+        The validated metric value.
+
+    Raises
+    ------
+    ValueError
+        If the value cannot be converted to a valid metric type.
     """
     try:
         return Metric(value=value).value
@@ -47,23 +63,30 @@ def set_metrics(
     single_value: bool,
 ) -> dict[str, MetricType]:
     """
-    Set metric value.
+    Set or update a metric value in the metrics dictionary.
+
+    This function routes to appropriate handling based on the value type
+    and the single_value flag. It can handle single values, lists, and
+    appending to existing metrics.
 
     Parameters
     ----------
     metrics : dict[str, MetricType]
-        The metrics dictionary.
+        The metrics dictionary to update.
     key : str
-        The key of the entity.
+        The metric key to set or update.
     value : Any
-        The value to set.
+        The value to set for the metric.
     overwrite : bool
-        Whether to overwrite the metric.
+        Whether to overwrite existing metrics.
+    single_value : bool
+        Whether to treat the value as a single metric rather than
+        appending to a list.
 
     Returns
     -------
     dict[str, MetricType]
-        The metrics dictionary.
+        The updated metrics dictionary.
     """
     if isinstance(value, list):
         return handle_metric_list(metrics, key, value, overwrite)
@@ -79,23 +102,26 @@ def handle_metric_single(
     overwrite: bool,
 ) -> dict:
     """
-    Handle metric single value.
+    Handle setting a single metric value.
+
+    Sets or overwrites a metric with a single numeric value. If the key
+    already exists and overwrite is False, the existing value is preserved.
 
     Parameters
     ----------
     metrics : dict[str, MetricType]
-        Metrics dictionary.
+        The metrics dictionary to update.
     key : str
-        Key of the metric.
-    value : float
-        Value of the metric.
+        The metric key to set.
+    value : float | int
+        The single numeric value to set.
     overwrite : bool
-        If True, overwrite existing metric.
+        Whether to overwrite an existing metric with the same key.
 
     Returns
     -------
     dict
-        Metrics dictionary.
+        The updated metrics dictionary.
     """
     if key not in metrics or overwrite:
         metrics[key] = value
@@ -109,23 +135,27 @@ def handle_metric_list_append(
     overwrite: bool,
 ) -> dict:
     """
-    Handle metric list append.
+    Handle appending a single value to a metric list.
+
+    If the metric doesn't exist or overwrite is True, creates a new list
+    with the single value. If the metric exists as a list, appends to it.
+    If the metric exists as a single value, converts it to a list and appends.
 
     Parameters
     ----------
     metrics : dict[str, MetricType]
-        Metrics dictionary.
+        The metrics dictionary to update.
     key : str
-        Key of the metric.
-    value : float
-        Value of the metric.
+        The metric key to append to.
+    value : float | int
+        The numeric value to append.
     overwrite : bool
-        If True, overwrite existing metric.
+        Whether to overwrite an existing metric instead of appending.
 
     Returns
     -------
     dict
-        Metrics dictionary.
+        The updated metrics dictionary.
     """
     if key not in metrics or overwrite:
         metrics[key] = [value]
@@ -143,23 +173,27 @@ def handle_metric_list(
     overwrite: bool,
 ) -> dict:
     """
-    Handle metric list.
+    Handle setting or extending a metric with a list of values.
+
+    If the metric doesn't exist or overwrite is True, sets the metric to
+    the provided list. If the metric exists and overwrite is False, extends
+    the existing list with the new values.
 
     Parameters
     ----------
     metrics : dict[str, MetricType]
-        Metrics dictionary.
+        The metrics dictionary to update.
     key : str
-        Key of the metric.
+        The metric key to set or extend.
     value : list[int | float]
-        Value of the metric.
+        The list of numeric values to set or extend with.
     overwrite : bool
-        If True, overwrite existing metric.
+        Whether to overwrite an existing metric instead of extending it.
 
     Returns
     -------
     dict
-        Metrics dictionary.
+        The updated metrics dictionary.
     """
     if key not in metrics or overwrite:
         metrics[key] = value

digitalhub/entities/_commons/utils.py

@@ -4,66 +4,130 @@
 
 from __future__ import annotations
 
+import re
+from collections import namedtuple
+
 from digitalhub.entities._commons.enums import EntityTypes
 
+KindAction = namedtuple("KindAction", ["kind", "action"])
+
+
+KEY_PATTERN_WITH_ID = "store://([^/]+)/([^/]+)/([^/]+)/([^:]+):(.+)"
+KEY_PATTERN_NO_ID = "store://([^/]+)/([^/]+)/([^/]+)/([^:]+)"
+
+
+def is_valid_key(key: str) -> bool:
+    """
+    Check if an entity key is valid.
+
+    Parameters
+    ----------
+    key : str
+        The entity key to validate.
+
+    Returns
+    -------
+    bool
+        True if the key is valid, False otherwise.
+    """
+    return bool(re.fullmatch(KEY_PATTERN_WITH_ID, key) or re.fullmatch(KEY_PATTERN_NO_ID, key))
+
+
+def sanitize_unversioned_key(key: str) -> str:
+    """
+    Sanitize an unversioned entity key (from name:id to id).
+
+    Parameters
+    ----------
+    key : str
+        The unversioned entity key.
+
+    Returns
+    -------
+    str
+        The sanitized entity key with version.
+    """
+    splt = key.split("/")[2:]
+    ent_id = splt[-1].split(":")[0]
+    return "store://" + "/".join(splt[:-1] + [ent_id])
+
 
 def parse_entity_key(key: str) -> tuple[str, str, str, str | None, str]:
     """
-    Parse the entity key. Returns project, entity type, kind, name and uuid.
+    Parse an entity key into its constituent components.
+
+    Extracts project name, entity type, kind, name, and UUID from a
+    standardized entity key format. Handles special cases for tasks
+    and runs which don't have name components.
 
     Parameters
     ----------
     key : str
-        The entity key.
+        The entity key in format "store://project/type/kind/name:uuid"
+        or "store://project/type/kind/uuid" for tasks and runs.
 
     Returns
     -------
     tuple[str, str, str, str | None, str]
-        Project, entity type, kind, name and uuid.
+        A tuple containing (project, entity_type, kind, name, uuid).
+        The name component is None for tasks and runs.
+
+    Raises
+    ------
+    ValueError
+        If the key format is invalid or cannot be parsed.
     """
-    try:
-        # Remove "store://" from the key
-        key = key.replace("store://", "")
+    if not is_valid_key(key):
+        raise ValueError("Invalid entity key format.")
+
+    # Remove "store://" from the key
+    key = key.replace("store://", "")
 
-        # Split the key into parts
-        parts = key.split("/")
+    # Split the key into parts
+    parts = key.split("/")
 
-        # The project is the first part
-        project = parts[0]
+    # The project is the first part
+    project = parts[0]
 
-        # The entity type is the second part
-        entity_type = parts[1]
+    # The entity type is the second part
+    entity_type = parts[1]
 
-        # The kind is the third part
-        kind = parts[2]
+    # The kind is the third part
+    kind = parts[2]
 
-        # Tasks and runs have no name and uuid
-        if entity_type in (EntityTypes.TASK.value, EntityTypes.RUN.value):
-            name = None
-            uuid = parts[3]
+    # Tasks and runs have no name and uuid
+    if entity_type in (EntityTypes.TASK.value, EntityTypes.RUN.value):
+        name = None
+        uuid = parts[3]
 
-        # The name and uuid are separated by a colon in the last part
-        else:
-            name, uuid = parts[3].split(":")
+    # The name and uuid are separated by a colon in the last part
+    else:
+        name, uuid = parts[3].split(":")
 
-        return project, entity_type, kind, name, uuid
-    except Exception as e:
-        raise ValueError("Invalid key format.") from e
+    return project, entity_type, kind, name, uuid
 
 
 def get_entity_type_from_key(key: str) -> str:
     """
-    Get entity type from key.
+    Extract the entity type from an entity key.
+
+    Parses the entity key and returns only the entity type component,
+    which indicates the kind of entity (artifact, function, run, etc.).
 
     Parameters
     ----------
     key : str
-        The key of the entity.
+        The entity key in standardized format.
 
     Returns
     -------
     str
-        The entity type.
+        The entity type extracted from the key.
+
+    Raises
+    ------
+    ValueError
+        If the key format is invalid or cannot be parsed.
     """
     _, entity_type, _, _, _ = parse_entity_key(key)
     return entity_type
@@ -71,17 +135,42 @@ def get_entity_type_from_key(key: str) -> str:
 
 def get_project_from_key(key: str) -> str:
     """
-    Get project from key.
+    Extract the project name from an entity key.
+
+    Parses the entity key and returns only the project component,
+    which identifies the project context the entity belongs to.
 
     Parameters
     ----------
     key : str
-        The key of the entity.
+        The entity key in standardized format.
 
     Returns
     -------
     str
-        The project.
+        The project name extracted from the key.
+
+    Raises
+    ------
+    ValueError
+        If the key format is invalid or cannot be parsed.
     """
     project, _, _, _, _ = parse_entity_key(key)
     return project
+
+
+def map_actions(kind_action_list: list[tuple[str, str]]) -> list[KindAction]:
+    """
+    Build task actions as KindAction namedtuples.
+
+    Parameters
+    ----------
+    kind_action_list : list[tuple[str, str]]
+        List of kind-action couples.
+
+    Returns
+    -------
+    list[KindAction]
+        Returns the task actions as KindAction namedtuples.
+    """
+    return [KindAction(kind, action) for (kind, action) in kind_action_list]