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

digitalhub/stores/client/dhcore/response_processor.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from warnings import warn
+
+from requests.exceptions import JSONDecodeError
+
+from digitalhub.stores.client.dhcore.error_parser import ErrorParser
+from digitalhub.utils.exceptions import BackendError, ClientError
+
+if typing.TYPE_CHECKING:
+    from requests import Response
+
+
+# API levels that are supported
+MAX_API_LEVEL = 20
+MIN_API_LEVEL = 14
+LIB_VERSION = 14
+
+
+class ResponseProcessor:
+    """
+    Processes and validates HTTP responses from DHCore backend.
+
+    Handles API version validation, error parsing, and response body parsing
+    to dictionary. Supports API versions {MIN_API_LEVEL} to {MAX_API_LEVEL}.
+    """
+
+    def __init__(self) -> None:
+        self._error_parser = ErrorParser()
+
+    def process(self, response: Response) -> dict:
+        """
+        Process HTTP response with validation and parsing.
+
+        Performs API version compatibility check, error parsing for failed
+        responses, and JSON deserialization.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response object from backend.
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary.
+        """
+        self._check_api_version(response)
+        self._error_parser.parse(response)
+        return self._parse_json(response)
+
+    def _check_api_version(self, response: Response) -> None:
+        """
+        Validate DHCore API version compatibility.
+
+        Checks backend API version against supported range and warns if backend
+        version is newer than library. Supported: {MIN_API_LEVEL} to {MAX_API_LEVEL}.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response containing X-Api-Level header.
+        """
+        if "X-Api-Level" not in response.headers:
+            return
+
+        core_api_level = int(response.headers["X-Api-Level"])
+        if not (MIN_API_LEVEL <= core_api_level <= MAX_API_LEVEL):
+            raise ClientError("Backend API level not supported.")
+
+        if LIB_VERSION < core_api_level:
+            warn("Backend API level is higher than library version. You should consider updating the library.")
+
+    @staticmethod
+    def _parse_json(response: Response) -> dict:
+        """
+        Parse HTTP response body to dictionary.
+
+        Converts JSON response to Python dictionary, treating empty responses
+        as valid and returning empty dict.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response object to parse.
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary, or empty dict if body is empty.
+        """
+        try:
+            return response.json()
+        except JSONDecodeError:
+            if response.text == "":
+                return {}
+            raise BackendError("Backend response could not be parsed.")

digitalhub/stores/client/dhcore/utils.py

@@ -4,91 +4,25 @@
 
 from __future__ import annotations
 
-import os
 import typing
 
 from digitalhub.stores.client.api import get_client
-from digitalhub.stores.credentials.enums import CredsEnvVar
 
 if typing.TYPE_CHECKING:
-    from digitalhub.stores.client.dhcore.client import ClientDHCore
-
-
-def set_dhcore_env(
-    endpoint: str | None = None,
-    user: str | None = None,
-    password: str | None = None,
-    access_token: str | None = None,
-    refresh_token: str | None = None,
-    client_id: str | None = None,
-) -> None:
-    """
-    Function to set environment variables for DHCore config.
-
-    Sets the environment variables for DHCore configuration and
-    reloads the client configurator to use the new settings.
-    Note that if the environment variable is already set, it
-    will be overwritten.
-
-    Parameters
-    ----------
-    endpoint : str, optional
-        The endpoint URL of the DHCore backend.
-    user : str, optional
-        The username for basic authentication.
-    password : str, optional
-        The password for basic authentication.
-    access_token : str, optional
-        The OAuth2 access token.
-    refresh_token : str, optional
-        The OAuth2 refresh token.
-    client_id : str, optional
-        The OAuth2 client identifier.
-
-    Returns
-    -------
-    None
-
-    Notes
-    -----
-    After setting the environment variables, this function automatically
-    reloads the client configurator to apply the new configuration.
-    """
-    if endpoint is not None:
-        os.environ[CredsEnvVar.DHCORE_ENDPOINT.value] = endpoint
-    if user is not None:
-        os.environ[CredsEnvVar.DHCORE_USER.value] = user
-    if password is not None:
-        os.environ[CredsEnvVar.DHCORE_PASSWORD.value] = password
-    if access_token is not None:
-        os.environ[CredsEnvVar.DHCORE_ACCESS_TOKEN.value] = access_token
-    if refresh_token is not None:
-        os.environ[CredsEnvVar.DHCORE_REFRESH_TOKEN.value] = refresh_token
-    if client_id is not None:
-        os.environ[CredsEnvVar.DHCORE_CLIENT_ID.value] = client_id
-
-    client: ClientDHCore = get_client(local=False)
-    client._configurator.load_env_vars()
+    pass
 
 
 def refresh_token() -> None:
     """
-    Function to refresh the OAuth2 access token.
+    Refresh the current OAuth2 access token.
 
-    Attempts to refresh the current OAuth2 access token using the
-    refresh token stored in the client configuration. This function
-    requires that the client be configured with OAuth2 authentication.
+    Uses the refresh token stored in client configuration to obtain a new
+    access token. Requires OAuth2 authentication configuration.
 
-    Returns
-    -------
-    None
 
     Raises
     ------
     ClientError
-        If the client is not properly configured or if the token
-        refresh fails.
+        If client not properly configured or token refresh fails.
     """
-    client: ClientDHCore = get_client(local=False)
-    client._configurator.check_config()
-    client._configurator.refresh_credentials()
+    get_client(local=False).refresh_token()

digitalhub/stores/client/local/api_builder.py

@@ -4,8 +4,8 @@
 
 from __future__ import annotations
 
-from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
 from digitalhub.stores.client._base.api_builder import ClientApiBuilder
+from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
 from digitalhub.stores.client.local.enums import LocalClientVar
 from digitalhub.utils.exceptions import BackendError
 

digitalhub/stores/client/local/client.py

@@ -207,7 +207,16 @@ class ClientLocal(Client):
 
             else:
                 name = obj.get("name", entity_id)
-                self._db[entity_type][name][entity_id] = obj
+                container = self._db[entity_type][name]
+                container[entity_id] = obj
+
+                # Keep the "latest" pointer consistent when updating the latest entity
+                try:
+                    if container.get("latest", {}).get("id") == entity_id:
+                        container["latest"] = obj
+                except AttributeError:
+                    # In case "latest" is malformed, ignore and continue
+                    pass
 
         except KeyError:
             msg = self._format_msg(3, entity_type=entity_type, entity_id=entity_id)
@@ -253,55 +262,51 @@ class ClientLocal(Client):
 
                 # Name is optional and extracted from kwargs
                 # "params": {"name": <name>}
-                name = kwargs.get("params", {}).get("name")
+                name_param = kwargs.get("params", {}).get("name")
 
-                # Delete by name
-                if entity_id is None and name is not None:
-                    self._db[entity_type].pop(name, None)
+                # Delete by name (remove the whole named container)
+                if entity_id is None and name_param is not None:
+                    self._db[entity_type].pop(name_param, None)
                     return {"deleted": True}
 
                 # Delete by id
-                for _, v in self._db[entity_type].items():
+                found_name: str | None = None
+                container: dict | None = None
+                for n, v in self._db[entity_type].items():
                     if entity_id in v:
-                        v.pop(entity_id)
-
-                        # Handle latest
-                        if v["latest"]["id"] == entity_id:
-                            name = v["latest"].get("name", entity_id)
-                            v.pop("latest")
-                            reset_latest = True
+                        found_name = n
+                        container = v
                         break
                 else:
                     raise KeyError
 
-                if name is not None:
-                    # Pop name if empty
-                    if not self._db[entity_type][name]:
-                        self._db[entity_type].pop(name)
-
-                    # Handle latest
-                    elif reset_latest:
-                        latest_uuid = None
-                        latest_date = None
-                        for k, v in self._db[entity_type][name].items():
-                            # Get created from metadata. If tzinfo is None, set it to UTC
-                            # If created is not in ISO format, use fallback
-                            fallback = datetime.fromtimestamp(0, timezone.utc)
-                            try:
-                                current_created = datetime.fromisoformat(v.get("metadata", {}).get("created"))
-                                if current_created.tzinfo is None:
-                                    current_created = current_created.replace(tzinfo=timezone.utc)
-                            except ValueError:
-                                current_created = fallback
-
-                            # Update latest date and uuid
-                            if latest_date is None or current_created > latest_date:
-                                latest_uuid = k
-                                latest_date = current_created
-
-                        # Set new latest
-                        if latest_uuid is not None:
-                            self._db[entity_type][name]["latest"] = self._db[entity_type][name][latest_uuid]
+                # Remove the entity from the container
+                assert container is not None  # for type checkers
+                container.pop(entity_id)
+
+                # Handle latest pointer if needed
+                if container.get("latest", {}).get("id") == entity_id:
+                    # Remove stale latest
+                    container.pop("latest", None)
+                    reset_latest = True
+
+                # If container is now empty, drop it entirely
+                if not container:
+                    assert found_name is not None
+                    self._db[entity_type].pop(found_name, None)
+                # Otherwise, recompute latest if required
+                elif reset_latest:
+                    latest_uuid = None
+                    latest_date = None
+                    for k, v in container.items():
+                        # Parse creation time from metadata; tolerate various formats
+                        current_created = self._safe_parse_created(v)
+                        if latest_date is None or current_created > latest_date:
+                            latest_uuid = k
+                            latest_date = current_created
+
+                    if latest_uuid is not None:
+                        container["latest"] = container[latest_uuid]
 
         except KeyError:
             msg = self._format_msg(3, entity_type=entity_type, entity_id=entity_id)
@@ -330,7 +335,10 @@ class ClientLocal(Client):
         # "params": {"name": <name>}
         name = kwargs.get("params", {}).get("name")
         if name is not None:
-            return [self._db[entity_type][name]["latest"]]
+            try:
+                return [self._db[entity_type][name]["latest"]]
+            except KeyError:
+                return []
 
         try:
             # If no name is provided, get latest objects
@@ -343,7 +351,7 @@ class ClientLocal(Client):
         if kind is not None:
             listed_objects = [obj for obj in listed_objects if obj["kind"] == kind]
 
-        # If function is provided, return objects by function
+        # If function/task is provided, return objects by function/task
         spec_params = ["function", "task"]
         for i in spec_params:
             p = kwargs.get("params", {}).get(i)
@@ -489,14 +497,15 @@ class ClientLocal(Client):
         """
         # Deepcopy to avoid modifying the original object
         project = deepcopy(obj)
-        spec = project.get("spec", {})
+        # Ensure spec exists on the returned project
+        spec = project.setdefault("spec", {})
 
         # Get all entities associated with the project specs
         projects_entities = [k for k, _ in self._db.items() if k not in ["projects", "runs", "tasks"]]
 
         for entity_type in projects_entities:
             # Get all objects of the entity type for the project
-            objs = self._db[entity_type]
+            objs = self._db.get(entity_type, {})
 
             # Set empty list
             spec[entity_type] = []
@@ -521,6 +530,29 @@ class ClientLocal(Client):
 
         return project
 
+    @staticmethod
+    def _safe_parse_created(obj: dict) -> datetime:
+        """
+        Safely parse the creation datetime of an object.
+
+        - Accepts ISO format with optional 'Z'.
+        - If tzinfo is missing, assume UTC.
+        - Falls back to epoch if missing/invalid.
+        """
+        created_raw = obj.get("metadata", {}).get("created")
+        fallback = datetime.fromtimestamp(0, timezone.utc)
+        if not created_raw or not isinstance(created_raw, str):
+            return fallback
+        try:
+            # Support trailing 'Z'
+            ts = created_raw.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(ts)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+        except Exception:
+            return fallback
+
     ##############################
     # Utils
     ##############################
@@ -538,9 +570,9 @@ class ClientLocal(Client):
         ----------
         error_code : int
             Error code identifying the type of error.
-        entity_type : str, optional
+        entity_type : str
             Entity type that caused the error.
-        entity_id : str, optional
+        entity_id : str
             Entity ID that caused the error.
 
         Returns

digitalhub/stores/client/local/params_builder.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
+from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
 from digitalhub.stores.client._base.params_builder import ClientParametersBuilder
 
 
@@ -51,10 +51,13 @@ class ClientLocalParametersBuilder(ClientParametersBuilder):
         dict
             Parameters formatted.
         """
