digitalhub 0.10.3__py3-none-any.whl → 0.11.0__py3-none-any.whl

digitalhub/factory/factory.py

@@ -8,7 +8,7 @@ if typing.TYPE_CHECKING:
     from digitalhub.entities._base.entity.builder import EntityBuilder
     from digitalhub.entities._base.entity.entity import Entity
     from digitalhub.entities._base.entity.metadata import Metadata
-    from digitalhub.entities._base.entity.spec import Spec
+    from digitalhub.entities._base.entity.spec import Spec, SpecValidator
     from digitalhub.entities._base.entity.status import Status
     from digitalhub.entities._base.runtime_entity.builder import RuntimeEntityBuilder
     from digitalhub.runtimes._base import Runtime
@@ -17,7 +17,26 @@ if typing.TYPE_CHECKING:
 
 class Factory:
     """
-    Factory class for building entities and runtimes.
+    Factory for creating and managing entity and runtime builders.
+
+    This class implements the Factory pattern to manage the creation of
+    entities and runtimes through their respective builders. It maintains
+    separate registries for entity and runtime builders.
+
+    Many function arguments are called kind_to_build_from to avoid overwriting
+    kind in kwargs.
+
+    Attributes
+    ----------
+    _entity_builders : dict[str, EntityBuilder | RuntimeEntityBuilder]
+        Registry of entity builders indexed by kind.
+    _runtime_builders : dict[str, RuntimeBuilder]
+        Registry of runtime builders indexed by kind.
+
+    Notes
+    -----
+    All builder methods may raise BuilderError if the requested kind
+    is not found in the registry.
     """
 
     def __init__(self):
@@ -26,18 +45,19 @@ class Factory:
 
     def add_entity_builder(self, name: str, builder: EntityBuilder | RuntimeEntityBuilder) -> None:
         """
-        Add a builder to the factory.
+        Register an entity builder.
 
         Parameters
         ----------
         name : str
-            Builder name.
-        builder : EntityBuilder
-            Builder object.
-
-        Returns
-        -------
-        None
+            The unique identifier for the builder.
+        builder : EntityBuilder | RuntimeEntityBuilder
+            The builder instance to register.
+
+        Raises
+        ------
+        BuilderError
+            If a builder with the same name already exists.
         """
         if name in self._entity_builders:
             raise BuilderError(f"Builder {name} already exists.")
@@ -45,31 +65,30 @@ class Factory:
 
     def add_runtime_builder(self, name: str, builder: RuntimeBuilder) -> None:
         """
-        Add a builder to the factory.
+        Register a runtime builder.
 
         Parameters
         ----------
         name : str
-            Builder name.
+            The unique identifier for the builder.
         builder : RuntimeBuilder
-            Builder object.
+            The builder instance to register.
 
-        Returns
-        -------
-        None
+        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 build_entity_from_params(self, kind_to_build_from: str, **kwargs) -> Entity:
+    def build_entity_from_params(self, **kwargs) -> Entity:
         """
         Build an entity from parameters.
 
         Parameters
         ----------
-        kind_to_build_from : str
-            Entity type.
         **kwargs
             Entity parameters.
 
@@ -78,17 +97,20 @@ class Factory:
         Entity
             Entity object.
         """
-        return self._entity_builders[kind_to_build_from].build(**kwargs)
-
-    def build_entity_from_dict(self, kind_to_build_from: str, obj: dict) -> Entity:
+        try:
+            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)
+
+    def build_entity_from_dict(self, obj: dict) -> Entity:
         """
         Build an entity from a dictionary.
 
         Parameters
         ----------
-        kind_to_build_from : str
-            Entity type.
-        dict_data : dict
+        obj : dict
             Dictionary with entity data.
 
         Returns
@@ -96,7 +118,12 @@ class Factory:
         Entity
             Entity object.
         """
-        return self._entity_builders[kind_to_build_from].from_dict(obj)
+        try:
+            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)
 
     def build_spec(self, kind_to_build_from: str, **kwargs) -> Spec:
         """
