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

digitalhub/stores/client/dhcore/enums.py

@@ -7,22 +7,6 @@ from __future__ import annotations
 from enum import Enum
 
 
-class DhcoreEnvVar(Enum):
-    """
-    Environment variables.
-    """
-
-    ENDPOINT = "DHCORE_ENDPOINT"
-    ISSUER = "DHCORE_ISSUER"
-    USER = "DHCORE_USER"
-    PASSWORD = "DHCORE_PASSWORD"
-    CLIENT_ID = "DHCORE_CLIENT_ID"
-    ACCESS_TOKEN = "DHCORE_ACCESS_TOKEN"
-    REFRESH_TOKEN = "DHCORE_REFRESH_TOKEN"
-    PERSONAL_ACCESS_TOKEN = "DHCORE_PERSONAL_ACCESS_TOKEN"
-    WORKFLOW_IMAGE = "DHCORE_WORKFLOW_IMAGE"
-
-
 class AuthType(Enum):
     """
     Authentication types.

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

digitalhub/stores/client/dhcore/header_manager.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+
+class HeaderManager:
+    """
+    Manages HTTP headers for DHCore client requests.
+
+    Provides utilities for setting and managing common HTTP headers
+    like Content-Type for JSON requests.
+    """
+
+    @staticmethod
+    def ensure_headers(**kwargs) -> dict:
+        """
+        Initialize headers dictionary in kwargs.
+
+        Ensures parameter dictionary has 'headers' key for HTTP headers,
+        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
+            Dictionary with guaranteed 'headers' key containing
+            empty dict if not already present.
+        """
+        if "headers" not in kwargs:
+            kwargs["headers"] = {}
+        return kwargs
+
+    @staticmethod
+    def set_json_content_type(**kwargs) -> dict:
+        """
+        Set Content-Type header to application/json.
+
+        Ensures that the 'Content-Type' header is set to 'application/json'
+        for requests that require JSON payloads.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Dictionary with 'Content-Type' header set to 'application/json'.
+        """
+        kwargs = HeaderManager.ensure_headers(**kwargs)
+        kwargs["headers"]["Content-Type"] = "application/json"
+        return kwargs

digitalhub/stores/client/dhcore/http_handler.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from requests import request
+
+from digitalhub.stores.client.dhcore.configurator import ClientDHCoreConfigurator
+from digitalhub.stores.client.dhcore.response_processor import ResponseProcessor
+from digitalhub.utils.exceptions import BackendError
+
+# Default timeout for requests (in seconds)
+DEFAULT_TIMEOUT = 60
+
+
+class HttpRequestHandler:
+    """
+    Handles HTTP request execution for DHCore client.
+
+    Encapsulates all HTTP communication logic including request execution,
+    automatic token refresh on authentication failures, and response processing.
+    Works in coordination with configurator for authentication and response
+    processor for parsing.
+    """
+
+    def __init__(self) -> None:
+        self._configurator = ClientDHCoreConfigurator()
+        self._response_processor = ResponseProcessor()
+
+    def prepare_request(self, method: str, api: str, **kwargs) -> dict:
+        """
+        Execute API call with full URL construction and authentication.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method type (GET, POST, PUT, DELETE, etc.).
+        api : str
+            API endpoint path to call.
+        **kwargs : dict
+            Additional HTTP request arguments.
+
+        Returns
+        -------
+        dict
+            Response from the API call.
+        """
+        full_kwargs = self._set_auth(**kwargs)
+        url = self._build_url(api)
+        return self._execute_request(method, url, **full_kwargs)
+
+    def _execute_request(
+        self,
+        method: str,
+        url: str,
+        refresh: bool = True,
+        **kwargs,
+    ) -> dict:
+        """
+        Execute HTTP request with automatic handling.
+
+        Sends HTTP request with authentication, handles token refresh on 401 errors,
+        validates API version compatibility, and parses response. Uses 60-second
+        timeout by default.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method (GET, POST, PUT, DELETE, etc.).
+        url : str
+            Complete URL to request.
+        refresh : bool, default True
+            Whether to attempt token refresh on authentication errors.
+            Set to False during refresh to prevent infinite recursion.
+        **kwargs : dict
+            Additional HTTP request arguments (headers, params, data, etc.).
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary.
+        """
+        # Execute HTTP request
+        response = request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
+
+        # Process response (version check, error parsing, dictify)
+        try:
+            return self._response_processor.process(response)
+        except BackendError as e:
+            # Handle authentication errors with token refresh
+            if response.status_code == 401 and refresh and self._configurator.refreshable_auth_types():
+                self._configurator.refresh_credentials(change_origin=True)
+                kwargs = self._configurator.get_auth_parameters(kwargs)
+                return self._execute_request(method, url, refresh=False, **kwargs)
+            raise e
+
+    def _set_auth(self, **kwargs) -> dict:
+        """
+        Prepare kwargs with authentication parameters.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Request parameters to augment with authentication.
+
+        Returns
+        -------
+        dict
+            kwargs enhanced with authentication parameters.
+        """
+        self._configurator.check_config()
+        return self._configurator.get_auth_parameters(kwargs)
+
+    def _build_url(self, api: str) -> str:
+        """
+        Build complete URL for API call.
+
+        Combines configured endpoint with API path, automatically removing
+        leading slashes for proper URL construction.
+
+        Parameters
+        ----------
+        api : str
+            API endpoint path. Leading slashes are automatically handled.
+
+        Returns
+        -------
+        str
+            Complete URL for the API call.
+        """
+        endpoint = self._configurator.get_endpoint()
+        return f"{endpoint}/{api.removeprefix('/')}"

digitalhub/stores/client/dhcore/params_builder.py

@@ -4,26 +4,24 @@
 
 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
 
+DEFAULT_START_PAGE = 0
+DEFAULT_SIZE = 25
+DEFAULT_SORT = "metadata.updated,DESC"
+
 
 class ClientDHCoreParametersBuilder(ClientParametersBuilder):
     """
     Parameter builder for DHCore client API calls.
 
