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

digitalhub/stores/client/dhcore/client.py

@@ -4,120 +4,39 @@
 
 from __future__ import annotations
 
-import typing
 from typing import Any
-from warnings import warn
-
-from requests import request
-from requests.exceptions import JSONDecodeError
 
 from digitalhub.stores.client._base.client import Client
 from digitalhub.stores.client.dhcore.api_builder import ClientDHCoreApiBuilder
-from digitalhub.stores.client.dhcore.configurator import ClientDHCoreConfigurator
-from digitalhub.stores.client.dhcore.error_parser import ErrorParser
+from digitalhub.stores.client.dhcore.header_manager import HeaderManager
+from digitalhub.stores.client.dhcore.http_handler import HttpRequestHandler
 from digitalhub.stores.client.dhcore.key_builder import ClientDHCoreKeyBuilder
 from digitalhub.stores.client.dhcore.params_builder import ClientDHCoreParametersBuilder
-from digitalhub.utils.exceptions import BackendError, ClientError
+from digitalhub.utils.exceptions import BackendError
 from digitalhub.utils.generic_utils import dump_json
 
-if typing.TYPE_CHECKING:
-    from requests import Response
-
-
-# API levels that are supported
-MAX_API_LEVEL = 20
-MIN_API_LEVEL = 13
-LIB_VERSION = 13
-
 
 class ClientDHCore(Client):
     """
     DHCore client for remote DigitalHub Core backend communication.
 
-    The DHCore client is used to communicate with the DigitalHub Core
-    backend API via REST. The client supports multiple authentication methods:
-    - Basic authentication (username/password)
-    - OAuth2 token authentication with automatic token refresh
-    - Personal access token exchange
-
-    At initialization, the client attempts to load endpoint and authentication
-    parameters from environment variables and the .dhcore configuration file.
-    If authentication or endpoint errors occur during client creation, users
-    can update the configuration using the `set_dhcore_env` function from
-    the utils module.
-
-    The client automatically handles:
-    - API version compatibility checking
-    - Pagination for list operations
-    - Token refresh on authentication errors
-    - Error parsing and exception mapping
-    - JSON serialization/deserialization
-
-    Parameters
-    ----------
-    config : dict, optional
-        DHCore environment configuration. If None, configuration will
-        be loaded from environment variables and configuration files.
-
-    Attributes
-    ----------
-    _api_builder : ClientDHCoreApiBuilder
-        Builds API endpoint URLs for different operations.
-    _key_builder : ClientDHCoreKeyBuilder
-        Builds storage keys for entities.
-    _params_builder : ClientDHCoreParametersBuilder
-        Builds request parameters for API calls.
-    _error_parser : ErrorParser
-        Parses backend responses and raises appropriate exceptions.
-    _configurator : ClientDHCoreConfigurator
-        Manages client configuration and authentication.
-
-    Notes
-    -----
-    Supported DHCore API versions: {MIN_API_LEVEL} to {MAX_API_LEVEL}
-    Current library API version: {LIB_VERSION}
-
-    Examples
-    --------
-    >>> from digitalhub.stores.client.api import get_client
-    >>> client = get_client(local=False)
-    >>> # Client is now ready for API operations
+    Provides REST API communication with DigitalHub Core backend supporting
+    multiple authentication methods: Basic (username/password), OAuth2 (token
+    with refresh), and Personal Access Token exchange. Automatically handles
+    API version compatibility, pagination, token refresh, error parsing, and
+    JSON serialization.
     """
 
     def __init__(self, config: dict | None = None) -> None:
-        """
-        Initialize DHCore client.
-
-        Creates a new DHCore client instance with all necessary components
-        for communicating with the DigitalHub Core backend. Sets up API
-        builders, configurators, and error handling.
-
-        Parameters
-        ----------
-        config : dict, optional
-            DHCore environment configuration. If None, configuration will
-            be loaded from environment variables and configuration files.
-
-        Returns
-        -------
-        None
-        """
         super().__init__()
 