@@ -112,6 +139,7 @@ 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)
 
     def build_metadata(self, kind_to_build_from: str, **kwargs) -> Metadata:
@@ -128,6 +156,7 @@ 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)
 
     def build_status(self, kind_to_build_from: str, **kwargs) -> Status:
@@ -144,6 +173,7 @@ 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)
 
     def build_runtime(self, kind_to_build_from: str, project: str) -> Runtime:
@@ -162,6 +192,7 @@ 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)
 
     def get_entity_type_from_kind(self, kind: str) -> str:
@@ -178,6 +209,7 @@ class Factory:
         str
             Entity type.
         """
+        self._raise_if_entity_builder_not_found(kind)
         return self._entity_builders[kind].get_entity_type()
 
     def get_executable_kind(self, kind: str) -> str:
@@ -194,6 +226,7 @@ class Factory:
         str
             Executable kind.
         """
+        self._raise_if_entity_builder_not_found(kind)
         return self._entity_builders[kind].get_executable_kind()
 
     def get_action_from_task_kind(self, kind: str, task_kind: str) -> str:
@@ -212,6 +245,7 @@ class Factory:
         str
             Action.
         """
+        self._raise_if_entity_builder_not_found(kind)
         return self._entity_builders[kind].get_action_from_task_kind(task_kind)
 
     def get_task_kind_from_action(self, kind: str, action: str) -> list[str]:
@@ -230,6 +264,7 @@ class Factory:
         list[str]
             Task kinds.
         """
+        self._raise_if_entity_builder_not_found(kind)
         return self._entity_builders[kind].get_task_kind_from_action(action)
 
     def get_run_kind(self, kind: str) -> str:
@@ -246,6 +281,7 @@ class Factory:
         str
             Run kind.
         """
+        self._raise_if_entity_builder_not_found(kind)
         return self._entity_builders[kind].get_run_kind()
 
     def get_all_kinds(self, kind: str) -> list[str]:
@@ -264,5 +300,56 @@ class Factory:
         """
         return self._entity_builders[kind].get_all_kinds()
 
+    def get_spec_validator(self, kind: str) -> SpecValidator:
+        """
+        Get spec validators.
+
+        Parameters
+        ----------
+        kind : str
+            Kind.
+
+        Returns
+        -------
+        SpecValidator
+            Spec validator.
+        """
+        self._raise_if_entity_builder_not_found(kind)
+        return self._entity_builders[kind].get_spec_validator()
+
+    def _raise_if_entity_builder_not_found(self, kind: str) -> None:
+        """
+        Verify entity builder existence.
+
+        Parameters
+        ----------
+        kind : str
+            The entity kind to verify.
+
+        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.")
+
+    def _raise_if_runtime_builder_not_found(self, kind: str) -> None:
+        """
+        Verify runtime builder existence.
+
+        Parameters
+        ----------
+        kind : str
+            The runtime kind to verify.
+
+        Raises
+        ------
+        BuilderError
+            If no builder exists for the specified kind.
+        """
+        if kind not in self._runtime_builders:
+            raise BuilderError(f"Runtime builder for kind '{kind}' not found.")
+
 
 factory = Factory()

digitalhub/factory/utils.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import importlib
-import importlib.metadata
 import pkgutil
 import re
 from types import ModuleType
@@ -11,17 +10,24 @@ from digitalhub.factory.factory import factory
 
 def import_module(package: str) -> ModuleType:
     """
-    Import modules from package name.
+    Import a module dynamically by package name.
 
     Parameters
     ----------
     package : str
-        Package name.
+        The fully qualified package name to import.
 
     Returns
     -------
     ModuleType
