digitalhub 0.13.0b3__py3-none-any.whl → 0.14.0b0__py3-none-any.whl

digitalhub/entities/_processors/utils.py

@@ -8,7 +8,7 @@ import typing
 
 from digitalhub.context.api import get_context
 from digitalhub.entities._commons.enums import ApiCategories, BackendOperations, EntityTypes
-from digitalhub.entities._commons.utils import get_project_from_key, parse_entity_key
+from digitalhub.entities._commons.utils import get_project_from_key, is_valid_key, parse_entity_key
 from digitalhub.factory.factory import factory
 from digitalhub.stores.client.api import get_client
 from digitalhub.utils.exceptions import ContextError, EntityError, EntityNotExistsError
@@ -26,25 +26,38 @@ def parse_identifier(
     entity_id: str | None = None,
 ) -> tuple[str, str, str | None, str | None, str | None]:
     """
-    Parse entity identifier.
+    Parse and validate entity identifier into its components.
+
+    Processes an entity identifier that can be either a full entity key
+    (store://) or a simple entity name. When using a simple name,
+    additional parameters must be provided for proper identification.
 
     Parameters
     ----------
     identifier : str
-        Entity key (store://...) or entity name.
-    project : str
-        Project name.
-    entity_type : str
-        Entity type.
-    entity_id : str
-        Entity ID.
+        The entity identifier to parse. Can be either a full entity key
+        (store://project/entity_type/kind/name:id) or a simple entity name.
+    project : str, optional
+        The project name. Required when identifier is not a full key.
+    entity_type : str, optional
+        The entity type. Required when identifier is not a full key.
+    entity_kind : str, optional
+        The entity kind specification.
+    entity_id : str, optional
+        The entity version identifier.
 
     Returns
     -------
     tuple[str, str, str | None, str | None, str | None]
-        Project name, entity type, entity kind, entity name, entity ID.
+        A tuple containing (project_name, entity_type, entity_kind,
+        entity_name, entity_id) parsed from the identifier.
+
+    Raises
+    ------
+    ValueError
+        If identifier is not a full key and project or entity_type is None.
     """
-    if not identifier.startswith("store://"):
+    if not is_valid_key(identifier):
         if project is None or entity_type is None:
             raise ValueError("Project and entity type must be specified.")
         return project, entity_type, entity_kind, identifier, entity_id
@@ -56,21 +69,31 @@ def get_context_from_identifier(
     project: str | None = None,
 ) -> Context:
     """
-    Get context from project.
+    Retrieve context instance from entity identifier or project name.
+
+    Extracts project information from the identifier and returns the
+    corresponding context. If the identifier is not a full key, the
+    project parameter must be provided explicitly.
 
     Parameters
     ----------
     identifier : str
-        Entity key (store://...) or entity name.
-    project : str
-        Project name.
+        The entity identifier to extract context from. Can be either
+        a full entity key (store://...) or a simple entity name.
+    project : str, optional
+        The project name. Required when identifier is not a full key.
 
     Returns
     -------
     Context
-        Context.
+        The context instance associated with the identified project.
+
+    Raises
+    ------
+    EntityError
+        If identifier is not a full key and project parameter is None.
     """
-    if not identifier.startswith("store://"):
+    if not is_valid_key(identifier):
         if project is None:
             raise EntityError("Specify project if you do not specify entity key.")
     else:
@@ -83,19 +106,26 @@ def get_context_from_project(
     project: str,
 ) -> Context:
     """
-    Check if the given project is in the context.
-    Otherwise try to get the project from remote.
-    Finally return the client.
+    Retrieve context for a project, fetching from remote if necessary.
+
+    Attempts to get the project context from the local cache first.
+    If the project is not found locally, tries to fetch it from the
+    remote backend and create the context.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project to get context for.
 
     Returns
     -------
     Context
-        Context.
+        The context instance for the specified project.
+
+    Raises
+    ------
+    ContextError
+        If the project cannot be found locally or remotely.
     """
     try:
         return get_context(project)
