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

digitalhub/entities/workflow/crud.py

@@ -181,14 +181,25 @@ def list_workflows(project: str, **kwargs) -> list[Workflow]:
     )
 
 
-def import_workflow(file: str) -> Workflow:
+def import_workflow(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Workflow:
     """
-    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
     -------
@@ -199,7 +210,7 @@ def import_workflow(file: str) -> Workflow:
     --------
     >>> obj = import_workflow("my-workflow.yaml")
     """
-    return context_processor.import_executable_entity(file)
+    return context_processor.import_executable_entity(file, key, reset_id, context)
 
 
 def load_workflow(file: str) -> Workflow:

digitalhub/factory/enums.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class FactoryEnum(Enum):
+    """
+    Enumeration for factory.
+    """
+
+    RGX_RUNTIMES = r"digitalhub_runtime_.*"
+    REG_ENTITIES = "digitalhub.entities.builders"
+    REG_ENTITIES_VAR = "entity_builders"
+    REG_RUNTIME_VAR = "runtime_builders"

digitalhub/factory/factory.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 
 import typing
 
+from digitalhub.factory.enums import FactoryEnum
+from digitalhub.factory.utils import import_module, list_runtimes
 from digitalhub.utils.exceptions import BuilderError
 
 if typing.TYPE_CHECKING:
@@ -33,9 +35,9 @@ class Factory:
     Attributes
     ----------
     _entity_builders : dict[str, EntityBuilder | RuntimeEntityBuilder]
-        Registry of entity builders indexed by kind.
+        Registry of instantiated entity builders indexed by kind.
     _runtime_builders : dict[str, RuntimeBuilder]
-        Registry of runtime builders indexed by kind.
+        Registry of instantiated runtime builders indexed by kind.
 
     Notes
     -----
@@ -46,8 +48,10 @@ class Factory:
     def __init__(self):
         self._entity_builders: dict[str, EntityBuilder | RuntimeEntityBuilder] = {}
         self._runtime_builders: dict[str, RuntimeBuilder] = {}
+        self._entities_registered = False
+        self._runtimes_registered = False
 
-    def add_entity_builder(self, name: str, builder: EntityBuilder | RuntimeEntityBuilder) -> None:
+    def add_entity_builder(self, name: str, builder: type[EntityBuilder | RuntimeEntityBuilder]) -> None:
         """
         Register an entity builder.
 
@@ -55,8 +59,8 @@ class Factory:
         ----------
         name : str
             The unique identifier for the builder.
-        builder : EntityBuilder or RuntimeEntityBuilder
-            The builder instance to register.
+        builder : type[EntityBuilder] | type[RuntimeEntityBuilder]
+            The builder class to register. It will be instantiated immediately.
 
         Returns
         -------
@@ -71,7 +75,7 @@ class Factory:
             raise BuilderError(f"Builder {name} already exists.")
         self._entity_builders[name] = builder()
 
-    def add_runtime_builder(self, name: str, builder: RuntimeBuilder) -> None:
+    def add_runtime_builder(self, name: str, builder: type[RuntimeBuilder]) -> None:
         """
         Register a runtime builder.
 
@@ -79,8 +83,8 @@ class Factory:
         ----------
         name : str
             The unique identifier for the builder.
-        builder : RuntimeBuilder
-            The builder instance to register.
+        builder : type[RuntimeBuilder]
+            The builder class to register. It will be instantiated immediately.
 
         Returns
         -------
@@ -113,8 +117,8 @@ class Factory:
             kind = kwargs["kind"]
         except KeyError:
             raise BuilderError("Missing 'kind' parameter.")
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].build(**kwargs)
+        builder = self._get_entity_builder(kind)
+        return builder.build(**kwargs)
 
     def build_entity_from_dict(self, obj: dict) -> Entity:
         """
@@ -134,8 +138,8 @@ class Factory:
             kind = obj["kind"]
         except KeyError:
             raise BuilderError("Missing 'kind' parameter.")
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].from_dict(obj)
+        builder = self._get_entity_builder(kind)
+        return builder.from_dict(obj)
 
     def build_spec(self, kind_to_build_from: str, **kwargs) -> Spec:
         """
