digitalhub 0.13.0b3__py3-none-any.whl → 0.14.9__py3-none-any.whl

digitalhub/stores/client/{_base/key_builder.py → key_builder.py}

@@ -4,9 +4,7 @@
 
 from __future__ import annotations
 
-from abc import abstractmethod
-
-from digitalhub.entities._commons.enums import ApiCategories
+from digitalhub.stores.client.enums import ApiCategories
 
 
 class ClientKeyBuilder:
@@ -36,7 +34,6 @@ class ClientKeyBuilder:
             return self.base_entity_key(*args, **kwargs)
         return self.context_entity_key(*args, **kwargs)
 
-    @abstractmethod
     def base_entity_key(self, entity_id: str) -> str:
         """
         Build for base entity key.
@@ -44,15 +41,15 @@ class ClientKeyBuilder:
         Parameters
         ----------
         entity_id : str
-            The entity identifier.
+            Entity id.
 
         Returns
         -------
         str
-            The formatted base entity key.
+            Key.
         """
+        return f"store://{entity_id}"
 
-    @abstractmethod
     def context_entity_key(
         self,
         project: str,
@@ -67,18 +64,21 @@ class ClientKeyBuilder:
         Parameters
         ----------
         project : str
-            The project name.
+            Project name.
         entity_type : str
-            The entity type.
+            Entity type.
         entity_kind : str
-            The entity kind.
+            Entity kind.
         entity_name : str
-            The entity name.
-        entity_id : str, optional
-            The entity identifier. If None, key will not include version.
+            Entity name.
+        entity_id : str
+            Entity ID.
 
         Returns
         -------
         str
-            The formatted context entity key.
+            Key.
         """
+        if entity_id is None:
+            return f"store://{project}/{entity_type}/{entity_kind}/{entity_name}"
+        return f"store://{project}/{entity_type}/{entity_kind}/{entity_name}:{entity_id}"

digitalhub/stores/client/params_builder.py

@@ -0,0 +1,330 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+from digitalhub.stores.client.enums import ApiCategories, BackendOperations
+
+DEFAULT_START_PAGE = 0
+DEFAULT_SIZE = 25
+DEFAULT_SORT = "metadata.updated,DESC"
+
+
+class ClientParametersBuilder:
+    """
+    Parameter builder for DHCore client API calls.
+
+    Constructs HTTP request parameters for DHCore API operations, handling
+    parameter formats and query structures for both base-level operations
+    (project management) and context-level operations (entity operations
+    within projects). Supports query parameter formatting, search filter
+    construction for Solr-based searches, cascade deletion options,
+    versioning parameters, and entity sharing parameters.
+    """
+
+    def build_parameters(self, category: str, operation: str, **kwargs) -> dict:
+        """
+        Build HTTP request parameters for DHCore API calls.
+
+        Parameters
+        ----------
+        category : str
+            API category: 'base' for project-level operations or 'context'
+            for entity operations within projects.
+        operation : str
+            Specific API operation (create, read, update, delete, list, search, etc.).
+        **kwargs : dict
+            Raw parameters to transform including entity identifiers, filter
+            criteria, pagination options, etc.
+
+        Returns
+        -------
+        dict
+            Formatted parameters dictionary with 'params' key for query parameters
+            and other request-specific parameters.
+        """
+        if category == ApiCategories.BASE.value:
+            return self.build_parameters_base(operation, **kwargs)
+        return self.build_parameters_context(operation, **kwargs)
+
+    def build_parameters_base(self, operation: str, **kwargs) -> dict:
+        """
+        Constructs HTTP request parameters for project operations.
+
+        Parameters
+        ----------
+        operation : str
+            API operation.
+        **kwargs : dict
+            Operation-specific parameters.
+        Returns
+        -------
+        dict
+            Formatted parameters with 'params' containing query parameters.
+        """
+        kwargs = self._ensure_params(**kwargs)
+
+        # Handle delete
+        if operation == BackendOperations.DELETE.value:
+            if (cascade := kwargs.pop("cascade", None)) is not None:
+                kwargs = self._add_param("cascade", str(cascade).lower(), **kwargs)
+
+        # Handle share
+        elif operation == BackendOperations.SHARE.value:
+            kwargs = self._add_param("user", kwargs.pop("user"), **kwargs)
+            if kwargs.pop("unshare", False):
+                kwargs = self._add_param("id", kwargs.pop("id"), **kwargs)
+
+        return kwargs
+
+    def build_parameters_context(self, operation: str, **kwargs) -> dict:
+        """
+        Constructs HTTP request parameters for entity management and search within
+        projects.
+
+        Parameters
+        ----------
+        operation : str
+            API operation.
+        **kwargs : dict
+            Operation-specific parameters.
+
+        Returns
+        -------
+        dict
+            Formatted parameters with 'params'.
+        """
+        kwargs = self._ensure_params(**kwargs)
+
+        # Handle read
+        if operation == BackendOperations.READ.value:
+            if (name := kwargs.pop("name", None)) is not None:
+                kwargs = self._add_param("name", name, **kwargs)
+
+        # Handle read all versions
+        elif operation == BackendOperations.READ_ALL_VERSIONS.value:
+            kwargs = self._add_param("versions", "all", **kwargs)
+            kwargs = self._add_param("name", kwargs.pop("name"), **kwargs)
+
+        # Handle list
+        elif operation == BackendOperations.LIST.value:
+            possible_list_params = [
+                "q",
+                "name",
+                "kind",
+                "user",
+                "state",
+                "created",
+                "updated",
+                "versions",
+                "function",
+                "workflow",
+                "action",
+                "task",
+            ]
+            list_params = {k: kwargs.get(k, None) for k in possible_list_params}
+            list_params = self._filter_none_params(**list_params)
+            for k, v in list_params.items():
+                kwargs = self._add_param(k, v, **kwargs)
+            for k in possible_list_params:
+                kwargs.pop(k, None)
+
+        # Handle delete
+        elif operation == BackendOperations.DELETE.value:
+            if (cascade := kwargs.pop("cascade", None)) is not None:
+                kwargs = self._add_param("cascade", str(cascade).lower(), **kwargs)
+
+        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)
+
+        # Handle search
+        elif operation == BackendOperations.SEARCH.value:
+            # Handle fq
+            if (fq := kwargs.pop("fq", None)) is not None:
+                kwargs = self._add_param("fq", fq, **kwargs)
+
+            # Add search query
+            if (query := kwargs.pop("query", None)) is not None:
+                kwargs = self._add_param("q", query, **kwargs)
+
+            # Add search filters
+            fq = []
+
+            # Entity types
+            if (entity_types := kwargs.pop("entity_types", None)) is not None:
+                if not isinstance(entity_types, list):
+                    entity_types = [entity_types]
+                if len(entity_types) == 1:
+                    entity_types = entity_types[0]
+                else:
+                    entity_types = " OR ".join(entity_types)
+                fq.append(f"type:({entity_types})")
+
+            # Name
+            if (name := kwargs.pop("name", None)) is not None:
+                fq.append(f'metadata.name:"{name}"')
+
+            # Kind
+            if (kind := kwargs.pop("kind", None)) is not None:
+                fq.append(f'kind:"{kind}"')
+
+            # Time
+            created = kwargs.pop("created", None)
+            updated = kwargs.pop("updated", None)
+            created = created if created is not None else "*"
+            updated = updated if updated is not None else "*"
+            fq.append(f"metadata.updated:[{created} TO {updated}]")
+
+            # Description
+            if (description := kwargs.pop("description", None)) is not None:
+                fq.append(f'metadata.description:"{description}"')
+
+            # Labels
+            if (labels := kwargs.pop("labels", None)) is not None:
+                if len(labels) == 1:
+                    labels = labels[0]
+                else:
+                    labels = " AND ".join(labels)
+                fq.append(f"metadata.labels:({labels})")
+
+            # Add filters
+            kwargs = self._add_param("fq", fq, **kwargs)
+
+        return kwargs
+
+    def set_pagination(self, partial: bool = False, **kwargs) -> dict:
+        """
+        Ensure pagination parameters are set in kwargs.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Pagination parameters set in 'params' of kwargs.
+        """
+        kwargs = self._ensure_params(**kwargs)
+
+        if "page" not in kwargs["params"]:
+            kwargs["params"]["page"] = DEFAULT_START_PAGE
+
+        if partial:
+            return kwargs
+
+        if "size" not in kwargs["params"]:
+            kwargs["params"]["size"] = DEFAULT_SIZE
+
+        if "sort" not in kwargs["params"]:
+            kwargs["params"]["sort"] = DEFAULT_SORT
+
+        return kwargs
+
+    @staticmethod
+    def _ensure_params(**kwargs) -> dict:
+        """
+        Initialize parameter dictionary with query parameters structure.
+
+        Ensures parameter dictionary has 'params' key for HTTP query parameters,
+        guaranteeing consistent structure for all parameter building methods.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with guaranteed 'params' key containing
+            empty dict if not already present.
+        """
+        if "params" not in kwargs:
+            kwargs["params"] = {}
+        return kwargs
+
+    @staticmethod
+    def _add_param(key: str, value: Any | None, **kwargs) -> dict:
+        """
+        Add a single query parameter to kwargs.
+
+        Parameters
+        ----------
+        key : str
+            Parameter key.
+        value : Any
+            Parameter value.
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with added key-value pair in 'params'.
+        """
+        kwargs["params"][key] = value
+        return kwargs
+
+    @staticmethod
+    def read_page_number(**kwargs) -> int:
+        """
+        Read current page number from kwargs.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        int
+            Current page number.
+        """
+        return kwargs["params"]["page"]
+
+    @staticmethod
+    def increment_page_number(**kwargs) -> dict:
+        """
+        Increment page number in kwargs.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with incremented 'page' number in 'params'.
+        """
+        kwargs["params"]["page"] += 1
+        return kwargs
+
+    @staticmethod
+    def _filter_none_params(**kwargs) -> dict:
+        """
+        Filter out None values from kwargs.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to filter.
+
+        Returns
+        -------
+        dict
+            Filtered kwargs.
+        """
+        return {k: v for k, v in kwargs.items() if v is not None}

digitalhub/stores/client/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.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/utils.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from digitalhub.stores.client.builder import get_client
+
+
+def refresh_token() -> None:
+    """
+    Refresh the current OAuth2 access token.
+
+    Uses the refresh token stored in client configuration to obtain a new
+    access token. Requires OAuth2 authentication configuration.
+
+
+    Raises
+    ------
+    ClientError
+        If client not properly configured or token refresh fails.
+    """
+    get_client().refresh_token()
+
+
+def get_credentials_and_config() -> dict:
+    """
+    Get current client credentials and configuration.
+
+    Returns
+    -------
+    dict
+        Current client credentials and configuration details.
+    """
+    return get_client().get_credentials_and_config()

digitalhub/stores/{credentials → configurator}/api.py

@@ -4,23 +4,19 @@
 
 from __future__ import annotations
 
-from digitalhub.stores.credentials.handler import creds_handler
+from digitalhub.stores.configurator.configurator import configurator
 
 
-def set_current_profile(environment: str) -> None:
+def set_current_profile(profile: str) -> None:
     """
     Set the current credentials profile.
 
     Parameters
     ----------
-    environment : str
+    profile : str
         Name of the credentials profile to set.
-
-    Returns
-    -------
-    None
     """
-    creds_handler.set_current_profile(environment)
+    configurator.set_current_profile(profile)
 
 
 def get_current_profile() -> str:
@@ -32,4 +28,4 @@ def get_current_profile() -> str:
     str
         Name of the current credentials profile.
     """
-    return creds_handler.get_current_profile()
+    return configurator.get_current_profile()

digitalhub/stores/configurator/configurator.py

@@ -0,0 +1,123 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from digitalhub.stores.configurator.handler import ConfigurationHandler
+
+
+class Configurator:
+    """
+    Configurator class for configuration and credentials management.
+    """
+
+    def __init__(self):
+        self._handler = ConfigurationHandler()
+        self._reload_from_env = False
+
+    ##############################
+    # Configuration
+    ##############################
+
+    def get_configuration(self) -> dict:
+        """
+        Retrieve the current configuration.
+
+        Returns
+        -------
+        dict
+            Dictionary of configuration variables.
+        """
+        return self._handler.get_configuration()
+
+    ##############################
+    # Credentials
+    ##############################
+
+    def get_credentials(self) -> dict:
+        """
+        Retrieve the current credentials.
+
+        Returns
+        -------
+        dict
+            Dictionary of credentials.
+        """
+        return self._handler.get_credentials()
+
+    def eval_retry(self) -> bool:
+        """
+        Evaluate credentials reload based on retry logic.
+
+        Returns
+        -------
+        bool
+            True if a retry action was performed, otherwise False.
+        """
+        current_creds = self.get_credentials()
+        reread_creds = self._handler.load_credentials()
+
+        # Compare cached and file credentials.
+        # If different, reload in cache.
+        if current_creds != reread_creds:
+            self.reload_credentials()
+            return True
+
+        # Check if we need to reload from env only
+        if not self._reload_from_env:
+            self._handler.reload_credentials_from_env()
+            self._reload_from_env = True
+            return True
+
+        return False
+
+    def reload_credentials(self) -> None:
+        """
+        Reload credentials from environment and file.
+        """
+        self._handler.reload_credentials()
+
+    ###############################
+    # Profile methods
+    ###############################
+
+    def set_current_profile(self, profile: str) -> None:
+        """
+        Set the current profile.
+
+        Parameters
+        ----------
+        profile : str
+            Name of the profile to set.
+        """
+        self._handler.set_current_profile(profile)
+
+    ################################
+    # Other methods
+    ################################
+
+    def write_file(self, variables: dict) -> None:
+        """
+        Write the current configuration and credentials to file.
+
+        Parameters
+        ----------
+        variables : dict
+            Dictionary of variables to write.
+        """
+        self._handler.write_file(variables)
+
+    def get_config_creds(self) -> dict:
+        """
+        Get merged configuration and credentials.
+
+        Returns
+        -------
+        dict
+            Merged configuration and credentials dictionary.
+        """
+        return {**self.get_configuration(), **self.get_credentials()}
+
+
+configurator = Configurator()