digitalhub 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/stores/client/dhcore/enums.py

@@ -19,6 +19,7 @@ class DhcoreEnvVar(Enum):
     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"
 
 
@@ -29,3 +30,5 @@ class AuthType(Enum):
 
     BASIC = "basic"
     OAUTH2 = "oauth2"
+    EXCHANGE = "exchange"
+    ACCESS_TOKEN = "access_token_only"

digitalhub/stores/client/dhcore/error_parser.py

@@ -23,19 +23,53 @@ if typing.TYPE_CHECKING:
 
 
 class ErrorParser:
+    """
+    Parser for DHCore API errors.
+
+    This class handles the parsing and translation of HTTP responses
+    from the DHCore backend into appropriate Python exceptions.
+    """
+
     @staticmethod
     def parse(response: Response) -> None:
         """
         Handle DHCore API errors.
 
+        Parses the HTTP response and raises appropriate exceptions based on
+        the status code and response content. Maps backend errors to specific
+        exception types for better error handling in the client code.
+
         Parameters
         ----------
         response : Response
-            The response object.
+            The HTTP response object from requests.
 
         Returns
         -------
         None
+
+        Raises
+        ------
+        TimeoutError
+            If the request timed out.
+        ConnectionError
+            If unable to connect to the backend.
+        MissingSpecError
+            If the backend reports a missing spec (400 status).
+        EntityAlreadyExistsError
+            If the entity already exists (400 status with specific message).
+        BadRequestError
+            For other 400 status codes.
+        UnauthorizedError
+            For 401 status codes.
+        ForbiddenError
+            For 403 status codes.
+        EntityNotExistsError
+            For 404 status codes with specific message.
+        BackendError
+            For other 404 status codes and general backend errors.
+        RuntimeError
+            For unexpected exceptions.
         """
         try:
             response.raise_for_status()

digitalhub/stores/client/dhcore/params_builder.py

@@ -10,26 +10,65 @@ from digitalhub.stores.client._base.params_builder import ClientParametersBuilde
 
 class ClientDHCoreParametersBuilder(ClientParametersBuilder):
     """
-    This class is used to build the parameters for the DHCore client calls.
+    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
+
+    Methods
+    -------
+    build_parameters(category, operation, **kwargs)
+        Main entry point for parameter building based on API category.
+    build_parameters_base(operation, **kwargs)
+        Builds parameters for base-level API operations.
+    build_parameters_context(operation, **kwargs)
+        Builds parameters for context-level API operations.
     """
 
     def build_parameters(self, category: str, operation: str, **kwargs) -> dict:
         """
-        Build the parameters for the client call.
+        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
-            API category.
+            The API category, either 'base' for project-level operations
+            or 'context' for entity operations within projects.
         operation : str
-            API operation.
+            The specific API operation being performed (create, read, update,
+            delete, list, search, etc.).
         **kwargs : dict
-            Parameters to build.
+            Raw parameters to be transformed into proper HTTP request format.
+            May include entity identifiers, filter criteria, pagination
+            options, etc.
 
         Returns
         -------
         dict
-            Parameters formatted.
+            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.
         """
         if category == ApiCategories.BASE.value:
             return self.build_parameters_base(operation, **kwargs)
@@ -37,19 +76,37 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
 
     def build_parameters_base(self, operation: str, **kwargs) -> dict:
         """
-        Build the base parameters for the client call.
+        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.
 
         Parameters
         ----------
         operation : str
-            API operation.
+            The API operation being performed. Supported operations:
+            - DELETE: Project deletion with optional cascade
+            - SHARE: Entity sharing/unsharing with users
         **kwargs : dict
-            Parameters to build.
+            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
 
         Returns
         -------
         dict
-            Parameters formatted.
+            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
         """
         kwargs = self._set_params(**kwargs)
         if operation == BackendOperations.DELETE.value:
@@ -64,19 +121,46 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
 
     def build_parameters_context(self, operation: str, **kwargs) -> dict:
         """
-        Build the context parameters for the client call.
+        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.
 
         Parameters
         ----------
         operation : str
-            API operation.
+            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)
         **kwargs : dict
-            Parameters to build.
+            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
 
         Returns
         -------
         dict
-            Parameters formatted.
+            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
         """
         kwargs = self._set_params(**kwargs)
 
@@ -163,17 +247,29 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
     @staticmethod
     def _set_params(**kwargs) -> dict:
         """
-        Format params parameter.
+        Initialize parameter dictionary with query parameters structure.
+
+        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.
 
         Parameters
         ----------
         **kwargs : dict
-            Keyword arguments.
+            Keyword arguments to be formatted. May be empty or contain
+            various parameters for API operations.
 
         Returns
         -------
         dict
-            Parameters with initialized params.
+            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.
         """
         if not kwargs:
             kwargs = {}

digitalhub/stores/client/dhcore/utils.py

@@ -8,7 +8,7 @@ import os
 import typing
 
 from digitalhub.stores.client.api import get_client