@@ -153,8 +157,8 @@ class Factory:
         Spec
             Spec object.
         """
-        self._raise_if_entity_builder_not_found(kind_to_build_from)
-        return self._entity_builders[kind_to_build_from].build_spec(**kwargs)
+        builder = self._get_entity_builder(kind_to_build_from)
+        return builder.build_spec(**kwargs)
 
     def build_metadata(self, kind_to_build_from: str, **kwargs) -> Metadata:
         """
@@ -172,8 +176,8 @@ class Factory:
         Metadata
             Metadata object.
         """
-        self._raise_if_entity_builder_not_found(kind_to_build_from)
-        return self._entity_builders[kind_to_build_from].build_metadata(**kwargs)
+        builder = self._get_entity_builder(kind_to_build_from)
+        return builder.build_metadata(**kwargs)
 
     def build_status(self, kind_to_build_from: str, **kwargs) -> Status:
         """
@@ -191,8 +195,8 @@ class Factory:
         Status
             Status object.
         """
-        self._raise_if_entity_builder_not_found(kind_to_build_from)
-        return self._entity_builders[kind_to_build_from].build_status(**kwargs)
+        builder = self._get_entity_builder(kind_to_build_from)
+        return builder.build_status(**kwargs)
 
     def build_runtime(self, kind_to_build_from: str, project: str) -> Runtime:
         """
@@ -210,8 +214,8 @@ class Factory:
         Runtime
             Runtime object.
         """
-        self._raise_if_runtime_builder_not_found(kind_to_build_from)
-        return self._runtime_builders[kind_to_build_from].build(project=project)
+        builder = self._get_runtime_builder(kind_to_build_from)
+        return builder.build(project=project)
 
     def get_entity_type_from_kind(self, kind: str) -> str:
         """
@@ -227,8 +231,8 @@ class Factory:
         str
             Entity type.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_entity_type()
+        builder = self._get_entity_builder(kind)
+        return builder.get_entity_type()
 
     def get_executable_kind(self, kind: str) -> str:
         """
@@ -244,8 +248,8 @@ class Factory:
         str
             Executable kind.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_executable_kind()
+        builder = self._get_entity_builder(kind)
+        return builder.get_executable_kind()
 
     def get_action_from_task_kind(self, kind: str, task_kind: str) -> str:
         """
@@ -263,8 +267,8 @@ class Factory:
         str
             Action.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_action_from_task_kind(task_kind)
+        builder = self._get_entity_builder(kind)
+        return builder.get_action_from_task_kind(task_kind)
 
     def get_task_kind_from_action(self, kind: str, action: str) -> list[str]:
         """
@@ -282,10 +286,10 @@ class Factory:
         list of str
             Task kinds.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_task_kind_from_action(action)
+        builder = self._get_entity_builder(kind)
+        return builder.get_task_kind_from_action(action)
 
-    def get_run_kind(self, kind: str) -> str:
+    def get_run_kind_from_action(self, kind: str, action: str) -> str:
         """
         Get run kind.
 
@@ -299,8 +303,8 @@ class Factory:
         str
             Run kind.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_run_kind()
+        builder = self._get_entity_builder(kind)
+        return builder.get_run_kind_from_action(action)
 
     def get_all_kinds(self, kind: str) -> list[str]:
         """
@@ -316,7 +320,8 @@ class Factory:
         list of str
             All kinds.
         """
-        return self._entity_builders[kind].get_all_kinds()
+        builder = self._get_entity_builder(kind)
+        return builder.get_all_kinds()
 
     def get_spec_validator(self, kind: str) -> SpecValidator:
         """
@@ -332,50 +337,124 @@ class Factory:
         SpecValidator
             Spec validator.
         """
-        self._raise_if_entity_builder_not_found(kind)
-        return self._entity_builders[kind].get_spec_validator()
+        builder = self._get_entity_builder(kind)
+        return builder.get_spec_validator()
 
