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

digitalhub/entities/workflow/crud.py

@@ -7,7 +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.entities._processors.processors import context_processor
 
 if typing.TYPE_CHECKING:
     from digitalhub.entities.workflow._base.entity import Workflow
@@ -75,7 +75,6 @@ def get_workflow(
     identifier: str,
     project: str | None = None,
     entity_id: str | None = None,
-    **kwargs,
 ) -> Workflow:
     """
     Get object from backend.
@@ -88,8 +87,6 @@ def get_workflow(
         Project name.
     entity_id : str
         Entity ID.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -107,18 +104,16 @@ def get_workflow(
     >>>                    entity_id="my-workflow-id")
     """
     return context_processor.read_context_entity(
-        identifier,
+        identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
         entity_id=entity_id,
-        **kwargs,
     )
 
 
 def get_workflow_versions(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> list[Workflow]:
     """
     Get object versions from backend.
@@ -129,8 +124,6 @@ def get_workflow_versions(
         Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -147,14 +140,23 @@ def get_workflow_versions(
     >>>                             project="my-project")
     """
     return context_processor.read_context_entity_versions(
-        identifier,
+        identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_workflows(project: str, **kwargs) -> list[Workflow]:
+def list_workflows(
+    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,
+    version: str | None = None,
+) -> list[Workflow]:
     """
     List all latest version objects from backend.
 
@@ -162,8 +164,22 @@ def list_workflows(project: str, **kwargs) -> list[Workflow]:
     ----------
     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.
+    version : str
+        Object version, default is latest.
 
     Returns
     -------
@@ -177,18 +193,36 @@ def list_workflows(project: str, **kwargs) -> list[Workflow]:
     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,
+        version=version,
     )
 
 
-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 +233,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:
@@ -269,7 +303,8 @@ def delete_workflow(
     entity_id : str
         Entity ID.
     delete_all_versions : bool
-        Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+        Delete all versions of the named entity.
+        If True, use entity name instead of entity key as identifier.
     cascade : bool
         Cascade delete.
     **kwargs : dict
@@ -297,5 +332,4 @@ def delete_workflow(
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
         cascade=cascade,
-        **kwargs,
     )

digitalhub/factory/entity.py

@@ -0,0 +1,283 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+
+from digitalhub.factory.registry import registry
+from digitalhub.utils.exceptions import BuilderError
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.entity.entity import Entity
+    from digitalhub.entities._base.entity.metadata import Metadata
+    from digitalhub.entities._base.entity.spec import Spec, SpecValidator
+    from digitalhub.entities._base.entity.status import Status
+
+
+class EntityFactory:
+    """
+    Factory for creating and managing entity builders.
+
+    This class handles the creation of entities and their components
+    through their respective builders, using a centralized registry.
+    """
+
+    def _call_builder_method(self, kind: str, method_name: str, *args, **kwargs):
+        """
+        Helper method to get a builder and call a method on it.
+
+        Parameters
+        ----------
+        kind : str
+            The kind of builder to retrieve.
+        method_name : str
+            The name of the method to call on the builder.
+        *args
+            Positional arguments to pass to the method.
+        **kwargs
+            Keyword arguments to pass to the method.
+
+        Returns
+        -------
+        Any
+            The result of calling the method on the builder.
+        """
+        builder = registry.get_entity_builder(kind)
+        return getattr(builder, method_name)(*args, **kwargs)
+
+    def build_entity_from_params(self, **kwargs) -> Entity:
+        """
+        Build an entity from parameters.
+
+        Parameters
+        ----------
+        **kwargs
+            Entity parameters.
+
+        Returns
+        -------
+        Entity
+            Entity object.
+        """
+        kind = self._get_kind(**kwargs)
+        builder = registry.get_entity_builder(kind)
+        return builder.build(**kwargs)
+
+    def build_entity_from_dict(self, obj: dict) -> Entity:
+        """
+        Build an entity from a dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            Dictionary with entity data.
+
+        Returns
+        -------
+        Entity
+            Entity object.
+        """
+        kind = self._get_kind(**obj)
+        builder = registry.get_entity_builder(kind)
+        return builder.from_dict(obj)
+
+    def build_spec(self, kind_to_build_from: str, **kwargs) -> Spec:
+        """
+        Build an entity spec.
+
+        Parameters
+        ----------
+        kind_to_build_from : str
+            Entity type.
+        **kwargs
+            Additional spec parameters.
+
+        Returns
+        -------
+        Spec
+            Spec object.
+        """
+        return self._call_builder_method(kind_to_build_from, "build_spec", **kwargs)
+
+    def build_metadata(self, kind_to_build_from: str, **kwargs) -> Metadata:
+        """
+        Build an entity metadata.
+
+        Parameters
+        ----------
+        kind_to_build_from : str
+            Entity type.
+        **kwargs
+            Additional metadata parameters.
+
+        Returns
+        -------
+        Metadata
+            Metadata object.
+        """
+        return self._call_builder_method(kind_to_build_from, "build_metadata", **kwargs)
+
+    def build_status(self, kind_to_build_from: str, **kwargs) -> Status:
+        """
+        Build an entity status.
+
+        Parameters
+        ----------
+        kind_to_build_from : str
+            Entity type.
+        **kwargs
+            Additional status parameters.
+
+        Returns
+        -------
+        Status
+            Status object.
+        """
+        return self._call_builder_method(kind_to_build_from, "build_status", **kwargs)
+
+    def get_entity_type_from_kind(self, kind: str) -> str:
+        """
+        Get entity type from builder.
+
+        Parameters
+        ----------
+        kind : str
+            Entity type.
+
+        Returns
+        -------
+        str
+            Entity type.
+        """
+        return self._call_builder_method(kind, "get_entity_type")
+
+    def get_executable_kind(self, kind: str) -> str:
+        """
+        Get executable kind.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+
+        Returns
+        -------
+        str
+            Executable kind.
+        """
+        return self._call_builder_method(kind, "get_executable_kind")
+
+    def get_action_from_task_kind(self, kind: str, task_kind: str) -> str:
+        """
+        Get action from task.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+        task_kind : str
+            Task kind.
+
+        Returns
+        -------
+        str
+            Action.
+        """
+        return self._call_builder_method(kind, "get_action_from_task_kind", task_kind)
+
+    def get_task_kind_from_action(self, kind: str, action: str) -> list[str]:
+        """
+        Get task kinds from action.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+        action : str
+            Action.
+
+        Returns
+        -------
+        list of str
+            Task kinds.
+        """
+        return self._call_builder_method(kind, "get_task_kind_from_action", action)
+
+    def get_run_kind_from_action(self, kind: str, action: str) -> str:
+        """
+        Get run kind.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+
+        Returns
+        -------
+        str
+            Run kind.
+        """
+        return self._call_builder_method(kind, "get_run_kind_from_action", action)
+
+    def get_all_kinds(self, kind: str) -> list[str]:
+        """
+        Get all kinds.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+
+        Returns
+        -------
+        list of str
+            All kinds.
+        """
+        return self._call_builder_method(kind, "get_all_kinds")
+
+    def get_spec_validator(self, kind: str) -> SpecValidator:
+        """
+        Get spec validators.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+
+        Returns
+        -------
+        SpecValidator
+            Spec validator.
+        """
+        return self._call_builder_method(kind, "get_spec_validator")
+
+    @staticmethod
+    def _get_kind(**kwargs) -> str:
+        """
+        Extract the 'kind' from parameters.
+
+        Parameters
+        ----------
+        **kwargs
+            Entity parameters.
+
+        Returns
+        -------
+        str
+            The kind of the entity.
+
+        Raises
+        ------
+        BuilderError
+            If 'kind' is not found in parameters.
+        """
+        try:
+            return kwargs["kind"]
+        except KeyError:
+            raise BuilderError("Missing 'kind' parameter.")
+
+
+# Global instance
+entity_factory = EntityFactory()

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/registry.py

@@ -0,0 +1,197 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+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:
+    from digitalhub.entities._base.entity.builder import EntityBuilder
+    from digitalhub.entities._base.runtime_entity.builder import RuntimeEntityBuilder
+    from digitalhub.runtimes.builder import RuntimeBuilder
+
+
+class BuilderRegistry:
+    """
+    Singleton registry for managing imported modules and builders.
+
+    This class centralizes the registration and retrieval of entity and runtime builders,
+    ensuring lazy loading and a single source of truth for available builders.
+    """
+
+    def __init__(self) -> None:
+        self._instance: BuilderRegistry | None = None
+        self._initialized = False
+        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: type[EntityBuilder | RuntimeEntityBuilder],
+    ) -> None:
+        """
+        Register an entity builder.
+
+        Parameters
+        ----------
+        name : str
+            The unique identifier for the builder.
+        builder : type[EntityBuilder] | type[RuntimeEntityBuilder]
+            The builder class to register. It will be instantiated immediately.
+
+        Raises
+        ------
+        BuilderError
+            If a builder with the same name already exists.
+        """
+        if name in self._entity_builders:
+            raise BuilderError(f"Builder {name} already exists.")
+        self._entity_builders[name] = builder()
+
+    def add_runtime_builder(self, name: str, builder: type[RuntimeBuilder]) -> None:
+        """
+        Register a runtime builder.
+
+        Parameters
+        ----------
+        name : str
+            The unique identifier for the builder.
+        builder : type[RuntimeBuilder]
+            The builder class to register. It will be instantiated immediately.
+
+        Raises
+        ------
+        BuilderError
+            If a builder with the same name already exists.
+        """
+        if name in self._runtime_builders:
+            raise BuilderError(f"Builder {name} already exists.")
+        self._runtime_builders[name] = builder()
+
+    def get_entity_builder(self, kind: str) -> EntityBuilder | RuntimeEntityBuilder:
+        """
+        Retrieve the entity builder for the given kind, ensuring lazy registration.
+
+        Parameters
+        ----------
+        kind : str
+            The kind of entity builder to retrieve.
+
+        Returns
+        -------
+        EntityBuilder | RuntimeEntityBuilder
+            The builder instance.
+
+        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]
+
+    def get_runtime_builder(self, kind: str) -> RuntimeBuilder:
+        """
+        Retrieve the runtime builder for the given kind, ensuring lazy registration.
+
+        Parameters
+        ----------
+        kind : str
+            The kind of runtime builder to retrieve.
+
+        Returns
+        -------
+        RuntimeBuilder
+            The builder instance.
+
+        Raises
+        ------
+        BuilderError
+            If no builder exists for the specified kind.
+        """
+        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 _ensure_entities_registered(self) -> None:
+        """
+        Ensure core entities are registered on-demand.
+        """
+        if self._entities_registered:
+            return
+        try:
+            self._register_entities()
+            self._entities_registered = True
+        except Exception as e:
+            raise BuilderError(f"Failed to register core entities: {e}")
+
+    def _register_entities(self) -> None:
+        """
+        Register core entity builders into the registry.
+
+        Imports the core entities module and registers all entity
+        builders with the registry.
+        """
+        try:
+            module = import_module(FactoryEnum.REG_ENTITIES.value)
+
+            # 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:
+        """
+        Ensure runtime entities are registered on-demand.
+        """
+        if self._runtimes_registered:
+            return
+        try:
+            self._register_runtimes_entities()
+            self._runtimes_registered = True
+        except Exception as e:
+            raise BuilderError(f"Failed to register runtime entities: {e}")
+
+    def _register_runtimes_entities(self) -> None:
+        """
+        Register all runtime builders and their entities into the registry.
+
+        Imports each runtime package and registers its entity and runtime
+        builders with the registry.
+        """
+        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
+
+
+# Global singleton instance
+registry = BuilderRegistry()

digitalhub/factory/runtime.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+
+from digitalhub.factory.registry import registry
+
+if typing.TYPE_CHECKING:
+    from digitalhub.runtimes._base import Runtime
+
+
+class RuntimeFactory:
+    """
+    Factory for creating and managing runtime builders.
+
+    This class handles the creation of runtimes through their respective builders,
+    using a centralized registry.
+    """
+
+    def build_runtime(self, kind_to_build_from: str, project: str) -> Runtime:
+        """
+        Build a runtime.
+
+        Parameters
+        ----------
+        kind_to_build_from : str
+            Runtime type.
+        project : str
+            Project name.
+
+        Returns
+        -------
+        Runtime
+            Runtime object.
+        """
+        builder = registry.get_runtime_builder(kind_to_build_from)
+        return builder.build(project=project)
+
+
+# Global instance
+runtime_factory = RuntimeFactory()