-from digitalhub.stores.client.dhcore.enums import DhcoreEnvVar
+from digitalhub.stores.credentials.enums import CredsEnvVar
 
 if typing.TYPE_CHECKING:
     from digitalhub.stores.client.dhcore.client import ClientDHCore
@@ -24,53 +24,71 @@ def set_dhcore_env(
 ) -> None:
     """
     Function to set environment variables for DHCore config.
+
+    Sets the environment variables for DHCore configuration and
+    reloads the client configurator to use the new settings.
     Note that if the environment variable is already set, it
     will be overwritten.
 
     Parameters
     ----------
-    endpoint : str
-        The endpoint of DHCore.
-    user : str
-        The user of DHCore.
-    password : str
-        The password of DHCore.
-    access_token : str
-        The access token of DHCore.
-    refresh_token : str
-        The refresh token of DHCore.
-    client_id : str
-        The client id of DHCore.
+    endpoint : str, optional
+        The endpoint URL of the DHCore backend.
+    user : str, optional
+        The username for basic authentication.
+    password : str, optional
+        The password for basic authentication.
+    access_token : str, optional
+        The OAuth2 access token.
+    refresh_token : str, optional
+        The OAuth2 refresh token.
+    client_id : str, optional
+        The OAuth2 client identifier.
 
     Returns
     -------
     None
+
+    Notes
+    -----
+    After setting the environment variables, this function automatically
+    reloads the client configurator to apply the new configuration.
     """
     if endpoint is not None:
-        os.environ[DhcoreEnvVar.ENDPOINT.value] = endpoint
+        os.environ[CredsEnvVar.DHCORE_ENDPOINT.value] = endpoint
     if user is not None:
-        os.environ[DhcoreEnvVar.USER.value] = user
+        os.environ[CredsEnvVar.DHCORE_USER.value] = user
     if password is not None:
-        os.environ[DhcoreEnvVar.PASSWORD.value] = password
+        os.environ[CredsEnvVar.DHCORE_PASSWORD.value] = password
     if access_token is not None:
-        os.environ[DhcoreEnvVar.ACCESS_TOKEN.value] = access_token
+        os.environ[CredsEnvVar.DHCORE_ACCESS_TOKEN.value] = access_token
     if refresh_token is not None:
-        os.environ[DhcoreEnvVar.REFRESH_TOKEN.value] = refresh_token
+        os.environ[CredsEnvVar.DHCORE_REFRESH_TOKEN.value] = refresh_token
     if client_id is not None:
-        os.environ[DhcoreEnvVar.CLIENT_ID.value] = client_id
+        os.environ[CredsEnvVar.DHCORE_CLIENT_ID.value] = client_id
 
     client: ClientDHCore = get_client(local=False)
-    client._configurator.configure()
+    client._configurator.load_env_vars()
 
 
 def refresh_token() -> None:
     """
-    Function to refresh token.
+    Function to refresh the OAuth2 access token.
+
+    Attempts to refresh the current OAuth2 access token using the
+    refresh token stored in the client configuration. This function
+    requires that the client be configured with OAuth2 authentication.
 
     Returns
     -------
     None
+
+    Raises
+    ------
+    ClientError
+        If the client is not properly configured or if the token
+        refresh fails.
     """
     client: ClientDHCore = get_client(local=False)
     client._configurator.check_config()
-    client._configurator.get_new_access_token()
+    client._configurator.refresh_credentials()

digitalhub/stores/client/local/api_builder.py

@@ -73,6 +73,23 @@ class ClientLocalApiBuilder(ClientApiBuilder):
     def build_api_context(self, operation: str, **kwargs) -> str:
         """
         Build the context API for the client.
+
+        Parameters
+        ----------
+        operation : str
+            The API operation.
+        **kwargs : dict
+            Additional parameters including project, entity_type, entity_id, etc.
+
+        Returns
+        -------
+        str
+            The formatted context API endpoint.
+
+        Raises
+        ------
+        BackendError
+            If the operation is not supported for the entity type.
         """
         try:
             entity_type = kwargs["entity_type"] + "s"

digitalhub/stores/client/local/client.py

@@ -537,18 +537,16 @@ class ClientLocal(Client):
         Parameters
         ----------
         error_code : int
-            Error code.
-        project : str
-            Project name.
-        entity_type : str
-            Entity type.
-        entity_id : str
-            Entity ID.
+            Error code identifying the type of error.
+        entity_type : str, optional
+            Entity type that caused the error.
+        entity_id : str, optional
+            Entity ID that caused the error.
 
         Returns
         -------
         str