-    def _raise_if_entity_builder_not_found(self, kind: str) -> None:
+    def _get_entity_builder(self, kind: str) -> EntityBuilder | RuntimeEntityBuilder:
         """
-        Verify entity builder existence.
+        Return the entity builder for the given kind, ensuring lazy runtime registration.
 
-        Parameters
-        ----------
-        kind : str
-            The entity kind to verify.
+        Raises
+        ------
+        BuilderError
+            If no builder exists for the specified kind.
+        """
+        if not self._entities_registered:
+            self._ensure_entities_registered()
+        if kind not in self._entity_builders:
+            if not self._runtimes_registered:
+                self._ensure_runtimes_registered()
+            if kind not in self._entity_builders:
+                raise BuilderError(f"Entity builder for kind '{kind}' not found.")
+        return self._entity_builders[kind]
 
-        Returns
-        -------
-        None
+    def _get_runtime_builder(self, kind: str) -> RuntimeBuilder:
+        """
+        Return the runtime builder for the given kind, ensuring lazy runtime registration.
 
         Raises
         ------
         BuilderError
             If no builder exists for the specified kind.
         """
-        if kind not in self._entity_builders:
-            raise BuilderError(f"Entity builder for kind '{kind}' not found.")
+        if kind not in self._runtime_builders:
+            if not self._runtimes_registered:
+                self._ensure_runtimes_registered()
+            if kind not in self._runtime_builders:
+                raise BuilderError(f"Runtime builder for kind '{kind}' not found.")
+        return self._runtime_builders[kind]
 
-    def _raise_if_runtime_builder_not_found(self, kind: str) -> None:
+    def _ensure_entities_registered(self) -> None:
         """
-        Verify runtime builder existence.
+        Ensure core entities are registered on-demand.
 
-        Parameters
-        ----------
-        kind : str
-            The runtime kind to verify.
+        Returns
+        -------
+        None
+        """
+        if self._entities_registered:
+            return
+        try:
+            self._register_entities()
+            self._entities_registered = True
+        except Exception as e:
+            # Avoid repeated attempts; surface as BuilderError for consistency
+            self._entities_registered = True
+            raise BuilderError(f"Failed to register core entities: {e}")
+
+    def _register_entities(self) -> None:
+        """
+        Register core entity builders into the factory.
+
+        Imports the core entities module and registers all entity
+        builders with the global factory instance.
 
         Returns
         -------
         None
+        """
+        try:
+            module = import_module(FactoryEnum.REG_ENTITIES.value)
 
-        Raises
-        ------
-        BuilderError
-            If no builder exists for the specified kind.
+            # Register core entities
+            for k, b in getattr(module, FactoryEnum.REG_ENTITIES_VAR.value, []):
+                self.add_entity_builder(k, b)
+
+        except Exception as e:
+            raise RuntimeError("Error registering core entities.") from e
+
+    def _ensure_runtimes_registered(self) -> None:
         """
-        if kind not in self._runtime_builders:
-            raise BuilderError(f"Runtime builder for kind '{kind}' not found.")
+        Ensure runtime entities are registered on-demand.
+
+        Returns
+        -------
+        None
+        """
+        if self._runtimes_registered:
+            return
+        try:
+            self._register_runtimes_entities()
+            self._runtimes_registered = True
+        except Exception as e:
+            # If registration fails, mark as attempted to avoid infinite loops
+            self._runtimes_registered = True
+            raise BuilderError(f"Failed to register runtime entities: {e}")
+
+    def _register_runtimes_entities(self) -> None:
+        """
+        Register all runtime builders and their entities into the factory.
+
+        Imports each runtime package and registers its entity and runtime
+        builders with the global factory instance.
+
+        Returns
+        -------
+        None
+        """
+        try:
+            for package in list_runtimes():
+                module = import_module(package)
+
+                # Register workflows, functions, tasks and runs entities builders
+                for k, b in getattr(module, FactoryEnum.REG_ENTITIES_VAR.value, []):
+                    self.add_entity_builder(k, b)
+
+                # Register runtime builders
+                for k, b in getattr(module, FactoryEnum.REG_RUNTIME_VAR.value, []):
+                    self.add_runtime_builder(k, b)
+        except Exception as e:
+            raise RuntimeError("Error registering runtime entities.") from e
 
 
 factory = Factory()

digitalhub/factory/utils.py

@@ -9,7 +9,7 @@ import pkgutil
 import re
 from types import ModuleType
 
-from digitalhub.factory.factory import factory
+from digitalhub.factory.enums import FactoryEnum
 
 
 def import_module(package: str) -> ModuleType:
