digitalhub 0.11.0b7__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/stores/client/dhcore/client.py

@@ -1,7 +1,12 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
 from typing import Any
+from warnings import warn
 
 from requests import request
 from requests.exceptions import JSONDecodeError
@@ -12,30 +17,91 @@ from digitalhub.stores.client.dhcore.configurator import ClientDHCoreConfigurato
 from digitalhub.stores.client.dhcore.error_parser import ErrorParser
 from digitalhub.stores.client.dhcore.key_builder import ClientDHCoreKeyBuilder
 from digitalhub.stores.client.dhcore.params_builder import ClientDHCoreParametersBuilder
-from digitalhub.utils.exceptions import BackendError
+from digitalhub.utils.exceptions import BackendError, ClientError
 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.
-
-    The DHCore client is used to communicate with the Digitalhub Core
-    backendAPI via REST. The client supports basic authentication and
-    OAuth2 token authentication with token refresh.
-    At creation, the client tries to get the endpoint and authentication
-    parameters from the .dhcore file and the environment variables. In
-    case the user incours into an authentication/endpoint error during
-    the client creation, the user has the possibility to update the
-    correct parameters using the `set_dhcore_env` function. If the DHCore
-    client is already initialized, this function will override the
-    configuration, otherwise it simply set the environment variables.
+    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
     """
 
     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
@@ -52,7 +118,6 @@ class ClientDHCore(Client):
 
         # Client Configurator
         self._configurator = ClientDHCoreConfigurator()
-        self._configurator.configure(config)
 
     ##############################
     # CRUD methods
@@ -62,19 +127,31 @@ class ClientDHCore(Client):
         """
         Create an object in DHCore.
 
+        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.
+
         Parameters
         ----------
         api : str
-            Create API.
+            The API endpoint path for creating the object.
         obj : Any
-            Object to create.
+            The object to create. Will be serialized to JSON.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request,
+            such as headers, params, etc.
 
         Returns
         -------
         dict
-            Response object.
+            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.
         """
         if "headers" not in kwargs:
             kwargs["headers"] = {}
@@ -86,17 +163,27 @@ class ClientDHCore(Client):
         """
         Get an object from DHCore.
 
+        Sends a GET request to the DHCore backend to retrieve an existing object.
+
         Parameters
         ----------
         api : str
-            Read API.
+            The API endpoint path for reading the object.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request,
+            such as headers, params, etc.
 
         Returns
         -------
         dict
-            Response object.
+            The retrieved object as returned by the backend.
+
+        Raises
+        ------
+        BackendError
+            If the backend returns an error response.
+        EntityNotExistsError
+            If the requested object does not exist.
         """
         return self._prepare_call("GET", api, **kwargs)
 
@@ -104,19 +191,31 @@ class ClientDHCore(Client):
         """
         Update an object in DHCore.
 
+        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.
+
         Parameters
         ----------
         api : str
-            Update API.
-        obj : dict
-            Object to update.
+            The API endpoint path for updating the object.
+        obj : Any
+            The updated object data. Will be serialized to JSON.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request,
+            such as headers, params, etc.
 
         Returns
         -------
         dict
-            Response object.
+            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.
         """
         if "headers" not in kwargs:
             kwargs["headers"] = {}
@@ -128,17 +227,30 @@ class ClientDHCore(Client):
         """
         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.
+
         Parameters
         ----------
         api : str
-            Delete API.
+            The API endpoint path for deleting the object.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request,
+            such as headers, params, cascade options, etc.
 
         Returns
         -------
         dict
-            Response object.
+            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.
         """
         resp = self._prepare_call("DELETE", api, **kwargs)
         if isinstance(resp, bool):
@@ -149,21 +261,33 @@ class ClientDHCore(Client):
         """
         List objects from DHCore.
 
+        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.
+
         Parameters
         ----------
         api : str
-            List API.
+            The API endpoint path for listing objects.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request.
+            Can include 'params' dict with pagination parameters.
 
         Returns
         -------
         list[dict]