-    This class constructs HTTP request parameters for different DHCore API
-    operations, handling the specific parameter formats and query structures
-    required by the DigitalHub Core backend. It supports both base-level
-    operations (like project management) and context-level operations
-    (entity operations within projects).
-
-    The builder handles various parameter transformations including:
-    - Query parameter formatting for different operations
-    - Search filter construction for Solr-based searches
-    - Cascade deletion options
-    - Versioning parameters
-    - Entity sharing parameters
+    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.
 
     Methods
     -------
@@ -39,36 +37,22 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         """
         Build HTTP request parameters for DHCore API calls.
 
-        Routes parameter building to the appropriate method based on the
-        API category (base or context operations) and applies operation-specific
-        parameter transformations.
-
         Parameters
         ----------
         category : str
-            The API category, either 'base' for project-level operations
-            or 'context' for entity operations within projects.
+            API category: 'base' for project-level operations or 'context'
+            for entity operations within projects.
         operation : str
-            The specific API operation being performed (create, read, update,
-            delete, list, search, etc.).
+            Specific API operation (create, read, update, delete, list, search, etc.).
         **kwargs : dict
-            Raw parameters to be transformed into proper HTTP request format.
-            May include entity identifiers, filter criteria, pagination
-            options, etc.
+            Raw parameters to transform including entity identifiers, filter
+            criteria, pagination options, etc.
 
         Returns
         -------
         dict
-            Formatted parameters dictionary ready for HTTP request, typically
-            containing a 'params' key with query parameters and other
-            request-specific parameters.
-
-        Notes
-        -----
-        This method acts as a dispatcher, routing to either base or context
-        parameter building based on the category. All parameter dictionaries
-        are initialized with a 'params' key for query parameters if not
-        already present.
+            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)
@@ -76,128 +60,105 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
 
     def build_parameters_base(self, operation: str, **kwargs) -> dict:
         """
-        Build parameters for base-level API operations.
-
-        Constructs HTTP request parameters for operations that work at the
-        base level of the API, typically project-level operations and
-        entity sharing functionality.
+        Constructs HTTP request parameters for project operations.
 
         Parameters
         ----------
         operation : str
-            The API operation being performed. Supported operations:
-            - DELETE: Project deletion with optional cascade
-            - SHARE: Entity sharing/unsharing with users
+            API operation.
         **kwargs : dict
-            Operation-specific parameters including:
-            - cascade (bool): For DELETE, whether to cascade delete
-            - user (str): For SHARE, target user for sharing
-            - unshare (bool): For SHARE, whether to unshare instead
-            - id (str): For SHARE unshare, entity ID to unshare
-
+            Operation-specific parameters.
         Returns
         -------
         dict