@@ -105,19 +135,28 @@ def get_context_from_project(
 
 def get_context_from_remote(
     project: str,
-) -> Client:
+) -> Context:
     """
-    Get context from remote.
+    Fetch project context from remote backend and create local context.
+
+    Retrieves project information from the remote backend, builds the
+    project entity locally, and returns the corresponding context.
+    Used when a project is not available in the local context cache.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project to fetch from remote.
 
     Returns
     -------
-    Client
-        Client.
+    Context
+        The context instance created from the remote project data.
+
+    Raises
+    ------
+    ContextError
+        If the project is not found on the remote backend.
     """
     try:
         client = get_client()
@@ -135,23 +174,28 @@ def _read_base_entity(
     **kwargs,
 ) -> dict:
     """
-    Read object from backend.
+    Read entity data from the backend API.
+
+    Internal utility function that performs a base-level entity read
+    operation through the client API. Builds the appropriate API
+    endpoint and retrieves the entity data as a dictionary.
 
     Parameters
     ----------
     client : Client
-        Client instance.
+        The client instance to use for the API request.
     entity_type : str
-        Entity type.
+        The type of entity to read (e.g., 'project', 'function').
     entity_name : str
-        Entity name.
+        The name identifier of the entity to retrieve.
     **kwargs : dict
-        Parameters to pass to the API call.
+        Additional parameters to pass to the API call, such as
+        version specifications or query filters.
 
     Returns
     -------
     dict
-        Object instance.
+        Dictionary containing the entity data retrieved from the backend.
     """
     api = client.build_api(
         ApiCategories.BASE.value,

digitalhub/entities/artifact/crud.py

@@ -238,14 +238,25 @@ def list_artifacts(project: str, **kwargs) -> list[Artifact]:
     )
 
 
-def import_artifact(file: str) -> Artifact:
+def import_artifact(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Artifact:
     """
-    Import object from a YAML file and create a new object into the backend.
+    Import an object from a YAML file or from a storage key.
 
     Parameters
     ----------
     file : str
-        Path to YAML file.
+        Path to the YAML file.
+    key : str
+        Entity key (store://...).
+    reset_id : bool
+        Flag to determine if the ID of executable entities should be reset.
+    context : str
+        Project name to use for context resolution.
 
     Returns
     -------
@@ -256,7 +267,12 @@ def import_artifact(file: str) -> Artifact:
     --------
     >>> obj = import_artifact("my-artifact.yaml")
     """
-    return context_processor.import_context_entity(file)
+    return context_processor.import_context_entity(
+        file,
+        key,
+        reset_id,
+        context,
+    )
 
 
 def load_artifact(file: str) -> Artifact:

digitalhub/entities/artifact/utils.py

@@ -6,25 +6,32 @@ from __future__ import annotations
 
 from typing import Any
 
-from digitalhub.entities._base.entity._constructors.uuid import build_uuid
 from digitalhub.entities._base.material.utils import build_log_path_from_source, eval_local_source
 from digitalhub.entities._commons.enums import EntityTypes
+from digitalhub.entities._constructors.uuid import build_uuid
 
 
 def eval_source(
     source: str | list[str] | None = None,
 ) -> Any:
     """
-    Evaluate if source is local.
+    Evaluate whether the source is local or remote.
+
+    Determines if the provided source(s) reference local files or
+    remote resources. This evaluation affects how the artifact
+    will be processed and stored.
 
     Parameters
     ----------
-    source : str | list[str]
-        Source(s).
+    source : str, list[str], or None, optional
+        The source specification(s) to evaluate. Can be a single
+        source string, a list of source strings, or None.
 
     Returns
     -------
-    None
+    Any
+        The result of the local source evaluation, indicating
+        whether the source is local or remote.
     """
     return eval_local_source(source)
 
@@ -37,25 +44,33 @@ def process_kwargs(
     **kwargs,
 ) -> dict:
     """
-    Process spec kwargs.
+    Process and enhance specification parameters for artifact creation.
+
+    Processes the keyword arguments for artifact specification, handling
+    path generation and UUID assignment. If no path is provided, generates
+    a unique path based on project, entity type, name, and source.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project.
     name : str
-        Object name.
-    source : str
-        Source(s).
-    path : str
-        Destination path of the entity. If not provided, it's generated.
+        The name of the artifact entity.
+    source : str or list[str]
+        The source specification(s) for the artifact content.
+        Can be a single source or multiple sources.
+    path : str, optional
+        The destination path for the artifact entity.
+        If None, a path will be automatically generated.
     **kwargs : dict
-        Spec parameters.
+        Additional specification parameters to be processed
+        and passed to the artifact creation.
 
     Returns
     -------
     dict
-        Kwargs updated.
+        The updated kwargs dictionary with processed path
+        and UUID information included.
     """
     if path is None:
         uuid = build_uuid()

digitalhub/entities/dataitem/crud.py

@@ -264,14 +264,25 @@ def list_dataitems(project: str, **kwargs) -> list[Dataitem]:
     )
 
 