-        Module.
+        The imported module object.
+
+    Raises
+    ------
+    ModuleNotFoundError
+        If the specified package cannot be found.
+    RuntimeError
+        If any other error occurs during import.
     """
     try:
         return importlib.import_module(package)
@@ -33,12 +39,20 @@ def import_module(package: str) -> ModuleType:
 
 def list_runtimes() -> list[str]:
     """
-    List installed runtimes for digitalhub.
+    List all installed DigitalHub runtime packages.
+
+    Scans installed packages for those matching the pattern
+    'digitalhub_runtime_*'.
 
     Returns
     -------
     list[str]
-        List of installed runtimes names.
+        List of runtime package names.
+
+    Raises
+    ------
+    RuntimeError
+        If an error occurs while scanning for runtime packages.
     """
     pattern = r"digitalhub_runtime_.*"
     runtimes: list[str] = []
@@ -53,11 +67,10 @@ def list_runtimes() -> list[str]:
 
 def register_runtimes_entities() -> None:
     """
-    Register runtimes and related entities into registry.
+    Register all runtime builders and their entities into the factory.
 
-    Returns
-    -------
-    None
+    Imports each runtime package and registers its entity and runtime
+    builders with the global factory instance.
     """
     for package in list_runtimes():
         module = import_module(package)
@@ -74,11 +87,15 @@ def register_runtimes_entities() -> None:
 
 def register_entities() -> None:
     """
-    Register layer and related entities into registry.
+    Register core entity builders into the factory.
 
-    Returns
-    -------
-    None
+    Imports the core entities module and registers all entity builders
+    with the global factory instance.
+
+    Raises
+    ------
+    RuntimeError
+        If registration of core entities fails.
     """
     try:
         module = import_module("digitalhub.entities.builders")

digitalhub/runtimes/_base.py

@@ -3,14 +3,14 @@ from __future__ import annotations
 from abc import abstractmethod
 from typing import Any, Callable
 
-from digitalhub.factory.api import get_action_from_task_kind
+from digitalhub.factory.factory import factory
 from digitalhub.utils.exceptions import EntityError
 from digitalhub.utils.logger import LOGGER
 
 
 class Runtime:
     """
-    Base Runtime class.
+    Base Runtime class for executing tasks in the DigitalHub platform.
 
     Runtimes are the entities responsible for the actual execution
     of a given run. They are highly specialized components which
@@ -25,13 +25,13 @@ class Runtime:
     @abstractmethod
     def build(self, executable: dict, task: dict, run: dict) -> dict:
         """
-        Build run spec.
+        Build run specification from executable, task and run configurations.
         """
 
     @abstractmethod
     def run(self, run: dict) -> dict:
         """
-        Execute run task.
+        Execute run task based on the run specification.
         """
 
     ##############################
@@ -40,9 +40,10 @@ class Runtime:
 
     def _validate_task(self, run: dict) -> str:
         """
-        Check if task is allowed. This presumes that the
-        runtime holds a list of allowed actions in the self.allowed_actions
-        attribute.
+        Check if task is allowed by validating against allowed actions.
+
+        This method presumes that the runtime holds a list of allowed actions
+        in the self.allowed_actions attribute.
 
         Parameters
         ----------
@@ -52,7 +53,12 @@ class Runtime:
         Returns
         -------
         str
-            Action to execute.
+            The validated action name to execute.
+
+        Raises
+        ------
+        RuntimeError
+            If the run specification is malformed or task is not allowed.
         """
         try:
             task_kind = run["spec"]["task"].split(":")[0]
@@ -62,7 +68,7 @@ class Runtime:
             raise RuntimeError(msg)
 
         try:
-            return get_action_from_task_kind(task_kind, task_kind)
+            return factory.get_action_from_task_kind(task_kind, task_kind)
         except EntityError:
             msg = f"Task {task_kind} not allowed."
             LOGGER.exception(msg)