@@ -58,62 +58,11 @@ def list_runtimes() -> list[str]:
     RuntimeError
         If an error occurs while scanning for runtime packages.
     """
-    pattern = r"digitalhub_runtime_.*"
-    runtimes: list[str] = []
     try:
+        runtimes: list[str] = []
         for _, name, _ in pkgutil.iter_modules():
-            if re.match(pattern, name):
+            if re.match(FactoryEnum.RGX_RUNTIMES.value, name):
                 runtimes.append(name)
         return runtimes
     except Exception as e:
         raise RuntimeError("Error listing installed runtimes.") from e
-
-
-def register_runtimes_entities() -> None:
-    """
-    Register all runtime builders and their entities into the factory.
-
-    Imports each runtime package and registers its entity and runtime
-    builders with the global factory instance.
-
-    Returns
-    -------
-    None
-    """
-    for package in list_runtimes():
-        module = import_module(package)
-        entity_builders = getattr(module, "entity_builders")
-        for entity_builder_tuple in entity_builders:
-            kind, builder = entity_builder_tuple
-            factory.add_entity_builder(kind, builder)
-
-        runtime_builders = getattr(module, "runtime_builders")
-        for runtime_builder_tuple in runtime_builders:
-            kind, builder = runtime_builder_tuple
-            factory.add_runtime_builder(kind, builder)
-
-
-def register_entities() -> None:
-    """
-    Register core entity builders into the factory.
-
-    Imports the core entities module and registers all entity
-    builders with the global factory instance.
-
-    Returns
-    -------
-    None
-
-    Raises
-    ------
-    RuntimeError
-        If registration of core entities fails.
-    """
-    try:
-        module = import_module("digitalhub.entities.builders")
-        entities_builders_list = getattr(module, "entity_builders")
-        for entity_builder_tuple in entities_builders_list:
-            kind, builder = entity_builder_tuple
-            factory.add_entity_builder(kind, builder)
-    except Exception as e:
-        raise RuntimeError("Error registering entities.") from e

digitalhub/stores/client/api.py

@@ -9,10 +9,11 @@ import typing
 from digitalhub.stores.client.builder import client_builder
 
 if typing.TYPE_CHECKING:
-    from digitalhub.stores.client._base.client import Client
+    from digitalhub.stores.client.dhcore.client import ClientDHCore
+    from digitalhub.stores.client.local.client import ClientLocal
 
 
-def get_client(local: bool = False, config: dict | None = None) -> Client:
+def get_client(local: bool = False) -> ClientLocal | ClientDHCore:
     """
     Wrapper around ClientBuilder.build.
 
@@ -22,15 +23,10 @@ def get_client(local: bool = False, config: dict | None = None) -> Client:
         Whether to create a local client or not. If True, creates a
         ClientLocal instance that operates in-memory. If False, creates
         a ClientDHCore instance that communicates with a remote backend.
-    config : dict, optional
-        DHCore environment configuration. Only used when local=False.
-        If None, configuration will be loaded from environment variables
-        and configuration files.
 
     Returns
     -------
-    Client
-        The client instance. Either ClientLocal or ClientDHCore depending
-        on the local parameter.
+    ClientLocal | ClientDHCore
+        The client instance.
     """
-    return client_builder.build(local, config)
+    return client_builder.build(local)

digitalhub/stores/client/builder.py

@@ -10,7 +10,7 @@ from digitalhub.stores.client.dhcore.client import ClientDHCore
 from digitalhub.stores.client.local.client import ClientLocal
 
 if typing.TYPE_CHECKING:
-    from digitalhub.stores.client._base.client import Client
+    pass
 
 
 class ClientBuilder:
@@ -27,7 +27,7 @@ class ClientBuilder:
         self._local = None
         self._dhcore = None
 
-    def build(self, local: bool = False, config: dict | None = None) -> Client:
+    def build(self, local: bool = False, config: dict | None = None) -> ClientLocal | ClientDHCore:
         """
         Method to create a client instance.
 
@@ -40,7 +40,7 @@ class ClientBuilder:
 
         Returns
         -------
-        Client
+        ClientLocal | ClientDHCore
             Returns the client instance.
         """
         if local: