digitalhub 0.13.3__py3-none-any.whl → 0.14.0__py3-none-any.whl

digitalhub/entities/project/crud.py

@@ -7,8 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._commons.enums import EntityTypes
-from digitalhub.entities._processors.base import base_processor
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import base_processor, context_processor
 from digitalhub.entities.project.utils import setup_project
 from digitalhub.utils.exceptions import BackendError
 
@@ -80,7 +79,6 @@ def get_project(
     name: str,
     local: bool = False,
     setup_kwargs: dict | None = None,
-    **kwargs,
 ) -> Project:
     """
     Retrieves project details from backend.
@@ -93,8 +91,6 @@ def get_project(
         Flag to determine if backend is local.
     setup_kwargs : dict
         Setup keyword arguments passed to setup_project() function.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -109,7 +105,6 @@ def get_project(
         entity_type=ENTITY_TYPE,
         entity_name=name,
         local=local,
-        **kwargs,
     )
     return setup_project(obj, setup_kwargs)
 
@@ -118,6 +113,7 @@ def import_project(
     file: str,
     local: bool = False,
     setup_kwargs: dict | None = None,
+    reset_id: bool = False,
 ) -> Project:
     """
     Import object from a YAML file and create a new object into the backend.
@@ -130,6 +126,8 @@ def import_project(
         Flag to determine if backend is local.
     setup_kwargs : dict
         Setup keyword arguments passed to setup_project() function.
+    reset_id : bool
+        Flag to determine if the ID of project entities should be reset.
 
     Returns
     -------
@@ -140,7 +138,11 @@ def import_project(
     --------
     >>> obj = import_project("my-project.yaml")
     """
-    obj = base_processor.import_project_entity(file=file, local=local)
+    obj = base_processor.import_project_entity(
+        file=file,
+        local=local,
+        reset_id=reset_id,
+    )
     return setup_project(obj, setup_kwargs)
 
 
@@ -174,7 +176,7 @@ def load_project(
     return setup_project(obj, setup_kwargs)
 
 
-def list_projects(local: bool = False, **kwargs) -> list[Project]:
+def list_projects(local: bool = False) -> list[Project]:
     """
     List projects in backend.
 
@@ -182,15 +184,13 @@ def list_projects(local: bool = False, **kwargs) -> list[Project]:
     ----------
     local : bool
         Flag to determine if backend is local.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
     list
         List of objects.
     """
-    return base_processor.list_project_entities(local=local, **kwargs)
+    return base_processor.list_project_entities(local=local)
 
 
 def get_or_create_project(
@@ -276,7 +276,6 @@ def delete_project(
     cascade: bool = True,
     clean_context: bool = True,
     local: bool = False,
-    **kwargs,
 ) -> dict:
     """
     Delete a project.
@@ -291,8 +290,6 @@ def delete_project(
         Flag to determine if context will be deleted.
     local : bool
         Flag to determine if backend is local.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -309,7 +306,6 @@ def delete_project(
         local=local,
         cascade=cascade,
         clean_context=clean_context,
-        **kwargs,
     )
 
 
@@ -323,7 +319,6 @@ def search_entity(
     updated: str | None = None,
     description: str | None = None,
     labels: list[str] | None = None,
-    **kwargs,
 ) -> list[ContextEntity]:
     """
     Search objects from backend.
@@ -348,13 +343,11 @@ def search_entity(
         Entity description.
     labels : list[str]
         Entity labels.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
-        Returns
-        -------
-        list[ContextEntity]
-            List of object instances.
+    Returns
+    -------
+    list[ContextEntity]
+        List of object instances.
     """
     return context_processor.search_entity(
         project_name,
@@ -366,5 +359,4 @@ def search_entity(
         updated=updated,
         description=description,
         labels=labels,
-        **kwargs,
     )

digitalhub/entities/run/_base/builder.py

@@ -90,10 +90,6 @@ class RunBuilder(UnversionedBuilder, RuntimeEntityBuilder):
         ----------
         task : str
             Task string.
-
-        Returns
-        -------
-        None
         """
         task_kind = task.split("://")[0]
         if task_kind not in self.get_all_kinds():

digitalhub/entities/run/_base/entity.py

@@ -10,8 +10,9 @@ import typing
 from digitalhub.entities._base.unversioned.entity import UnversionedEntity
 from digitalhub.entities._commons.enums import EntityTypes, State
 from digitalhub.entities._commons.metrics import MetricType, set_metrics, validate_metric_value
-from digitalhub.entities._processors.context import context_processor
-from digitalhub.factory.factory import factory
+from digitalhub.entities._processors.processors import context_processor
+from digitalhub.factory.entity import entity_factory
+from digitalhub.factory.runtime import runtime_factory
 from digitalhub.utils.exceptions import EntityError
 from digitalhub.utils.logger import LOGGER
 
@@ -51,15 +52,11 @@ class Run(UnversionedEntity):
     def build(self) -> None:
         """
         Build run.
-
-        Returns
-        -------
-        None
         """
         executable = self._get_executable()
         task = self._get_task()
         new_spec = self._get_runtime().build(executable, task, self.to_dict())
-        self.spec = factory.build_spec(self.kind, **new_spec)
+        self.spec = entity_factory.build_spec(self.kind, **new_spec)
         self._set_state(State.BUILT.value)
         self.save(update=True)
 
@@ -141,10 +138,6 @@ class Run(UnversionedEntity):
     def stop(self) -> None:
         """
         Stop run.
-
-        Returns
-        -------
-        None
         """
         if not self.spec.local_execution:
             return context_processor.stop_entity(self.project, self.ENTITY_TYPE, self.id)
@@ -152,10 +145,6 @@ class Run(UnversionedEntity):
     def resume(self) -> None:
         """
         Resume run.
-
-        Returns
-        -------
-        None
         """
         if not self.spec.local_execution:
             return context_processor.resume_entity(self.project, self.ENTITY_TYPE, self.id)
@@ -184,10 +173,6 @@ class Run(UnversionedEntity):
         single_value : bool
             If True, value is a single value.
 
-        Returns
-        -------
-        None
-
         Examples
         --------
         Log a new value in a list
@@ -197,13 +182,27 @@ class Run(UnversionedEntity):
         >>> entity.log_metric("loss", 0.0019)
 
         Log a list of values and append them to existing metric:
-        >>> entity.log_metric("loss", [0.0018, 0.0015])
+        >>> entity.log_metric(
+        ...     "loss",
+        ...     [
+        ...         0.0018,
+        ...         0.0015,
+        ...     ],
+        ... )
 
         Log a single value (not represented as list):
-        >>> entity.log_metric("accuracy", 0.9, single_value=True)
+        >>> entity.log_metric(
+        ...     "accuracy",
+        ...     0.9,
+        ...     single_value=True,
+        ... )
 
         Log a list of values and overwrite existing metric:
-        >>> entity.log_metric("accuracy", [0.8, 0.9], overwrite=True)
+        >>> entity.log_metric(
+        ...     "accuracy",
+        ...     [0.8, 0.9],
+        ...     overwrite=True,
+        ... )
         """
         self._set_metrics(key, value, overwrite, single_value)
         context_processor.update_metric(self.project, self.ENTITY_TYPE, self.id, key, self.status.metrics[key])
@@ -224,19 +223,59 @@ class Run(UnversionedEntity):
         overwrite : bool
             If True, overwrite existing metrics.
 
-        Returns
-        -------
-        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)
 
     ##############################
     #  Helpers
@@ -245,19 +284,11 @@ class Run(UnversionedEntity):
     def _setup_execution(self) -> None:
         """
         Setup run execution.
-
-        Returns
-        -------
-        None
         """
 
     def _start_execution(self) -> None:
         """
         Start run execution.
-
-        Returns
-        -------
-        None
         """
         self._context().set_run(f"{self.key}:{self.id}")
         if self.spec.local_execution:
@@ -269,10 +300,6 @@ class Run(UnversionedEntity):
     def _finish_execution(self) -> None:
         """
         Finish run execution.
-
-        Returns
-        -------
-        None
         """
         self._context().unset_run()
 
@@ -285,7 +312,7 @@ class Run(UnversionedEntity):
         bool
             True if run is in runnable state, False otherwise.
         """
-        return (self.status.state == State.BUILT.value) or (self.status.state == State.STOPPED.value)
+        return self.status.state in (State.BUILT.value, State.STOPPED.value)
 
     def _set_status(self, status: dict) -> None:
         """
@@ -295,12 +322,8 @@ class Run(UnversionedEntity):
         ----------
         status : dict
             Status to set.
-
-        Returns
-        -------
-        None
         """
-        self.status: RunStatus = factory.build_status(self.kind, **status)
+        self.status: RunStatus = entity_factory.build_status(self.kind, **status)
 
     def _set_state(self, state: str) -> None:
         """
@@ -310,10 +333,6 @@ class Run(UnversionedEntity):
         ----------
         state : str
             State to set.
-
-        Returns
-        -------
-        None
         """
         self.status.state = state
 
@@ -325,10 +344,6 @@ class Run(UnversionedEntity):
         ----------
         message : str
             Message to set.
-
-        Returns
-        -------
-        None
         """
         self.status.message = message
 
@@ -341,7 +356,7 @@ class Run(UnversionedEntity):
         Runtime
             Runtime object.
         """
-        return factory.build_runtime(self.kind, self.project)
+        return runtime_factory.build_runtime(self.kind, self.project)
 
     def _get_executable(self) -> dict:
         """
@@ -353,8 +368,8 @@ class Run(UnversionedEntity):
         dict
             Executable (function or workflow) from backend.
         """
-        exec_kind = factory.get_executable_kind(self.kind)
-        exec_type = factory.get_entity_type_from_kind(exec_kind)
+        exec_kind = entity_factory.get_executable_kind(self.kind)
+        exec_type = entity_factory.get_entity_type_from_kind(exec_kind)
         string_to_split = getattr(self.spec, exec_type)
         exec_name, exec_id = string_to_split.split("://")[-1].split("/")[-1].split(":")
         return context_processor.read_context_entity(
@@ -384,10 +399,6 @@ class Run(UnversionedEntity):
     def _get_metrics(self) -> None:
         """
         Get model metrics from backend.
-
-        Returns
-        -------
-        None
         """
         self.status.metrics = context_processor.read_metrics(
             project=self.project,
@@ -415,10 +426,6 @@ class Run(UnversionedEntity):
             If True, overwrite existing metric.
         single_value : bool
             If True, value is a single value.
-
-        Returns
-        -------
-        None
         """
         value = validate_metric_value(value)
         self.status.metrics = set_metrics(

digitalhub/entities/run/crud.py

@@ -7,8 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._commons.enums import EntityTypes
-from digitalhub.entities._processors.context import context_processor
-from digitalhub.utils.exceptions import EntityError
+from digitalhub.entities._processors.processors import context_processor
 
 if typing.TYPE_CHECKING:
     from digitalhub.entities.run._base.entity import Run
@@ -71,7 +70,6 @@ def new_run(
 def get_run(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> Run:
     """
     Get object from backend.
@@ -82,8 +80,6 @@ def get_run(
         Entity key (store://...) or entity ID.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -100,14 +96,26 @@ def get_run(
     >>>               project="my-project")
     """
     return context_processor.read_unversioned_entity(
-        identifier,
+        identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_runs(project: str, **kwargs) -> list[Run]:
+def list_runs(
+    project: str,
+    q: str | None = None,
+    name: str | None = None,
+    kind: str | None = None,
+    user: str | None = None,
+    state: str | None = None,
+    created: str | None = None,
+    updated: str | None = None,
+    function: str | None = None,
+    workflow: str | None = None,
+    task: str | None = None,
+    action: str | None = None,
+) -> list[Run]:
     """
     List all latest version objects from backend.
 
@@ -115,34 +123,74 @@ def list_runs(project: str, **kwargs) -> list[Run]:
     ----------
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
+    q : str
+        Query string to filter objects.
+    name : str
+        Object name.
+    kind : str
+        Kind of the object.
+    user : str
+        User that created the object.
+    state : str
+        Object state.
+    created : str
+        Creation date filter.
+    updated : str
+        Update date filter.
+    function : str
+        Function key filter.
+    workflow : str
+        Workflow key filter.
+    task : str
+        Task string filter.
+    action : str
+        Action name filter.
 
     Returns
     -------
-    list[Run]
+    list[Model]
         List of object instances.
 
     Examples
     --------
     >>> objs = list_runs(project="my-project")
     """
-    # TODO more examples: search by function, latest for task and function
     return context_processor.list_context_entities(
         project=project,
         entity_type=ENTITY_TYPE,
-        **kwargs,
+        q=q,
+        name=name,
+        kind=kind,
+        user=user,
+        state=state,
+        created=created,
+        updated=updated,
+        function=function,
+        workflow=workflow,
+        task=task,
+        action=action,
     )
 
 
-def import_run(file: str) -> Run:
+def import_run(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Run:
     """
-    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
     -------
@@ -153,7 +201,12 @@ def import_run(file: str) -> Run:
     -------
     >>> obj = import_run("my-run.yaml")
     """
-    return context_processor.import_context_entity(file)
+    return context_processor.import_context_entity(
+        file,
+        key,
+        reset_id,
+        context,
+    )
 
 
 def load_run(file: str) -> Run:
@@ -206,7 +259,7 @@ def update_run(entity: Run) -> Run:
 def delete_run(
     identifier: str,
     project: str | None = None,
-    **kwargs,
+    entity_id: str | None = None,
 ) -> dict:
     """
     Delete object from backend.
@@ -214,11 +267,11 @@ def delete_run(
     Parameters
     ----------
     identifier : str
-        Entity key (store://...) or entity ID.
+        Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
+    entity_id : str
+        Entity ID.
 
     Returns
     -------
@@ -228,14 +281,14 @@ def delete_run(
     Examples
     --------
     >>> obj = delete_run("store://my-run-key")
-    >>> obj = delete_run("my-run-id", project="my-project")
+    >>> obj = delete_run(
+    ...     "my-run-id",
+    ...     project="my-project",
+    ... )
     """
-    if not identifier.startswith("store://") and project is None:
-        raise EntityError("Specify entity key or entity ID combined with project")
     return context_processor.delete_context_entity(
         identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        entity_id=identifier,
-        **kwargs,
+        entity_id=entity_id,
     )

digitalhub/entities/secret/_base/entity.py

@@ -8,7 +8,7 @@ import typing
 
 from digitalhub.entities._base.versioned.entity import VersionedEntity
 from digitalhub.entities._commons.enums import EntityTypes
-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
@@ -50,10 +50,6 @@ class Secret(VersionedEntity):
         ----------
         value : str
             Value of the secret.
-
-        Returns
-        -------
-        None
         """
         obj = {self.name: value}
         context_processor.update_secret_data(self.project, self.ENTITY_TYPE, obj)