digitalhub 0.8.1__tar.gz → 0.9.0__tar.gz

{digitalhub-0.8.1 → digitalhub-0.9.0}/LICENSE.txt

@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
    same "printed page" as the copyright notice for easier
    identification within third-party archives.
 
-Copyright [yyyy] [name of copyright owner]
+Copyright 2024 DSLab, Fondazione Bruno Kessler
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

{digitalhub-0.8.1 → digitalhub-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: digitalhub
-Version: 0.8.1
+Version: 0.9.0
 Summary: Python SDK for Digitalhub
 Author-email: Fondazione Bruno Kessler <dslab@fbk.eu>, Matteo Martini <mmartini@fbk.eu>
 License:                               Apache License
@@ -191,7 +191,7 @@ License:                               Apache License
            same "printed page" as the copyright notice for easier
            identification within third-party archives.
         
-        Copyright [yyyy] [name of copyright owner]
+        Copyright 2024 DSLab, Fondazione Bruno Kessler
         
         Licensed under the Apache License, Version 2.0 (the "License");
         you may not use this file except in compliance with the License.
@@ -230,7 +230,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: boto3
-Requires-Dist: pydantic<2
+Requires-Dist: pydantic
 Requires-Dist: sqlalchemy<2
 Requires-Dist: pyarrow
 Requires-Dist: numpy<2

{digitalhub-0.8.1 → digitalhub-0.9.0}/digitalhub/__init__.py

@@ -1,9 +1,11 @@
+__version__ = "0.9.0b0"
 from digitalhub.entities.artifact.crud import (
     delete_artifact,
     get_artifact,
     get_artifact_versions,
     import_artifact,
     list_artifacts,
+    load_artifact,
     log_artifact,
     new_artifact,
     update_artifact,
@@ -14,6 +16,7 @@ from digitalhub.entities.dataitem.crud import (
     get_dataitem_versions,
     import_dataitem,
     list_dataitems,
+    load_dataitem,
     log_dataitem,
     new_dataitem,
     update_dataitem,
@@ -24,6 +27,7 @@ from digitalhub.entities.function.crud import (
     get_function_versions,
     import_function,
     list_functions,
+    load_function,
     new_function,
     update_function,
 )
@@ -33,6 +37,7 @@ from digitalhub.entities.model.crud import (
     get_model_versions,
     import_model,
     list_models,
+    load_model,
     log_model,
     new_model,
     update_model,
@@ -42,27 +47,39 @@ from digitalhub.entities.project.crud import (
     get_or_create_project,
     get_project,
     import_project,
+    list_projects,
     load_project,
     new_project,
+    search_entity,
     update_project,
 )
-from digitalhub.entities.run.crud import delete_run, get_run, import_run, list_runs, new_run, update_run
+from digitalhub.entities.run.crud import delete_run, get_run, import_run, list_runs, load_run, new_run, update_run
 from digitalhub.entities.secret.crud import (
     delete_secret,
     get_secret,
     get_secret_versions,
     import_secret,
     list_secrets,
+    load_secret,
     new_secret,
     update_secret,
 )
-from digitalhub.entities.task.crud import delete_task, get_task, import_task, list_tasks, new_task, update_task
+from digitalhub.entities.task.crud import (
+    delete_task,
+    get_task,
+    import_task,
+    list_tasks,
+    load_task,
+    new_task,
+    update_task,
+)
 from digitalhub.entities.workflow.crud import (
     delete_workflow,
     get_workflow,
     get_workflow_versions,
     import_workflow,
     list_workflows,
+    load_workflow,
     new_workflow,
     update_workflow,
 )

digitalhub-0.9.0/digitalhub/client/_base/api_builder.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+
+
+class ClientApiBuilder:
+    """
+    This class is used to build the API for the client.
+    Depending on the client, the API is built differently.
+    """
+
+    @abstractmethod
+    def build_api(self) -> str:
+        """
+        Build the API for the client.
+        """

digitalhub-0.9.0/digitalhub/client/_base/client.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import typing
+from abc import abstractmethod
+
+if typing.TYPE_CHECKING:
+    from digitalhub.client._base.api_builder import ClientApiBuilder
+    from digitalhub.client._base.key_builder import ClientKeyBuilder
+
+
+class Client:
+    """
+    Base Client class interface.
+
+    The client is an interface that handles the CRUD of an object during
+    a session. It manages the creation, reading, updating, deleting and
+    listing of objects and comes into two subclasses: Local and DHCore.
+    """
+
+    def __init__(self) -> None:
+        self._api_builder: ClientApiBuilder = None
+        self._key_builder: ClientKeyBuilder = None
+
+    ##############################
+    # CRUD methods
+    ##############################
+
+    @abstractmethod
+    def create_object(self, api: str, obj: dict, **kwargs) -> dict:
+        """
+        Create object method.
+        """
+
+    @abstractmethod
+    def read_object(self, api: str, **kwargs) -> dict:
+        """
+        Read object method.
+        """
+
+    @abstractmethod
+    def update_object(self, api: str, obj: dict, **kwargs) -> dict:
+        """
+        Update object method.
+        """
+
+    @abstractmethod
+    def delete_object(self, api: str, **kwargs) -> dict:
+        """
+        Delete object method.
+        """
+
+    @abstractmethod
+    def list_objects(self, api: str, **kwargs) -> dict:
+        """
+        List objects method.
+        """
+
+    @abstractmethod
+    def list_first_object(self, api: str, **kwargs) -> dict:
+        """
+        Read first object method.
+        """
+
+    @abstractmethod
+    def search_objects(self, api: str, **kwargs) -> dict:
+        """
+        Search objects method.
+        """
+
+    ##############################
+    # Build methods
+    ##############################
+
+    def build_api(self, category: str, operation: str, **kwargs) -> str:
+        """
+        Build the API for the client.
+
+        Parameters
+        ----------
+        category : str
+            API category.
+        operation : str
+            API operation.
+        **kwargs : dict
+            Additional parameters.
+
+        Returns
+        -------
+        str
+            API formatted.
+        """
+        return self._api_builder.build_api(category, operation, **kwargs)
+
+    def build_key(self, category: str, *args, **kwargs) -> str:
+        """
+        Build the key for the client.
+
+        Parameters
+        ----------
+        category : str
+            Key category.
+        *args : tuple
+            Additional arguments.
+        **kwargs : dict
+            Additional parameters.
+
+        Returns
+        -------
+        str
+            Key formatted.
+        """
+        return self._key_builder.build_key(category, *args, **kwargs)
+
+    ##############################
+    # Interface methods
+    ##############################
+
+    @staticmethod
+    @abstractmethod
+    def is_local() -> bool:
+        """
+        Flag to check if client is local.
+        """

digitalhub-0.9.0/digitalhub/client/_base/key_builder.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+
+from digitalhub.entities._commons.enums import ApiCategories
+
+
+class ClientKeyBuilder:
+    """
+    Class that build the key of entities.
+    """
+
+    def build_key(self, category: str, *args, **kwargs) -> str:
+        """
+        Build key.
+
+        Parameters
+        ----------
+        category : str
+            Key category.
+        *args : tuple
+            Positional arguments.
+        **kwargs : dict
+            Keyword arguments.
+
+        Returns
+        -------
+        str
+            Key.
+        """
+        if category == ApiCategories.BASE.value:
+            return self.base_entity_key(*args, **kwargs)
+        return self.context_entity_key(*args, **kwargs)
+
+    @abstractmethod
+    def base_entity_key(self, entity_id: str) -> str:
+        """
+        Build for base entity key.
+        """
+
+    @abstractmethod
+    def context_entity_key(
+        self,
+        project: str,
+        entity_type: str,
+        entity_kind: str,
+        entity_name: str,
+        entity_id: str | None = None,
+    ) -> str:
+        """
+        Build for context entity key.
+        """

digitalhub-0.9.0/digitalhub/client/api.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.client.builder import client_builder
+
+if typing.TYPE_CHECKING:
+    from digitalhub.client._base.client import Client
+
+
+def get_client(local: bool = False, config: dict | None = None) -> Client:
+    """
+    Wrapper around ClientBuilder.build.
+
+    Parameters
+    ----------
+    local : bool
+        Whether to create a local client or not.
+    config : dict
+        DHCore environment configuration.
+
+    Returns
+    -------
+    Client
+        The client instance.
+    """
+    return client_builder.build(local, config)

digitalhub-0.9.0/digitalhub/client/dhcore/api_builder.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from digitalhub.client._base.api_builder import ClientApiBuilder
+from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
+from digitalhub.utils.exceptions import BackendError
+
+API_BASE = "/api/v1"
+API_CONTEXT = f"{API_BASE}/-"
+
+
+class ClientDHCoreApiBuilder(ClientApiBuilder):
+    """
+    This class is used to build the API for the DHCore client.
+    """
+
+    def build_api(self, category: str, operation: str, **kwargs) -> str:
+        """
+        Build the API for the client.
+
+        Parameters
+        ----------
+        category : str
+            API category.
+        operation : str
+            API operation.
+        **kwargs : dict
+            Additional parameters.
+
+        Returns
+        -------
+        str
+            API formatted.
+        """
+        if category == ApiCategories.BASE.value:
+            return self.build_api_base(operation, **kwargs)
+        return self.build_api_context(operation, **kwargs)
+
+    def build_api_base(self, operation: str, **kwargs) -> str:
+        """
+        Build the base API for the client.
+
+        Parameters
+        ----------
+        operation : str
+            API operation.
+        **kwargs : dict
+            Additional parameters.
+
+        Returns
+        -------
+        str
+            API formatted.
+        """
+        entity_type = kwargs["entity_type"] + "s"
+        if operation in (
+            BackendOperations.CREATE.value,
+            BackendOperations.LIST.value,
+        ):
+            return f"{API_BASE}/{entity_type}"
+        elif operation in (
+            BackendOperations.READ.value,
+            BackendOperations.UPDATE.value,
+            BackendOperations.DELETE.value,
+        ):
+            return f"{API_BASE}/{entity_type}/{kwargs['entity_name']}"
+        elif operation == BackendOperations.SHARE.value:
+            return f"{API_BASE}/{entity_type}/{kwargs['entity_name']}/share"
+        raise BackendError(f"Invalid operation '{operation}' for entity type '{entity_type}' in DHCore.")
+
+    def build_api_context(self, operation: str, **kwargs) -> str:
+        """
+        Build the context API for the client.
+        """
+        entity_type = kwargs["entity_type"] + "s"
+        project = kwargs["project"]
+        if operation in (
+            BackendOperations.CREATE.value,
+            BackendOperations.LIST.value,
+        ):
+            return f"{API_CONTEXT}/{project}/{entity_type}"
+        elif operation in (
+            BackendOperations.READ.value,
+            BackendOperations.UPDATE.value,
+            BackendOperations.DELETE.value,
+        ):
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}"
+        elif operation == BackendOperations.LOGS.value:
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}/logs"
+        elif operation == BackendOperations.STOP.value:
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}/stop"
+        elif operation == BackendOperations.RESUME.value:
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}/resume"
+        elif operation == BackendOperations.DATA.value:
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}/data"
+        elif operation == BackendOperations.FILES.value:
+            return f"{API_CONTEXT}/{project}/{entity_type}/{kwargs['entity_id']}/files/info"
+        elif operation == BackendOperations.SEARCH.value:
+            return f"{API_CONTEXT}/{project}/solr/search/item"
+
+        raise BackendError(f"Invalid operation '{operation}' for entity type '{entity_type}' in DHCore.")

{digitalhub-0.8.1 → digitalhub-0.9.0}/digitalhub/client/dhcore/client.py

@@ -4,7 +4,6 @@ import datetime
 import json
 import os
 import typing
-from urllib.parse import urlparse
 from warnings import warn
 
 from dotenv import get_key, set_key
@@ -12,7 +11,10 @@ from requests import request
 from requests.exceptions import HTTPError, JSONDecodeError, RequestException
 
 from digitalhub.client._base.client import Client
-from digitalhub.client.dhcore.env import ENV_FILE, FALLBACK_USER, MAX_API_LEVEL, MIN_API_LEVEL, LIB_VERSION
+from digitalhub.client.dhcore.api_builder import ClientDHCoreApiBuilder
+from digitalhub.client.dhcore.enums import AuthType, DhcoreEnvVar
+from digitalhub.client.dhcore.env import ENV_FILE, FALLBACK_USER, LIB_VERSION, MAX_API_LEVEL, MIN_API_LEVEL
+from digitalhub.client.dhcore.key_builder import ClientDHCoreKeyBuilder
 from digitalhub.client.dhcore.models import BasicAuth, OAuth2TokenAuth
 from digitalhub.utils.exceptions import (
     BackendError,
@@ -23,6 +25,7 @@ from digitalhub.utils.exceptions import (
     MissingSpecError,
     UnauthorizedError,
 )
+from digitalhub.utils.uri_utils import has_remote_scheme
 
 if typing.TYPE_CHECKING:
     from requests import Response
@@ -47,6 +50,12 @@ class ClientDHCore(Client):
     def __init__(self, config: dict | None = None) -> None:
         super().__init__()
 
+        # API builder
+        self._api_builder = ClientDHCoreApiBuilder()
+
+        # Key builder
+        self._key_builder = ClientDHCoreKeyBuilder()
+
         # Endpoints
         self._endpoint_core: str | None = None
         self._endpoint_issuer: str | None = None
@@ -214,6 +223,56 @@ class ClientDHCore(Client):
         except IndexError:
             raise BackendError("No object found.")
 
+    def search_objects(self, api: str, **kwargs) -> list[dict]:
+        """
+        Search objects from DHCore.
+
+        Parameters
+        ----------
+        api : str
+            Search API.
+        **kwargs : dict
+            Keyword arguments to pass to the request.
+
+        Returns
+        -------
+        list[dict]
+            Response objects.
+        """
+        if kwargs is None:
+            kwargs = {}
+
+        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"
+
+        objects_with_highlights = []
+        while True:
+            resp = self._prepare_call("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
+
+        objects = []
+        for obj in objects_with_highlights:
+            obj.pop("highlights", None)
+            objects.append(obj)
+
+        return objects
+
     ##############################
     # Call methods
     ##############################
@@ -275,9 +334,9 @@ class ClientDHCore(Client):
         dict
             Keyword arguments with the authentication parameters.
         """
-        if self._auth_type == "basic":
+        if self._auth_type == AuthType.BASIC.value:
             kwargs["auth"] = self._user, self._password
-        elif self._auth_type == "oauth2":
+        elif self._auth_type == AuthType.OAUTH2.value:
             if "headers" not in kwargs:
                 kwargs["headers"] = {}
             kwargs["headers"]["Authorization"] = f"Bearer {self._access_token}"
@@ -465,7 +524,6 @@ class ClientDHCore(Client):
         -------
         None
         """
-
         self._get_endpoints_from_env()
 
         if config is not None:
@@ -475,21 +533,20 @@ class ClientDHCore(Client):
                 self._access_token = config.access_token
                 self._refresh_token = config.refresh_token
                 self._client_id = config.client_id
-                self._auth_type = "oauth2"
+                self._auth_type = AuthType.OAUTH2.value
 
             elif config.get("user") is not None and config.get("password") is not None:
                 config = BasicAuth(**config)
                 self._user = config.user
                 self._password = config.password
-                self._auth_type = "basic"
+                self._auth_type = AuthType.BASIC.value
 
             return
 
         self._get_auth_from_env()
 
         # Propagate access and refresh token to env file
-        if not ENV_FILE.exists():
-            self._write_env()
+        self._write_env()
 
     def _get_endpoints_from_env(self) -> None:
         """
@@ -504,12 +561,12 @@ class ClientDHCore(Client):
         Exception
             If the endpoint of DHCore is not set in the env variables.
         """
-        core_endpt = os.getenv("DHCORE_ENDPOINT")
+        core_endpt = os.getenv(DhcoreEnvVar.ENDPOINT.value)
         if core_endpt is None:
             raise BackendError("Endpoint not set as environment variables.")
         self._endpoint_core = self._sanitize_endpoint(core_endpt)
 
-        issr_endpt = os.getenv("DHCORE_ISSUER")
+        issr_endpt = os.getenv(DhcoreEnvVar.ISSUER.value)
         if issr_endpt is not None:
             self._endpoint_issuer = self._sanitize_endpoint(issr_endpt)
 
@@ -521,9 +578,8 @@ class ClientDHCore(Client):
         -------
         None
         """
-        parsed = urlparse(endpoint)
-        if parsed.scheme not in ["http", "https"]:
-            raise BackendError("Invalid endpoint scheme.")
+        if not has_remote_scheme(endpoint):
+            raise BackendError("Invalid endpoint scheme. Must start with http:// or https://.")
 
         endpoint = endpoint.strip()
         return endpoint.removesuffix("/")
@@ -536,19 +592,19 @@ class ClientDHCore(Client):
         -------
         None
         """
-        self._user = os.getenv("DHCORE_USER", FALLBACK_USER)
-        self._refresh_token = os.getenv("DHCORE_REFRESH_TOKEN")
-        self._client_id = os.getenv("DHCORE_CLIENT_ID")
+        self._user = os.getenv(DhcoreEnvVar.USER.value, FALLBACK_USER)
+        self._refresh_token = os.getenv(DhcoreEnvVar.REFRESH_TOKEN.value)
+        self._client_id = os.getenv(DhcoreEnvVar.CLIENT_ID.value)
 
-        token = os.getenv("DHCORE_ACCESS_TOKEN")
+        token = os.getenv(DhcoreEnvVar.ACCESS_TOKEN.value)
         if token is not None and token != "":
-            self._auth_type = "oauth2"
+            self._auth_type = AuthType.OAUTH2.value
             self._access_token = token
             return
 
-        password = os.getenv("DHCORE_PASSWORD")
+        password = os.getenv(DhcoreEnvVar.PASSWORD.value)
         if self._user is not None and password is not None:
-            self._auth_type = "basic"
+            self._auth_type = AuthType.BASIC.value
             self._password = password
             return
 
@@ -566,12 +622,12 @@ class ClientDHCore(Client):
 
         # Call refresh token endpoint
         # Try token from env
-        refresh_token = os.getenv("DHCORE_REFRESH_TOKEN")
+        refresh_token = os.getenv(DhcoreEnvVar.REFRESH_TOKEN.value)
         response = self._call_refresh_token_endpoint(url, refresh_token)
 
         # Otherwise try token from file
         if response.status_code in (400, 401, 403):
-            refresh_token = get_key(ENV_FILE, "DHCORE_REFRESH_TOKEN")
+            refresh_token = get_key(ENV_FILE, DhcoreEnvVar.REFRESH_TOKEN.value)
             response = self._call_refresh_token_endpoint(url, refresh_token)
 
         response.raise_for_status()
@@ -641,9 +697,9 @@ class ClientDHCore(Client):
         """
         keys = {}
         if self._access_token is not None:
-            keys["DHCORE_ACCESS_TOKEN"] = self._access_token
+            keys[DhcoreEnvVar.ACCESS_TOKEN.value] = self._access_token
         if self._refresh_token is not None:
-            keys["DHCORE_REFRESH_TOKEN"] = self._refresh_token
+            keys[DhcoreEnvVar.REFRESH_TOKEN.value] = self._refresh_token
 
         for k, v in keys.items():
             set_key(dotenv_path=ENV_FILE, key_to_set=k, value_to_set=v)

digitalhub-0.9.0/digitalhub/client/dhcore/enums.py

@@ -0,0 +1,27 @@
+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"
+    WORKFLOW_IMAGE = "DHCORE_WORKFLOW_IMAGE"
+
+
+class AuthType(Enum):
+    """
+    Authentication types.
+    """
+
+    BASIC = "basic"
+    OAUTH2 = "oauth2"

{digitalhub-0.8.1 → digitalhub-0.9.0}/digitalhub/client/dhcore/env.py

@@ -19,5 +19,5 @@ ENV_FILE = Path.home() / ".dhcore"
 
 # API levels that are supported
 MAX_API_LEVEL = 20
-MIN_API_LEVEL = 8
-LIB_VERSION = 8
+MIN_API_LEVEL = 9
+LIB_VERSION = 9