digitalhub 0.14.0b1__py3-none-any.whl → 0.14.0b3__py3-none-any.whl

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/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()

digitalhub/runtimes/_base.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from abc import abstractmethod
 from typing import Any, Callable
 
-from digitalhub.factory.factory import factory
+from digitalhub.factory.entity import entity_factory
 from digitalhub.utils.exceptions import EntityError
 from digitalhub.utils.logger import LOGGER
 
@@ -72,7 +72,7 @@ class Runtime:
             raise RuntimeError(msg)
 
         try:
-            return factory.get_action_from_task_kind(task_kind, task_kind)
+            return entity_factory.get_action_from_task_kind(task_kind, task_kind)
         except EntityError:
             msg = f"Task {task_kind} not allowed."
             LOGGER.exception(msg)

digitalhub/stores/client/dhcore/client.py

@@ -58,12 +58,6 @@ class ClientDHCore(Client):
         Parses backend responses and raises appropriate exceptions.
     _configurator : ClientDHCoreConfigurator
         Manages client configuration and authentication.
-
-    Examples
-    --------
-    >>> from digitalhub.stores.client.api import get_client
-    >>> client = get_client(local=False)
-    >>> # Client is now ready for API operations
     """
 
     def __init__(self, config: dict | None = None) -> None:
@@ -75,10 +69,6 @@ class ClientDHCore(Client):
         config : dict, optional
             DHCore environment configuration. If None, loads from environment
             variables and configuration files.
-
-        Returns
-        -------
-        None
         """
         super().__init__()
 
@@ -490,10 +480,6 @@ class ClientDHCore(Client):
         response : Response
             HTTP response containing X-Api-Level header.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         ClientError

digitalhub/stores/client/dhcore/configurator.py

@@ -47,10 +47,6 @@ class ClientDHCoreConfigurator(Configurator):
     def __init__(self) -> None:
         """
         Initialize DHCore configurator and evaluate authentication type.
-
-        Returns
-        -------
-        None
         """
         super().__init__()
         self._auth_type: str | None = None
@@ -66,10 +62,6 @@ class ClientDHCoreConfigurator(Configurator):
 
         Sanitizes endpoint and issuer URLs to ensure proper HTTP/HTTPS schemes
         and removes trailing slashes.
-
-        Returns
-        -------
-        None
         """
         env_creds = self._creds_handler.load_from_env(self.keys)
         env_creds = self._sanitize_env_vars(env_creds)
@@ -107,10 +99,6 @@ class ClientDHCoreConfigurator(Configurator):
 
         Handles keys without "DHCORE_" prefix for CLI compatibility. Falls back
         to environment variables for missing endpoint and personal access token values.
-
-        Returns
-        -------
-        None
         """
         file_creds = self._creds_handler.load_from_file(self.keys)
 
@@ -119,6 +107,11 @@ class ClientDHCoreConfigurator(Configurator):
         if file_creds[pat] is None:
             file_creds[pat] = self._creds_handler.load_from_env([pat]).get(pat)
 
+        # Because in the response there is no endpoint
+        endpoint = CredsEnvVar.DHCORE_ENDPOINT.value
+        if file_creds[endpoint] is None:
+            file_creds[endpoint] = self._creds_handler.load_from_env([endpoint]).get(endpoint)
+
         file_creds = self._sanitize_file_vars(file_creds)
         self._creds_handler.set_credentials(self._file, file_creds)
 
@@ -208,10 +201,6 @@ class ClientDHCoreConfigurator(Configurator):
 
         Changes between environment and file credential sources, then re-evaluates
         authentication type based on the new credentials.
-
-        Returns
-        -------
-        None
         """
         super().change_origin()
 
@@ -230,10 +219,6 @@ class ClientDHCoreConfigurator(Configurator):
         OAUTH2 (access + refresh tokens), ACCESS_TOKEN (access only), BASIC
         (username + password). For EXCHANGE type, automatically exchanges the
         personal access token and switches to file-based credentials storage.
-
-        Returns
-        -------
-        None
         """
         creds = creds_handler.get_credentials(self._origin)
         self._auth_type = self._eval_auth_type(creds)
@@ -305,10 +290,6 @@ class ClientDHCoreConfigurator(Configurator):
         change_origin : bool, default False
             Whether to switch credential sources on auth failure.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         ClientError
@@ -462,10 +443,6 @@ class ClientDHCoreConfigurator(Configurator):
         ----------
         response : dict
             OAuth2 token response with new credentials.
-
-        Returns
-        -------
-        None
         """
         for key in self.keys_to_prefix:
             key = key.lower()

digitalhub/stores/client/dhcore/error_parser.py

@@ -44,10 +44,6 @@ class ErrorParser:
         response : Response
             The HTTP response object from requests.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         TimeoutError