-        kwargs = self._set_params(**kwargs)
+        kwargs = self._ensure_params(**kwargs)
+
+        # Handle delete
         if operation == BackendOperations.DELETE.value:
             if (cascade := kwargs.pop("cascade", None)) is not None:
-                kwargs["params"]["cascade"] = str(cascade).lower()
+                kwargs = self._add_param("cascade", str(cascade).lower(), **kwargs)
+
         return kwargs
 
     def build_parameters_context(self, operation: str, **kwargs) -> dict:
@@ -73,48 +76,22 @@ class ClientLocalParametersBuilder(ClientParametersBuilder):
         dict
             Parameters formatted.
         """
-        kwargs = self._set_params(**kwargs)
+        kwargs = self._ensure_params(**kwargs)
 
-        # Handle read
+        # Handle read all versions
         if operation == BackendOperations.READ_ALL_VERSIONS.value:
-            kwargs["params"]["versions"] = "all"
-            kwargs["params"]["name"] = kwargs.pop("entity_name")
+            kwargs = self._add_param("versions", "all", **kwargs)
+            kwargs = self._add_param("name", kwargs.pop("name"), **kwargs)
+
         # Handle delete
         elif operation == BackendOperations.DELETE.value:
-            # Handle cascade
-            if cascade := kwargs.pop("cascade", None) is not None:
-                kwargs["params"]["cascade"] = str(cascade).lower()
-
-            # Handle delete all versions
-            entity_id = kwargs.pop("entity_id")
-            entity_name = kwargs.pop("entity_name")
-            if not kwargs.pop("delete_all_versions", False):
-                if entity_id is None:
-                    raise ValueError(
-                        "If `delete_all_versions` is False, `entity_id` must be provided,"
-                        " either as an argument or in key `identifier`.",
-                    )
-            else:
-                kwargs["params"]["name"] = entity_name
-        return kwargs
-
-    @staticmethod
-    def _set_params(**kwargs) -> dict:
-        """
-        Format params parameter.
+            if (cascade := kwargs.pop("cascade", None)) is not None:
+                kwargs = self._add_param("cascade", str(cascade).lower(), **kwargs)
 
-        Parameters
-        ----------
-        **kwargs : dict
-            Keyword arguments.
+        # Handle delete all versions
+        elif operation == BackendOperations.DELETE_ALL_VERSIONS.value:
+            if (cascade := kwargs.pop("cascade", None)) is not None:
+                kwargs = self._add_param("cascade", str(cascade).lower(), **kwargs)
+            kwargs = self._add_param("name", kwargs.pop("name"), **kwargs)
 
-        Returns
-        -------
-        dict
-            Parameters with initialized params.
-        """
-        if not kwargs:
-            kwargs = {}
-        if "params" not in kwargs:
-            kwargs["params"] = {}
         return kwargs

digitalhub/stores/credentials/api.py

@@ -15,10 +15,6 @@ def set_current_profile(environment: str) -> None:
     ----------
     environment : str
         Name of the credentials profile to set.
-
-    Returns
-    -------
-    None
     """
     creds_handler.set_current_profile(environment)
 

digitalhub/stores/credentials/configurator.py

@@ -53,30 +53,20 @@ class Configurator:
     def load_configs(self) -> None:
         """
         Load the configuration from both environment and file sources.
-
-        Returns
-        -------
-        None
         """
         self.load_env_vars()
         self.load_file_vars()
 
     @abstractmethod
-    def load_env_vars(self) -> None:
-        ...
+    def load_env_vars(self) -> None: ...
 
     @abstractmethod