-        # API builder
-        self._api_builder = ClientDHCoreApiBuilder()
-
-        # Key builder
-        self._key_builder = ClientDHCoreKeyBuilder()
-
-        # Parameters builder
-        self._params_builder = ClientDHCoreParametersBuilder()
+        # API, key and parameters builders
+        self._api_builder: ClientDHCoreApiBuilder = ClientDHCoreApiBuilder()
+        self._key_builder: ClientDHCoreKeyBuilder = ClientDHCoreKeyBuilder()
+        self._params_builder: ClientDHCoreParametersBuilder = ClientDHCoreParametersBuilder()
 
-        # Error parser
-        self._error_parser = ErrorParser()
-
-        # Client Configurator
-        self._configurator = ClientDHCoreConfigurator()
+        # HTTP request handling
+        self._http_handler = HttpRequestHandler()
 
     ##############################
     # CRUD methods
@@ -125,39 +44,27 @@ class ClientDHCore(Client):
 
     def create_object(self, api: str, obj: Any, **kwargs) -> dict:
         """
-        Create an object in DHCore.
+        Create an object in DHCore via POST request.
 
-        Sends a POST request to the DHCore backend to create a new object.
-        Automatically sets the appropriate Content-Type header and serializes
-        the object to JSON format.
+        Automatically sets Content-Type header and serializes object to JSON.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for creating the object.
+            API endpoint path for creating the object.
         obj : Any
-            The object to create. Will be serialized to JSON.
+            Object to create. Will be serialized to JSON.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request,
-            such as headers, params, etc.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The created object as returned by the backend.
-
-        Raises
-        ------
-        BackendError
-            If the backend returns an error response.
-        ClientError
-            If there are client-side configuration issues.
+            Created object as returned by the backend.
         """
-        if "headers" not in kwargs:
-            kwargs["headers"] = {}
-        kwargs["headers"]["Content-Type"] = "application/json"
+        kwargs = HeaderManager.set_json_content_type(**kwargs)
         kwargs["data"] = dump_json(obj)
-        return self._prepare_call("POST", api, **kwargs)
+        return self._http_handler.prepare_request("POST", api, **kwargs)
 
     def read_object(self, api: str, **kwargs) -> dict:
         """
@@ -168,15 +75,14 @@ class ClientDHCore(Client):
         Parameters
         ----------
         api : str
-            The API endpoint path for reading the object.
+            API endpoint path for reading the object.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request,
-            such as headers, params, etc.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The retrieved object as returned by the backend.
+            Retrieved object as returned by the backend.
 
         Raises
         ------
@@ -185,151 +91,108 @@ class ClientDHCore(Client):
         EntityNotExistsError
             If the requested object does not exist.
         """
-        return self._prepare_call("GET", api, **kwargs)
+        return self._http_handler.prepare_request("GET", api, **kwargs)
 
     def update_object(self, api: str, obj: Any, **kwargs) -> dict:
         """
-        Update an object in DHCore.
+        Update an object in DHCore via PUT request.
 
-        Sends a PUT request to the DHCore backend to update an existing object.
-        Automatically sets the appropriate Content-Type header and serializes
-        the object to JSON format.
+        Automatically sets Content-Type header and serializes object to JSON.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for updating the object.
+            API endpoint path for updating the object.
         obj : Any
-            The updated object data. Will be serialized to JSON.
+            Updated object data. Will be serialized to JSON.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request,
-            such as headers, params, etc.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The updated object as returned by the backend.
-
-        Raises
-        ------
-        BackendError
-            If the backend returns an error response.
-        EntityNotExistsError
-            If the object to update does not exist.
+            Updated object as returned by the backend.
         """
-        if "headers" not in kwargs:
-            kwargs["headers"] = {}
-        kwargs["headers"]["Content-Type"] = "application/json"
+        kwargs = HeaderManager.set_json_content_type(**kwargs)
         kwargs["data"] = dump_json(obj)
-        return self._prepare_call("PUT", api, **kwargs)
+        return self._http_handler.prepare_request("PUT", api, **kwargs)
 
     def delete_object(self, api: str, **kwargs) -> dict:
         """
         Delete an object from DHCore.
 
-        Sends a DELETE request to the DHCore backend to remove an object.
-        If the backend returns a boolean response, it will be wrapped in
-        a dictionary with a "deleted" key.
+        Sends DELETE request to remove an object. Wraps boolean responses
+        in {"deleted": True/False} dictionary.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for deleting the object.
+            API endpoint path for deleting the object.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request,
-            such as headers, params, cascade options, etc.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The deletion result. Either the backend response or
-            {"deleted": True/False} if backend returns a boolean.
-
-        Raises
-        ------
-        BackendError
-            If the backend returns an error response.
-        EntityNotExistsError
-            If the object to delete does not exist.
+            Deletion result from backend or {"deleted": bool} wrapper.
         """
-        resp = self._prepare_call("DELETE", api, **kwargs)
+        resp = self._http_handler.prepare_request("DELETE", api, **kwargs)
         if isinstance(resp, bool):
             resp = {"deleted": resp}
         return resp
 
     def list_objects(self, api: str, **kwargs) -> list[dict]:
         """
-        List objects from DHCore.
+        List objects from DHCore with automatic pagination.
 
-        Sends GET requests to the DHCore backend to retrieve a paginated list
-        of objects. Automatically handles pagination by making multiple requests
-        until all objects are retrieved.
+        Sends GET requests to retrieve paginated objects, automatically handling
+        pagination (starting from page 0) until all objects are retrieved.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for listing objects.
+            API endpoint path for listing objects.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
-            Can include 'params' dict with pagination parameters.
+            Additional HTTP request arguments. Can include 'params' dict
+            with pagination parameters.
 
         Returns
         -------
         list[dict]
-            A list containing all objects from all pages.
-
-        Raises
-        ------
-        BackendError
-            If the backend returns an error response.
-
-        Notes
-        -----
-        This method automatically handles pagination starting from page 0
-        and continues until all pages are retrieved.
+            List containing all objects from all pages.
         """
-        if "params" not in kwargs:
-            kwargs["params"] = {}
-
-        start_page = 0
-        if "page" not in kwargs["params"]:
-            kwargs["params"]["page"] = start_page
+        kwargs = self._params_builder.set_pagination(partial=True, **kwargs)
 
         objects = []
         while True:
-            resp = self._prepare_call("GET", api, **kwargs)
+            resp = self._http_handler.prepare_request("GET", api, **kwargs)
             contents = resp["content"]
             total_pages = resp["totalPages"]
-            if not contents or kwargs["params"]["page"] >= total_pages:
-                break
             objects.extend(contents)
-            kwargs["params"]["page"] += 1
+            if not contents or self._params_builder.read_page_number(**kwargs) >= (total_pages - 1):
+                break
+            self._params_builder.increment_page_number(**kwargs)
 
         return objects
 
     def list_first_object(self, api: str, **kwargs) -> dict:
         """
-        Get the first object from a list in DHCore.
+        Get the first object from a DHCore list.
 
-        Retrieves the first object from a paginated list by calling
-        list_objects and returning the first item.
+        Retrieves the first object by calling list_objects and returning
+        the first item.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for listing objects.
+            API endpoint path for listing objects.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The first object from the list.
-
-        Raises
-        ------
-        BackendError
-            If no objects are found or if the backend returns an error.
+            First object from the list.
         """
         try:
             return self.list_objects(api, **kwargs)[0]
@@ -338,60 +201,35 @@ class ClientDHCore(Client):
 
     def search_objects(self, api: str, **kwargs) -> list[dict]:
         """
-        Search objects from DHCore.
+        Search objects from DHCore using Solr capabilities.
 
-        Performs a search query against the DHCore backend using Solr search
-        capabilities. Handles pagination and removes search highlights from
-        the returned objects.
+        Performs search query with pagination and removes search highlights.
+        Sets default pagination (page=0, size=10) and sorting (metadata.updated DESC)
+        if not provided.
 
         Parameters
         ----------
         api : str
-            The API endpoint path for searching objects (usually Solr search).
+            API endpoint path for searching objects (usually Solr search).
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
-            Can include search parameters, filters, pagination options, etc.
+            Additional HTTP request arguments including search parameters,
+            filters, and pagination options.
 
         Returns
         -------
         list[dict]
-            A list of objects matching the search criteria, with search
-            highlights removed.
-
-        Raises
-        ------
-        BackendError
-            If the backend returns an error response.
-
-        Notes
-        -----
-        This method sets default values for pagination (page=0, size=10)
-        and sorting (by metadata.updated descending) if not provided.
-        Search highlights are automatically removed from results.
+            List of matching objects with search highlights removed.
         """
-        if "params" not in kwargs:
-            kwargs["params"] = {}
-
-        start_page = 0
-        if "page" not in kwargs["params"]:
-            kwargs["params"]["page"] = start_page
-
-        if "size" not in kwargs["params"]:
-            kwargs["params"]["size"] = 10
-
-        # Add sorting
-        if "sort" not in kwargs["params"]:
-            kwargs["params"]["sort"] = "metadata.updated,DESC"
-
+        kwargs = self._params_builder.set_pagination(**kwargs)
         objects_with_highlights: list[dict] = []
         while True:
-            resp = self._prepare_call("GET", api, **kwargs)
+            resp = self._http_handler.prepare_request("GET", api, **kwargs)
             contents = resp["content"]
             total_pages = resp["totalPages"]
-            if not contents or kwargs["params"]["page"] >= total_pages:
-                break
             objects_with_highlights.extend(contents)
-            kwargs["params"]["page"] += 1
+            if not contents or self._params_builder.read_page_number(**kwargs) >= (total_pages - 1):
+                break
+            self._params_builder.increment_page_number(**kwargs)
 
         objects = []
         for obj in objects_with_highlights:
@@ -400,193 +238,6 @@ class ClientDHCore(Client):
 
         return objects
 
-    ##############################
-    # Call methods
-    ##############################
-
-    def _prepare_call(self, call_type: str, api: str, **kwargs) -> dict:
-        """
-        Prepare a call to the DHCore API.
-
-        Handles the preparation of an API call by checking configuration,
-        building the URL, and adding authentication parameters.
-
-        Parameters
-        ----------
-        call_type : str
-            The HTTP method type (GET, POST, PUT, DELETE, etc.).
-        api : str
-            The API endpoint path to call.
-        **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
-
-        Returns
-        -------
-        dict
-            The response from the API call.
-
-        Raises
-        ------
-        ClientError
-            If the client configuration is invalid.
-        BackendError
-            If the backend returns an error response.
-        """
-        self._configurator.check_config()
-        url = self._build_url(api)
-        full_kwargs = self._configurator.get_auth_parameters(kwargs)
-        return self._make_call(call_type, url, **full_kwargs)
-
-    def _build_url(self, api: str) -> str:
-        """
-        Build the complete URL for an API call.
-
-        Combines the configured endpoint with the API path to create
-        the full URL for the HTTP request.
-
-        Parameters
-        ----------
-        api : str
-            The API endpoint path. Leading slashes are automatically handled.
-
-        Returns
-        -------
-        str
-            The complete URL for the API call.
-
-        Notes
-        -----
-        This method automatically removes leading slashes from the API path
-        to ensure proper URL construction.
-        """
-        endpoint = self._configurator.get_endpoint()
-        return f"{endpoint}/{api.removeprefix('/')}"
-
-    def _make_call(self, call_type: str, url: str, refresh: bool = True, **kwargs) -> dict:
-        """
-        Make a call to the DHCore API.
-
-        Executes the actual HTTP request to the DHCore backend, handles
-        API version checking, automatic token refresh on 401 errors,
-        and error parsing.
-
-        Parameters
-        ----------
-        call_type : str
-            The HTTP method type (GET, POST, PUT, DELETE, etc.).
-        url : str
-            The complete URL to call.
-        refresh : bool, default True
-            Whether to attempt token refresh on authentication errors.
-            Set to False to prevent infinite recursion during refresh.
-        **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
-
-        Returns
-        -------
-        dict
-            The parsed response from the backend as a dictionary.
-
-        Raises
-        ------
-        ClientError
-            If the backend API version is not supported.
-        BackendError
-            If the backend returns an error response or response parsing fails.
-        UnauthorizedError
-            If authentication fails and token refresh is not possible.
-
-        Notes
-        -----
-        This method automatically handles:
-        - API version compatibility checking
-        - OAuth2 token refresh on 401 errors
-        - Response parsing and error handling
-        - 60-second timeout for all requests
-        """
-        # Call the API
-        response = request(call_type, url, timeout=60, **kwargs)
-
-        # Evaluate DHCore API version
-        self._check_core_version(response)
-
-        # Handle token refresh (redo call)
-        if (response.status_code in [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._make_call(call_type, url, refresh=False, **kwargs)
-
-        self._error_parser.parse(response)
-        return self._dictify_response(response)
-
-    def _check_core_version(self, response: Response) -> None:
-        """
-        Check DHCore API version compatibility.
-
-        Validates that the DHCore backend API version is compatible with
-        this client library. Issues warnings if the backend version is
-        newer than the library version.
-
-        Parameters
-        ----------
-        response : Response
-            The HTTP response object containing the X-Api-Level header.
-
-        Returns
-        -------
-        None
-
-        Raises
-        ------
-        ClientError
-            If the backend API level is not supported by this client.
-
-        Notes
-        -----
-        Supported API levels: {MIN_API_LEVEL} to {MAX_API_LEVEL}
-        Current library version: {LIB_VERSION}
-        """
-        if "X-Api-Level" in response.headers:
-            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.")
-
-    def _dictify_response(self, response: Response) -> dict:
-        """
-        Parse HTTP response to dictionary.
-
-        Converts the HTTP response body from JSON to a Python dictionary.
-        Handles empty responses gracefully.
-
-        Parameters
-        ----------
-        response : Response
-            The HTTP response object to parse.
-
-        Returns
-        -------
-        dict
-            The parsed response body as a dictionary. Returns empty dict
-            if response body is empty.
-
-        Raises
-        ------
-        BackendError
-            If the response cannot be parsed as JSON.
-
-        Notes
-        -----
-        Empty response bodies are treated as valid and return an empty dict.
-        """
-        try:
-            return response.json()
-        except JSONDecodeError:
-            if response.text == "":
-                return {}
-            raise BackendError("Backend response could not be parsed.")
-
     ##############################
     # Interface methods
     ##############################
@@ -596,18 +247,23 @@ class ClientDHCore(Client):
         """
         Check if this client operates locally.
 
-        Returns a flag indicating whether this client instance operates
-        on local data or communicates with a remote backend.
+        Used to distinguish between ClientDHCore (remote) and ClientLocal
+        implementations.
 
         Returns
         -------
         bool
-            False, indicating this client communicates with a remote
-            DHCore backend, not local storage.
-
-        Notes
-        -----
-        This method is used to distinguish between ClientDHCore (returns False)
-        and ClientLocal (returns True) implementations.
+            False, indicating this client communicates with remote DHCore backend.
         """
         return False
+
+    ##############################
+    # Utility methods
+    ##############################
+
+    def refresh_token(self) -> None:
+        """
+        Manually trigger OAuth2 token refresh.
+        """
+        self._http_handler._configurator.check_config()
+        self._http_handler._configurator.refresh_credentials()