@@ -71,7 +77,7 @@ class Runtime:
     @staticmethod
     def _execute(func: Callable, *args, **kwargs) -> Any:
         """
-        Execute function.
+        Execute a function with provided arguments safely.
 
         Parameters
         ----------
@@ -85,7 +91,12 @@ class Runtime:
         Returns
         -------
         Any
-            Function result.
+            Function return value.
+
+        Raises
+        ------
+        RuntimeError
+            If any exception occurs during function execution.
         """
         try:
             return func(*args, **kwargs)

digitalhub/runtimes/builder.py

@@ -10,10 +10,23 @@ if typing.TYPE_CHECKING:
 
 class RuntimeBuilder:
     """
-    Builder class for building runtimes.
+    Builder class for instantiating runtime objects.
+
+    This class implements the Builder pattern to create Runtime instances.
+    Subclasses must set the RUNTIME_CLASS class variable to specify which
+    Runtime implementation to build.
+
+    Attributes
+    ----------
+    RUNTIME_CLASS : Runtime
+        The Runtime class to be instantiated by this builder.
+
+    Raises
+    ------
+    BuilderError
+        If RUNTIME_CLASS is not set in the implementing class.
     """
 
-    # Class variables
     RUNTIME_CLASS: Runtime = None
 
     def __init__(self) -> None:
@@ -27,6 +40,6 @@ class RuntimeBuilder:
         Returns
         -------
         Runtime
-            Runtime object.
+            A new instance of the configured Runtime class.
         """
         return self.RUNTIME_CLASS(project, *args, **kwargs)

digitalhub/runtimes/enums.py

@@ -5,7 +5,17 @@ from enum import Enum
 
 class RuntimeEnvVar(Enum):
     """
-    Environment variables.
+    Environment variables used by runtime execution environments.
+
+    These variables are automatically set in the runtime context
+    and can be accessed during task execution.
+
+    Values
+    ------
+    PROJECT : str
+        Environment variable name for the current project identifier
+    RUN_ID : str
+        Environment variable name for the current run identifier
     """
 
     PROJECT = "PROJECT_NAME"

digitalhub/stores/client/api.py

@@ -24,4 +24,4 @@ def get_client(local: bool = False, config: dict | None = None) -> Client:
     Client
         The client instance.
     """
-    return client_builder.build(local)
+    return client_builder.build(local, config)

digitalhub/stores/client/builder.py

@@ -23,7 +23,7 @@ class ClientBuilder:
         self._local = None
         self._dhcore = None
 
-    def build(self, local: bool = False) -> Client:
+    def build(self, local: bool = False, config: dict | None = None) -> Client:
         """
         Method to create a client instance.
 
@@ -43,7 +43,7 @@ class ClientBuilder:
             return self._local
 
         if self._dhcore is None:
-            self._dhcore = ClientDHCore()
+            self._dhcore = ClientDHCore(config)
         return self._dhcore
 
 

digitalhub/stores/client/dhcore/client.py

@@ -35,7 +35,7 @@ class ClientDHCore(Client):
     configuration, otherwise it simply set the environment variables.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, config: dict | None = None) -> None:
         super().__init__()
 
         # API builder
@@ -52,7 +52,7 @@ class ClientDHCore(Client):
 
         # Client Configurator
         self._configurator = ClientDHCoreConfigurator()
-        self._configurator.configure()
+        self._configurator.configure(config)
 
     ##############################
     # CRUD methods

digitalhub/stores/client/dhcore/configurator.py

@@ -22,8 +22,8 @@ AUTH_KEY = "_auth"
 
 # API levels that are supported
 MAX_API_LEVEL = 20
-MIN_API_LEVEL = 10
-LIB_VERSION = 10
+MIN_API_LEVEL = 11
+LIB_VERSION = 11
 
 
 class ClientDHCoreConfigurator:
@@ -54,7 +54,7 @@ class ClientDHCoreConfigurator:
         if configurator.get_current_env() != self._current_env:
             self.configure()
 
-    def configure(self) -> None:
+    def configure(self, config: dict | None = None) -> None:
         """
         Configure the client attributes with config (given or from
         environment).
