digitalhub 0.13.0b4__py3-none-any.whl → 0.14.0b1__py3-none-any.whl

digitalhub/stores/client/dhcore/client.py

@@ -26,38 +26,25 @@ if typing.TYPE_CHECKING:
 
 # API levels that are supported
 MAX_API_LEVEL = 20
-MIN_API_LEVEL = 13
-LIB_VERSION = 13
+MIN_API_LEVEL = 14
+LIB_VERSION = 14
 
 
 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
+    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. Supports API versions {MIN_API_LEVEL} to {MAX_API_LEVEL}.
 
     Parameters
     ----------
     config : dict, optional
-        DHCore environment configuration. If None, configuration will
-        be loaded from environment variables and configuration files.
+        DHCore environment configuration. If None, loads from environment
+        variables and configuration files.
 
     Attributes
     ----------
@@ -72,11 +59,6 @@ class ClientDHCore(Client):
     _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
@@ -86,17 +68,13 @@ class ClientDHCore(Client):
 
     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.
+        Initialize DHCore client with API builders and configurators.
 
         Parameters
         ----------
         config : dict, optional
-            DHCore environment configuration. If None, configuration will
-            be loaded from environment variables and configuration files.
+            DHCore environment configuration. If None, loads from environment
+            variables and configuration files.
 
         Returns
         -------
@@ -125,26 +103,23 @@ 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.
+            Created object as returned by the backend.
 
         Raises
         ------
@@ -168,15 +143,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
         ------
@@ -189,26 +163,23 @@ class ClientDHCore(Client):
 
     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.
+            Updated object as returned by the backend.
 
         Raises
         ------
@@ -227,23 +198,20 @@ 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.
+        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.
+            Deletion result from backend or {"deleted": bool} wrapper.
 
         Raises
         ------
@@ -259,34 +227,28 @@ class ClientDHCore(Client):
 
     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.
+            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"] = {}
@@ -309,27 +271,27 @@ class ClientDHCore(Client):
 
     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.
+            First object from the list.
 
         Raises
         ------
         BackendError
-            If no objects are found or if the backend returns an error.
+            If no objects found or backend returns an error.
         """
         try:
             return self.list_objects(api, **kwargs)[0]
@@ -338,36 +300,29 @@ 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.
+            List of matching objects 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 "params" not in kwargs:
             kwargs["params"] = {}
@@ -406,31 +361,30 @@ class ClientDHCore(Client):
 
     def _prepare_call(self, call_type: str, api: str, **kwargs) -> dict:
         """
-        Prepare a call to the DHCore API.
+        Prepare DHCore API call with configuration and authentication.
 
-        Handles the preparation of an API call by checking configuration,
-        building the URL, and adding authentication parameters.
+        Checks configuration, builds URL, and adds authentication parameters.
 
         Parameters
         ----------
         call_type : str
-            The HTTP method type (GET, POST, PUT, DELETE, etc.).
+            HTTP method type (GET, POST, PUT, DELETE, etc.).
         api : str
-            The API endpoint path to call.
+            API endpoint path to call.
         **kwargs : dict
-            Additional keyword arguments to pass to the HTTP request.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The response from the API call.
+            Response from the API call.
 
         Raises
         ------
         ClientError
-            If the client configuration is invalid.
+            If client configuration is invalid.
         BackendError
-            If the backend returns an error response.
+            If backend returns an error response.
         """
         self._configurator.check_config()
         url = self._build_url(api)
@@ -442,7 +396,8 @@ class ClientDHCore(Client):
         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.
+        the full URL for the HTTP request. Automatically removes leading
+        slashes from the API path to ensure proper URL construction.
 
         Parameters
         ----------
@@ -453,56 +408,60 @@ class ClientDHCore(Client):
         -------
         str
             The complete URL for the API call.
+        """
+
+    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.
 
-        Notes
-        -----
-        This method automatically removes leading slashes from the API path
-        to ensure 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('/')}"
 
     def _make_call(self, call_type: str, url: str, refresh: bool = True, **kwargs) -> dict:
         """
-        Make a call to the DHCore API.
+        Execute HTTP request to DHCore API with automatic handling.
 
-        Executes the actual HTTP request to the DHCore backend, handles
-        API version checking, automatic token refresh on 401 errors,
-        and error parsing.
+        Handles API version checking, token refresh on 401 errors, response parsing,
+        and error handling with 60-second timeout.
 
         Parameters
         ----------
         call_type : str
-            The HTTP method type (GET, POST, PUT, DELETE, etc.).
+            HTTP method type (GET, POST, PUT, DELETE, etc.).
         url : str
-            The complete URL to call.
+            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.
+            Additional HTTP request arguments.
 
         Returns
         -------
         dict
-            The parsed response from the backend as a dictionary.
+            Parsed response from backend as dictionary.
 
         Raises
         ------
         ClientError
-            If the backend API version is not supported.
+            If backend API version is not supported.
         BackendError
-            If the backend returns an error response or response parsing fails.
+            If backend returns 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
+            If authentication fails and token refresh not possible.
         """
         # Call the API
         response = request(call_type, url, timeout=60, **kwargs)
@@ -521,16 +480,15 @@ class ClientDHCore(Client):
 
     def _check_core_version(self, response: Response) -> None:
         """
-        Check DHCore API version compatibility.
+        Validate 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.
+        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
-            The HTTP response object containing the X-Api-Level header.
+            HTTP response containing X-Api-Level header.
 
         Returns
         -------
@@ -539,12 +497,7 @@ class ClientDHCore(Client):
         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 backend API level is not supported by this client.
         """
         if "X-Api-Level" in response.headers:
             core_api_level = int(response.headers["X-Api-Level"])
@@ -555,30 +508,25 @@ class ClientDHCore(Client):
 
     def _dictify_response(self, response: Response) -> dict:
         """
-        Parse HTTP response to dictionary.
+        Parse HTTP response body to dictionary.
 
-        Converts the HTTP response body from JSON to a Python dictionary.
-        Handles empty responses gracefully.
+        Converts JSON response to Python dictionary, treating empty responses
+        as valid and returning empty dict.
 
         Parameters
         ----------
         response : Response
-            The HTTP response object to parse.
+            HTTP response object to parse.
 
         Returns
         -------
         dict
-            The parsed response body as a dictionary. Returns empty dict
-            if response body is empty.
+            Parsed response body as dictionary, or empty dict if 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.
+            If response cannot be parsed as JSON.
         """
         try:
             return response.json()
@@ -596,18 +544,12 @@ 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