-    def load_file_vars(self) -> None:
-        ...
+    def load_file_vars(self) -> None: ...
 
     def check_config(self) -> None:
         """
         Check if the current profile has changed and reload
         the file credentials if needed.
-
-        Returns
-        -------
-        None
         """
         if (current := self._creds_handler.get_current_profile()) != self._current_profile:
             self.load_file_vars()
@@ -121,10 +111,6 @@ class Configurator:
         """
         Attempt to change the origin of credentials.
         Raise error if already evaluated.
-
-        Returns
-        -------
-        None
         """
         try:
             self.change_origin()
@@ -134,10 +120,6 @@ class Configurator:
     def change_origin(self) -> None:
         """
         Change the origin of credentials from env to file or vice versa.
-
-        Returns
-        -------
-        None
         """
         if self._changed_origin:
             raise ConfigError("Origin has already been changed.")
@@ -149,10 +131,6 @@ class Configurator:
     def change_to_file(self) -> None:
         """
         Set the credentials origin to file.
-
-        Returns
-        -------
-        None
         """
         if self._origin == self._env:
             self._changed_origin = True
@@ -161,10 +139,6 @@ class Configurator:
     def change_to_env(self) -> None:
         """
         Set the credentials origin to environment.
-
-        Returns
-        -------
-        None
         """
         if self._origin == self._file:
             self._changed_origin = True

digitalhub/stores/credentials/enums.py

@@ -66,3 +66,6 @@ class CredsEnvVar(Enum):
     DHCORE_REFRESH_TOKEN = "DHCORE_REFRESH_TOKEN"
     DHCORE_PERSONAL_ACCESS_TOKEN = "DHCORE_PERSONAL_ACCESS_TOKEN"
     DHCORE_WORKFLOW_IMAGE = "DHCORE_WORKFLOW_IMAGE"
+
+    # OAUTH2
+    OAUTH2_TOKEN_ENDPOINT = "OAUTH2_TOKEN_ENDPOINT"

digitalhub/stores/credentials/handler.py

@@ -64,10 +64,6 @@ class CredentialHandler:
         ----------
         creds_set : str
             Name of the credentials profile to set.
-
-        Returns
-        -------
-        None
         """
         self._profile = creds_set
         set_current_profile(creds_set)
@@ -127,10 +123,6 @@ class CredentialHandler:
         ----------
         creds : dict
             Credentials to write.
-
-        Returns
-        -------
-        None
         """
         write_config(creds, self._profile)
 
@@ -148,10 +140,6 @@ class CredentialHandler:
             The origin of the credentials ('env' or 'file').
         creds : dict
             Credentials to set.
-
-        Returns
-        -------
-        None
         """
         self._creds_store.set_credentials(self._profile, origin, creds)
 

digitalhub/stores/credentials/ini_module.py

@@ -92,9 +92,6 @@ def write_config(creds: dict, environment: str) -> None:
     environment : str
         Name of the credentials profile/environment.
 
-    Returns
-    -------
-    None
 
     Raises
     ------
@@ -129,9 +126,6 @@ def set_current_profile(environment: str) -> None:
     environment : str
         Name of the credentials profile to set as current.
 
-    Returns
-    -------
-    None
 
     Raises
     ------
@@ -146,19 +140,3 @@ def set_current_profile(environment: str) -> None:
 
     except Exception as e:
         raise ClientError(f"Failed to write env file: {e}")
-
-
-def read_env_from_file() -> str | None:
-    """
-    Read the current credentials profile name from the .dhcore.ini file.
-
-    Returns
-    -------
-    str or None
-        Name of the current credentials profile, or None if not found.
-    """
-    try:
-        cfg = load_file()
-        return cfg["DEFAULT"]["current_environment"]
-    except Exception:
-        return None

digitalhub/stores/credentials/store.py

@@ -42,10 +42,6 @@ class CredentialsStore:
             Origin of the credentials ('env' or 'file').
         credentials : dict of str to Any
             Dictionary of credentials to set.
-
-        Returns
-        -------
-        None
         """
         if origin == CredsOrigin.ENV.value:
             for key, value in credentials.items():