-            Response objects.
-        """
-        if kwargs is None:
-            kwargs = {}
+            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.
+        """
         if "params" not in kwargs:
             kwargs["params"] = {}
 
@@ -185,19 +309,27 @@ class ClientDHCore(Client):
 
     def list_first_object(self, api: str, **kwargs) -> dict:
         """
-        List first objects.
+        Get the first object from a list in DHCore.
+
+        Retrieves the first object from a paginated list by calling
+        list_objects and returning the first item.
 
         Parameters
         ----------
         api : str
-            The api to list the objects with.
+            The API endpoint path for listing objects.
         **kwargs : dict
-            Keyword arguments passed to the request.
+            Additional keyword arguments to pass to the HTTP request.
 
         Returns
         -------
         dict
-            The list of objects.
+            The first object from the list.
+
+        Raises
+        ------
+        BackendError
+            If no objects are found or if the backend returns an error.
         """
         try:
             return self.list_objects(api, **kwargs)[0]
@@ -208,21 +340,35 @@ class ClientDHCore(Client):
         """
         Search objects from DHCore.
 
+        Performs a search query against the DHCore backend using Solr search
+        capabilities. Handles pagination and removes search highlights from
+        the returned objects.
+
         Parameters
         ----------
         api : str
-            Search API.
+            The API endpoint path for searching objects (usually Solr search).
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request.
+            Can include search parameters, filters, pagination options, etc.
 
         Returns
         -------
         list[dict]
-            Response objects.
+            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.
         """
-        if kwargs is None:
-            kwargs = {}
-
         if "params" not in kwargs:
             kwargs["params"] = {}
 
@@ -262,73 +408,177 @@ class ClientDHCore(Client):
         """
         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 type of call to prepare.
+            The HTTP method type (GET, POST, PUT, DELETE, etc.).
         api : str
-            The api to call.
+            The API endpoint path to call.
         **kwargs : dict
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request.
 
         Returns
         -------
         dict
-            Response object.
+            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()
-        if kwargs is None:
-            kwargs = {}
-        url = self._configurator.build_url(api)
-        kwargs = self._configurator.set_request_auth(kwargs)
-        return self._make_call(call_type, url, **kwargs)
+        url = self._build_url(api)
+        full_kwargs = self._configurator.get_auth_parameters(kwargs)
+        return self._make_call(call_type, url, **full_kwargs)
 
-    def _make_call(self, call_type: str, url: str, refresh_token: bool = True, **kwargs) -> dict:
+    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 type of call to make.
+            The HTTP method type (GET, POST, PUT, DELETE, etc.).
         url : str
-            The URL to call.
+            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
-            Keyword arguments to pass to the request.
+            Additional keyword arguments to pass to the HTTP request.
 
         Returns
         -------
         dict
-            Response object.
+            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._configurator.check_core_version(response)
+        self._check_core_version(response)
 
-        # Handle token refresh
-        if response.status_code in [401] and refresh_token and self._configurator.oauth2_auth():
-            self._configurator.get_new_access_token()
-            kwargs = self._configurator.set_request_auth(kwargs)
-            return self._make_call(call_type, url, refresh_token=False, **kwargs)
+        # 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:
         """
-        Return dict from response.
+        Parse HTTP response to dictionary.
+
+        Converts the HTTP response body from JSON to a Python dictionary.
+        Handles empty responses gracefully.
 
         Parameters
         ----------
         response : Response
-            The response object.
+            The HTTP response object to parse.
 
         Returns
         -------
         dict
-            The parsed response object.
+            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()
@@ -344,11 +594,20 @@ class ClientDHCore(Client):
     @staticmethod
     def is_local() -> bool:
         """
-        Declare if Client is local.
+        Check if this client operates locally.
+
+        Returns a flag indicating whether this client instance operates
+        on local data or communicates with a remote backend.
 
         Returns
         -------
         bool
-            False
+            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.
         """
         return False