digitalhub 0.10.2__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/dhcore/client.py

@@ -276,6 +276,7 @@ class ClientDHCore(Client):
         dict
             Response object.
         """
+        self._configurator.check_config()
         if kwargs is None:
             kwargs = {}
         url = self._configurator.build_url(api)

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:
@@ -31,10 +31,29 @@ class ClientDHCoreConfigurator:
     Configurator object used to configure the client.
     """
 
+    def __init__(self) -> None:
+        self._current_env = configurator.get_current_env()
+
     ##############################
     # Configuration methods
     ##############################
 
+    def check_config(self) -> None:
+        """
+        Check if the config is valid.
+
+        Parameters
+        ----------
+        config : dict
+            Configuration dictionary.
+
+        Returns
+        -------
+        None
+        """
+        if configurator.get_current_env() != self._current_env:
+            self.configure()
+
     def configure(self, config: dict | None = None) -> None:
         """
         Configure the client attributes with config (given or from
@@ -140,10 +159,10 @@ class ClientDHCoreConfigurator:
         None
         """
         # Give priority to access token
-        access_token = configurator.load_var(DhcoreEnvVar.ACCESS_TOKEN.value)
+        access_token = self._load_dhcore_oauth_vars(DhcoreEnvVar.ACCESS_TOKEN.value)
         if access_token is not None:
             configurator.set_credential(AUTH_KEY, AuthType.OAUTH2.value)
-            configurator.set_credential(DhcoreEnvVar.ACCESS_TOKEN.value, access_token)
+            configurator.set_credential(DhcoreEnvVar.ACCESS_TOKEN.value.removeprefix("DHCORE_"), access_token)
 
         # Fallback to basic
         else:
@@ -204,7 +223,7 @@ class ClientDHCoreConfigurator:
         elif self.oauth2_auth():
             if "headers" not in kwargs:
                 kwargs["headers"] = {}
-            access_token = creds[DhcoreEnvVar.ACCESS_TOKEN.value]
+            access_token = creds[DhcoreEnvVar.ACCESS_TOKEN.value.removeprefix("DHCORE_")]
             kwargs["headers"]["Authorization"] = f"Bearer {access_token}"
         return kwargs
 
@@ -227,7 +246,7 @@ class ClientDHCoreConfigurator:
 
         # Otherwise try token from file
         if response.status_code in (400, 401, 403):
-            refresh_token = configurator.load_from_file(DhcoreEnvVar.REFRESH_TOKEN.value)
+            refresh_token = configurator.load_from_file(DhcoreEnvVar.REFRESH_TOKEN.value.removeprefix("DHCORE_"))
             response = self._call_refresh_token_endpoint(url, refresh_token)
 
         response.raise_for_status()
@@ -248,12 +267,43 @@ class ClientDHCoreConfigurator:
         -------
         None
         """
-        keys = list_enum(DhcoreEnvVar) + list_enum(S3StoreEnv) + list_enum(SqlStoreEnv)
+        keys = [
+            *self._remove_prefix_dhcore(list_enum(DhcoreEnvVar)),
+            *list_enum(S3StoreEnv),
+            *list_enum(SqlStoreEnv),
+        ]
         for key in keys:
-            if (value := response.get(key.lower().removeprefix("dhcore_"))) is not None:
+            if (value := response.get(key.lower())) is not None:
                 configurator.set_credential(key, value)
         configurator.write_env(keys)
 
+    def _remove_prefix_dhcore(self, keys: list[str]) -> list[str]:
+        """
+        Remove prefix from selected keys. (Compatibility with CLI)
+
+        Parameters
+        ----------
+        keys : list[str]
+            List of keys.
+
+        Returns
+        -------
+        list[str]
+            List of keys without prefix.
+        """
+        new_list = []
+        for key in keys:
+            if key in (
+                DhcoreEnvVar.REFRESH_TOKEN.value,
+                DhcoreEnvVar.ACCESS_TOKEN.value,
+                DhcoreEnvVar.ISSUER.value,
+                DhcoreEnvVar.CLIENT_ID.value,
+            ):
+                new_list.append(key.removeprefix("DHCORE_"))
+            else:
+                new_list.append(key)
+        return new_list
+
     def _get_refresh_endpoint(self) -> str:
         """
         Get the refresh endpoint.
@@ -264,11 +314,11 @@ class ClientDHCoreConfigurator:
             Refresh endpoint.
         """
         # Get issuer endpoint
-        endpoint_issuer = configurator.load_var(DhcoreEnvVar.ISSUER.value)
+        endpoint_issuer = self._load_dhcore_oauth_vars(DhcoreEnvVar.ISSUER.value)
         if endpoint_issuer is None:
             raise ClientError("Issuer endpoint not set.")
         endpoint_issuer = self._sanitize_endpoint(endpoint_issuer)
-        configurator.set_credential(DhcoreEnvVar.ISSUER.value, endpoint_issuer)
+        configurator.set_credential(DhcoreEnvVar.ISSUER.value.removeprefix("DHCORE_"), endpoint_issuer)
 
         # Standard issuer endpoint path
         url = endpoint_issuer + "/.well-known/openid-configuration"
@@ -295,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.")
 
@@ -308,3 +358,22 @@ class ClientDHCoreConfigurator:
         }
         headers = {"Content-Type": "application/x-www-form-urlencoded"}
         return request("POST", url, data=payload, headers=headers, timeout=60)
+
+    def _load_dhcore_oauth_vars(self, oauth_var: str) -> str | None:
+        """
+        Load DHCore oauth variables.
+
+        Parameters
+        ----------
+        oauth_var : str
+            The oauth variable to load.
+
+        Returns
+        -------
+        str
+            The oauth variable.
+        """
+        read_var = configurator.load_from_env(oauth_var)
+        if read_var is None:
+            read_var = configurator.load_from_file(oauth_var.removeprefix("DHCORE_"))
+        return read_var

digitalhub/stores/client/dhcore/utils.py

@@ -68,4 +68,5 @@ def refresh_token() -> None:
     None
     """
     client: ClientDHCore = get_client(local=False)
+    client._configurator.check_config()
     client._configurator.get_new_access_token()