digitalhub 0.13.0b3__py3-none-any.whl → 0.13.0b4__py3-none-any.whl

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

@@ -9,17 +9,28 @@ from digitalhub.entities._commons.enums import EntityTypes
 
 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
@@ -53,17 +64,25 @@ def parse_entity_key(key: str) -> tuple[str, str, str, str | None, str]:
 
 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 +90,25 @@ 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