-def import_dataitem(file: str) -> Dataitem:
+def import_dataitem(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Dataitem:
     """
-    Import object from a YAML file and create a new object into the backend.
+    Import an object from a YAML file or from a storage key.
 
     Parameters
     ----------
     file : str
-        Path to YAML file.
+        Path to the YAML file.
+    key : str
+        Entity key (store://...).
+    reset_id : bool
+        Flag to determine if the ID of executable entities should be reset.
+    context : str
+        Project name to use for context resolution.
 
     Returns
     -------
@@ -282,7 +293,12 @@ def import_dataitem(file: str) -> Dataitem:
     --------
     >>> obj = import_dataitem("my-dataitem.yaml")
     """
-    return context_processor.import_context_entity(file)
+    return context_processor.import_context_entity(
+        file,
+        key,
+        reset_id,
+        context,
+    )
 
 
 def load_dataitem(file: str) -> Dataitem:

digitalhub/entities/dataitem/table/entity.py

@@ -4,9 +4,7 @@
 
 from __future__ import annotations
 
-import shutil
 import typing
-from pathlib import Path
 from typing import Any
 
 from digitalhub.entities.dataitem._base.entity import Dataitem
@@ -138,22 +136,3 @@ class DataitemTable(Dataitem):
             extension=extension,
             **kwargs,
         )
-
-    @staticmethod
-    def _clean_tmp_path(pth: Path | None, clean: bool) -> None:
-        """
-        Clean temporary path.
-
-        Parameters
-        ----------
-        pth : Path | None
-            Path to clean.
-        clean : bool
-            If True, the path will be cleaned.
-
-        Returns
-        -------
-        None
-        """
-        if pth is not None and clean:
-            shutil.rmtree(pth)

digitalhub/entities/dataitem/utils.py

@@ -9,9 +9,9 @@ import typing
 from typing import Any
 
 from digitalhub.context.api import get_context
-from digitalhub.entities._base.entity._constructors.uuid import build_uuid
 from digitalhub.entities._base.material.utils import build_log_path_from_source, eval_local_source
 from digitalhub.entities._commons.enums import EntityKinds, EntityTypes
+from digitalhub.entities._constructors.uuid import build_uuid
 from digitalhub.stores.data.api import get_store
 from digitalhub.stores.readers.data.api import get_reader_by_object
 from digitalhub.utils.enums import FileExtensions