-            The formatted message.
+            The formatted error message.
         """
         msg = {
             1: f"Object '{entity_type}' to create is not valid",

digitalhub/stores/credentials/api.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.credentials.handler import creds_handler
+
+
+def set_current_profile(environment: str) -> None:
+    """
+    Set the current credentials profile.
+
+    Parameters
+    ----------
+    environment : str
+        Name of the credentials profile to set.
+
+    Returns
+    -------
+    None
+    """
+    creds_handler.set_current_profile(environment)
+
+
+def get_current_profile() -> str:
+    """
+    Get the name of the current credentials profile.
+
+    Returns
+    -------
+    str
+        Name of the current credentials profile.
+    """
+    return creds_handler.get_current_profile()

digitalhub/stores/credentials/configurator.py

@@ -0,0 +1,210 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from abc import abstractmethod
+
+from digitalhub.stores.credentials.enums import CredsOrigin
+from digitalhub.stores.credentials.handler import creds_handler
+from digitalhub.utils.exceptions import ConfigError
+
+
+class Configurator:
+    """
+    Base configurator for credentials management.
+
+    Attributes
+    ----------
+    keys : list of str
+        List of credential keys to manage.
+    required_keys : list of str
+        List of required credential keys.
+    _env : str
+        Environment origin identifier.
+    _file : str
+        File origin identifier.
+    _creds_handler : object
+        Credentials handler instance.
+    """
+
+    # Must be set in implementing class
+    keys: list[str] = []
+    required_keys: list[str] = []
+
+    # Origin of the credentials
+    _env = CredsOrigin.ENV.value
+    _file = CredsOrigin.FILE.value
+
+    # Credentials handler
+    _creds_handler = creds_handler
+
+    def __init__(self):
+        self._current_profile = self._creds_handler.get_current_profile()
+        self.load_configs()
+        self._changed_origin = False
+        self._origin = self.set_origin()
+
+    ##############################
+    # Configuration
+    ##############################
+
+    def load_configs(self) -> None:
+        """
+        Load the configuration from both environment and file sources.
+
+        Returns
+        -------
+        None
+        """
+        self.load_env_vars()
+        self.load_file_vars()
+
+    @abstractmethod
+    def load_env_vars(self) -> None:
+        ...
+
+    @abstractmethod
+    def load_file_vars(self) -> None:
+        ...
+
+    def check_config(self) -> None:
+        """
+        Check if the current profile has changed and reload
+        the file credentials if needed.
+
+        Returns
+        -------
+        None
+        """
+        if (current := self._creds_handler.get_current_profile()) != self._current_profile:
+            self.load_file_vars()
+            self._current_profile = current
+
+    def set_origin(self) -> str:
+        """
+        Determine the default origin for credentials (env or file).
+
+        Returns
+        -------
+        str
+            The selected origin ('env' or 'file').
+
+        Raises
+        ------
+        ConfigError
+            If required credentials are missing in both sources.
+        """
+        origin = self._env
+
+        env_creds = self._creds_handler.get_credentials(self._env)
+        missing_env = self._check_credentials(env_creds)
+
+        file_creds = self._creds_handler.get_credentials(self._file)
+        missing_file = self._check_credentials(file_creds)
+
+        msg = ""
+        if missing_env:
+            msg = f"Missing required vars in env: {', '.join(missing_env)}"
+            origin = self._file
+            self._changed_origin = True
+        elif missing_file:
+            msg += f"Missing required vars in .dhcore.ini file: {', '.join(missing_file)}"
+
+        if missing_env and missing_file:
+            raise ConfigError(msg)
+
+        return origin
+
+    def eval_change_origin(self) -> None:
+        """
+        Attempt to change the origin of credentials.
+        Raise error if already evaluated.
+
+        Returns
+        -------
+        None
+        """
+        try:
+            self.change_origin()
+        except ConfigError:
+            raise ConfigError("Credentials origin already evaluated. Please check your credentials.")
+
+    def change_origin(self) -> None:
+        """
+        Change the origin of credentials from env to file or vice versa.
+
+        Returns
+        -------
+        None
+        """
+        if self._changed_origin:
+            raise ConfigError("Origin has already been changed.")
+        if self._origin == self._env:
+            self.change_to_file()
+        self.change_to_env()
+
+    def change_to_file(self) -> None:
+        """
+        Set the credentials origin to file.
+
+        Returns
+        -------
+        None
+        """
+        if self._origin == self._env:
+            self._changed_origin = True
+        self._origin = CredsOrigin.FILE.value
+
+    def change_to_env(self) -> None:
+        """
+        Set the credentials origin to environment.
+
+        Returns
+        -------
+        None
+        """
+        if self._origin == self._file:
+            self._changed_origin = True
+        self._origin = CredsOrigin.ENV.value
+
+    ##############################
+    # Credentials
+    ##############################
+
+    def get_credentials(self, origin: str) -> dict:
+        """
+        Retrieve credentials for the specified origin.
+
+        Parameters
+        ----------
+        origin : str
+            The origin to retrieve credentials from ('env' or 'file').
+
+        Returns
+        -------
+        dict
+            Dictionary of credentials.
+        """
+        return self._creds_handler.get_credentials(origin)
+
+    def _check_credentials(self, creds: dict) -> list[str]:
+        """
+        Check for missing required credentials in a dictionary.
+
+        Parameters
+        ----------
+        creds : dict
+            Dictionary of credentials to check.
+
+        Returns
+        -------
+        list of str
+            List of missing required credential keys.
+        """
+        missing_keys = []
+        for k, v in creds.items():
+            if v is None and k in self.required_keys:
+                missing_keys.append(k)
+        return missing_keys