@@ -63,6 +63,11 @@ class ClientDHCoreConfigurator:
         over the basic auth. Furthermore, the config parameter is
         validated against the proper pydantic model.
 
+        Parameters
+        ----------
+        config : dict
+            Configuration dictionary.
+
         Returns
         -------
         None
@@ -292,6 +297,7 @@ class ClientDHCoreConfigurator:
                 DhcoreEnvVar.REFRESH_TOKEN.value,
                 DhcoreEnvVar.ACCESS_TOKEN.value,
                 DhcoreEnvVar.ISSUER.value,
+                DhcoreEnvVar.CLIENT_ID.value,
             ):
                 new_list.append(key.removeprefix("DHCORE_"))
             else:
@@ -339,7 +345,7 @@ class ClientDHCoreConfigurator:
             Response object.
         """
         # Get client id
-        client_id = configurator.load_var(DhcoreEnvVar.CLIENT_ID.value)
+        client_id = self._load_dhcore_oauth_vars(DhcoreEnvVar.CLIENT_ID.value)
         if client_id is None:
             raise ClientError("Client id not set.")
 

digitalhub/stores/configurator/configurator.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import os
 
 from digitalhub.stores.configurator.credentials_store import CredentialsStore
+from digitalhub.stores.configurator.enums import SetCreds
 from digitalhub.stores.configurator.ini_module import load_from_file, read_env_from_file, set_current_env, write_config
 
 
@@ -16,7 +17,7 @@ class EnvConfigurator:
         self._creds_store = CredentialsStore()
 
         # Current credentials set (__default by default)
-        self._environment = "__default"
+        self._environment = os.getenv(SetCreds.DH_ENV.value, SetCreds.DEFAULT.value)
 
     ##############################
     # Public methods

digitalhub/stores/configurator/enums.py

@@ -10,3 +10,12 @@ class CredsOrigin(Enum):
 
     ENV = "env"
     FILE = "file"
+
+
+class SetCreds(Enum):
+    """
+    List supported environments.
+    """
+
+    DEFAULT = "__default"
+    DH_ENV = "DH_NAME"

digitalhub/stores/data/api.py

@@ -8,7 +8,7 @@ if typing.TYPE_CHECKING:
     from digitalhub.stores.data._base.store import Store
 
 
-def get_store(project: str, uri: str, config: dict | None = None) -> Store:
+def get_store(project: str, uri: str) -> Store:
     """
     Get store instance by URI.
 
@@ -26,4 +26,4 @@ def get_store(project: str, uri: str, config: dict | None = None) -> Store:
     Store
         Store instance.
     """
-    return store_builder.get(uri, config)
+    return store_builder.get(project, uri)

digitalhub/stores/data/builder.py

@@ -44,9 +44,9 @@ class StoreBuilder:
     """
 
     def __init__(self) -> None:
-        self._instances: dict[str, Store] = {}
+        self._instances: dict[str, dict[str, Store]] = {}
 
-    def build(self, store_type: str, config: dict | None = None) -> None:
+    def build(self, project: str, store_type: str) -> None:
         """
         Build a store instance and register it.
 
@@ -55,7 +55,6 @@ class StoreBuilder:
         store_type : str
             Store type.
         config : dict
-            Store configuration.
 
         Returns
         -------
@@ -66,7 +65,7 @@ class StoreBuilder:
             self._instances[env] = {}
         self._instances[env][store_type] = _get_class_from_type(store_type)()
 
-    def get(self, uri: str, config: dict | None = None) -> Store:
+    def get(self, project: str, uri: str) -> Store:
         """
         Get a store instance by URI.
 
@@ -87,7 +86,7 @@ class StoreBuilder:
         try:
             return self._instances[env][store_type]
         except KeyError:
-            self.build(store_type, config)
+            self.build(project, store_type)
             return self._instances[env][store_type]