@@ -33,16 +33,39 @@ def eval_source(
     project: str | None = None,
 ) -> Any:
     """
-    Evaluate if source is local.
+    Evaluate and process data source for dataitem creation.
+
+    Determines the appropriate source handling based on whether a source
+    path or data object is provided. For table dataitems with data objects,
+    writes the data to a Parquet file and returns the file path.
 
     Parameters
     ----------
-    source : SourcesOrListOfSources
-        Source(s).
+    source : SourcesOrListOfSources, optional
+        The source specification(s) for the dataitem. Can be file paths,
+        URLs, or other source identifiers.
+    data : Any, optional
+        The data object to process (e.g., DataFrame). Alternative to source.
+        Exactly one of source or data must be provided.
+    kind : str, optional
+        The kind of dataitem being created (e.g., 'table').
+    name : str, optional
+        The name of the dataitem, used for generating file paths.
+    project : str, optional
+        The project name, used for context and path generation.
 
     Returns
     -------
-    None
+    Any
+        The processed source. Returns the original source if provided,
+        or the path to a generated file if data was processed.
+
+    Raises
+    ------
+    ValueError
+        If both source and data are provided or both are None.
+    NotImplementedError
+        If the specified kind is not supported for data processing.
     """
     if (source is None) == (data is None):
         raise ValueError("You must provide source or data.")
@@ -69,24 +92,32 @@ def eval_data(
     engine: str | None = None,
 ) -> Any:
     """
-    Evaluate data is loaded.
+    Evaluate and load data from source or return provided data.
+
+    For table dataitems, loads data from the source using the appropriate
+    store and reader. For other kinds, returns the data as-is.
 
     Parameters
     ----------
-    project : str
-        Project name.
-    source : str
-        Source(s).
-    data : Any
-        Dataframe to log. Alternative to source.
-    file_format : str
-        Extension of the file.
-    engine : str
-        Engine to use.
+    kind : str
+        The kind of dataitem (e.g., 'table') that determines
+        how data should be processed.
+    source : SourcesOrListOfSources
+        The source specification(s) to load data from.
+    data : Any, optional
+        Pre-loaded data object. If provided, may be returned directly
+        depending on the dataitem kind.
+    file_format : str, optional
+        The file format specification for reading the source
+        (e.g., 'parquet', 'csv').
+    engine : str, optional
+        The engine to use for reading the data (e.g., 'pandas', 'polars').
 
     Returns
     -------
-    None
+    Any
+        The loaded data object for table dataitems, or the original
+        data parameter for other kinds.
     """
     if kind == EntityKinds.DATAITEM_TABLE.value:
         if data is None:
@@ -108,29 +139,37 @@ def process_kwargs(
     **kwargs,
 ) -> dict:
     """
-    Process spec kwargs.
+    Process and enhance specification parameters for dataitem creation.
+
+    Processes the keyword arguments for dataitem specification, handling
+    schema extraction for table dataitems and path generation. Extracts
+    schema information from data objects when available.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project.
     name : str
-        Object name.
+        The name of the dataitem entity.
     kind : str
-        Kind the object.
+        The kind of dataitem being created (e.g., 'table').
     source : SourcesOrListOfSources
-        Source(s).
-    data : Any
-        Dataframe to log. Alternative to source.
-    path : str
-        Destination path of the entity. If not provided, it's generated.
+        The source specification(s) for the dataitem content.
+    data : Any, optional
+        The data object for schema extraction and processing.
+        Used as an alternative to source for table dataitems.
+    path : str, optional
+        The destination path for the dataitem entity.
+        If None, a path will be automatically generated.
     **kwargs : dict
-        Spec parameters.
+        Additional specification parameters to be processed
+        and passed to the dataitem creation.
 
     Returns
     -------
     dict
-        Kwargs updated.
+        The updated kwargs dictionary with processed path,
+        UUID, and schema information included.
     """
     if data is not None:
         if kind == EntityKinds.DATAITEM_TABLE.value:
@@ -147,12 +186,17 @@ def process_kwargs(
 
 def clean_tmp_path(pth: SourcesOrListOfSources) -> None:
     """
-    Clean temporary path.
+    Clean up temporary files and directories.
+
+    Removes temporary files or directories created during dataitem
+    processing. Handles both single paths and lists of paths,
+    ignoring any errors that occur during cleanup.
 
     Parameters
     ----------
     pth : SourcesOrListOfSources
-        Path to clean.
+        The path or list of paths to clean up. Can be file paths
+        or directory paths that need to be removed.
 
     Returns
     -------
@@ -167,19 +211,25 @@ def clean_tmp_path(pth: SourcesOrListOfSources) -> None:
 
 def post_process(obj: Dataitem, data: Any) -> Dataitem:
     """
-    Post process object.
+    Post-process dataitem object with additional metadata and previews.
+
+    Enhances the dataitem object with additional information extracted
+    from the data. For table dataitems, generates and stores a data
+    preview in the object's status.
 
     Parameters
     ----------
     obj : Dataitem
-        The object.
+        The dataitem object to post-process and enhance.
     data : Any
-        The data.
+        The data object used to generate previews and extract
+        additional metadata information.
 
     Returns
     -------
     Dataitem
-        The object.
+        The enhanced dataitem object with updated status information
+        and saved changes.
     """
     if obj.kind == EntityKinds.DATAITEM_TABLE.value:
         reader = get_reader_by_object(data)

digitalhub/entities/function/_base/entity.py

@@ -77,7 +77,7 @@ class Function(ExecutableEntity):
         """
         # Get task and run kind
         task_kind = factory.get_task_kind_from_action(self.kind, action)
-        run_kind = factory.get_run_kind(self.kind)
+        run_kind = factory.get_run_kind_from_action(self.kind, action)
 
         # Create or update new task
         task = self._get_or_create_task(task_kind)

digitalhub/entities/function/crud.py

@@ -182,14 +182,25 @@ def list_functions(project: str, **kwargs) -> list[Function]:
     )
 
 
-def import_function(file: str) -> Function:
+def import_function(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Function:
     """
-    Import object from a YAML file and create a new object into the backend.
+    Import an object from a YAML file or from a storage key.
 
     Parameters
     ----------
     file : str
-        Path to YAML file.
+        Path to the YAML file.
+    key : str
+        Entity key (store://...).
+    reset_id : bool
+        Flag to determine if the ID of executable entities should be reset.
+    context : str
+        Project name to use for context resolution.
 
     Returns
     -------
@@ -200,7 +211,7 @@ def import_function(file: str) -> Function:
     --------
     >>> obj = import_function("my-function.yaml")
     """
-    return context_processor.import_executable_entity(file)
+    return context_processor.import_executable_entity(file, key, reset_id, context)
 
 
 def load_function(file: str) -> Function:

digitalhub/entities/model/_base/entity.py

@@ -125,15 +125,35 @@ class Model(MaterialEntity):
         -------
         None
 
+        Examples
+        --------
+        Log multiple metrics at once
+        >>> entity.log_metrics({"loss": 0.002, "accuracy": 0.95})
+
+        Log metrics with lists and single values
+        >>> entity.log_metrics({"loss": [0.1, 0.05], "epoch": 10})
+
+        Append to existing metrics (default behavior)
+        >>> entity.log_metrics({"loss": 0.001, "accuracy": 0.96})  # Appends to existing
+
+        Overwrite existing metrics
+        >>> entity.log_metrics({"loss": 0.0005, "accuracy": 0.98}, overwrite=True)
+
         See also
         --------
         log_metric
         """
         for key, value in metrics.items():
+            # For lists, use log_metric which handles appending correctly
             if isinstance(value, list):
                 self.log_metric(key, value, overwrite)
+
+            # For single values, check if we should append or create new
             else:
-                self.log_metric(key, value, overwrite, single_value=True)
+                if not overwrite and key in self.status.metrics:
+                    self.log_metric(key, value)
+                else:
+                    self.log_metric(key, value, overwrite, single_value=True)
 
     ##############################
     # Helper methods