-            Formatted parameters with 'params' containing query parameters
-            and other request-specific parameters.
-
-        Notes
-        -----
-        Parameter transformations:
-        - CASCADE: Boolean values are converted to lowercase strings
-        - SHARE: User parameter is moved to query params
-        - UNSHARE: Requires both unshare=True and entity id
+            Formatted parameters with 'params' containing query parameters.
         """
-        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)
+
+        # Handle share
         elif operation == BackendOperations.SHARE.value:
-            kwargs["params"]["user"] = kwargs.pop("user")
+            kwargs = self._add_param("user", kwargs.pop("user"), **kwargs)
             if kwargs.pop("unshare", False):
-                kwargs["params"]["id"] = kwargs.pop("id")
+                kwargs = self._add_param("id", kwargs.pop("id"), **kwargs)
 
         return kwargs
 
     def build_parameters_context(self, operation: str, **kwargs) -> dict:
         """
-        Build parameters for context-level API operations.
-
-        Constructs HTTP request parameters for operations that work within
-        a specific context (project), including entity management and
-        search functionality.
+        Constructs HTTP request parameters for entity management and search within
+        projects.
 
         Parameters
         ----------
         operation : str
-            The API operation being performed. Supported operations:
-            - SEARCH: Search entities with filtering and pagination
-            - READ_MANY: Retrieve multiple entities with pagination
-            - DELETE: Delete specific entity by ID
-            - READ: Read specific entity by ID (with optional embedded)
+            API operation.
         **kwargs : dict
-            Operation-specific parameters including:
-            - params (dict): Search filters and conditions
-            - page (int): Page number for pagination (default: 0)
-            - size (int): Number of items per page (default: 20)
-            - order_by (str): Field to order results by
-            - order (str): Order direction ('asc' or 'desc')
-            - embedded (bool): For READ, whether to include embedded entities
-            - id (str): For READ/DELETE, entity identifier
+            Operation-specific parameters.
 
         Returns
         -------
         dict
-            Formatted parameters with 'params' containing query parameters
-            and other request-specific parameters like 'id' for entity operations.
-
-        Notes
-        -----
-        Search and pagination:
-        - Filters are applied via 'filter' parameter in query string
-        - Pagination uses 'page' and 'size' parameters
-        - Results can be ordered using 'sort' parameter format
-
-        Entity operations:
-        - READ: Supports embedded entity inclusion via 'embedded' param
-        - DELETE: Requires entity 'id' parameter
+            Formatted parameters with 'params'.
         """
-        kwargs = self._set_params(**kwargs)
+        kwargs = self._ensure_params(**kwargs)
 
         # Handle read
         if operation == BackendOperations.READ.value:
-            name = kwargs.pop("entity_name", None)
-            if name is not None:
-                kwargs["params"]["name"] = name
+            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["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 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:
-            # 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
+                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["params"]["fq"] = fq
+                kwargs = self._add_param("fq", fq, **kwargs)
 
             # Add search query
             if (query := kwargs.pop("query", None)) is not None:
-                kwargs["params"]["q"] = query
+                kwargs = self._add_param("q", query, **kwargs)
 
             # Add search filters
             fq = []
@@ -240,39 +201,91 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
                 fq.append(f"metadata.labels:({labels})")
 
             # Add filters
-            kwargs["params"]["fq"] = fq
+            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 _set_params(**kwargs) -> dict:
+    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.
         """
-        Initialize parameter dictionary with query parameters structure.
+        return kwargs["params"]["page"]
 
-        Ensures that the parameter dictionary has a 'params' key for
-        HTTP query parameters. This is a utility method used by all
-        parameter building methods to guarantee consistent structure.
+    @staticmethod
+    def increment_page_number(**kwargs) -> dict:
+        """
+        Increment page number in kwargs.
 
         Parameters
         ----------
         **kwargs : dict
-            Keyword arguments to be formatted. May be empty or contain
-            various parameters for API operations.
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
 
         Returns
         -------
         dict
-            Parameters dictionary with guaranteed 'params' key containing
-            an empty dict if not already present.
-
-        Notes
-        -----
-        This method is called at the beginning of all parameter building
-        methods to ensure consistent dictionary structure for query
-        parameter handling.
+            Parameters dictionary with incremented 'page' number in 'params'.
         """
-        if not kwargs:
-            kwargs = {}
-        if "params" not in kwargs:
-            kwargs["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}