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

digitalhub/runtimes/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -30,12 +34,29 @@ class RuntimeBuilder:
     RUNTIME_CLASS: Runtime = None
 
     def __init__(self) -> None:
+        """
+        Initialize a RuntimeBuilder instance.
+
+        Raises
+        ------
+        BuilderError
+            If RUNTIME_CLASS is not set in the implementing class.
+        """
         if self.RUNTIME_CLASS is None:
             raise BuilderError("RUNTIME_CLASS must be set")
 
     def build(self, project: str, *args, **kwargs) -> Runtime:
         """
-        Build runtime object.
+        Build a runtime object.
+
+        Parameters
+        ----------
+        project : str
+            The project identifier for the runtime instance.
+        *args
+            Additional positional arguments to pass to the Runtime constructor.
+        **kwargs
+            Additional keyword arguments to pass to the Runtime constructor.
 
         Returns
         -------

digitalhub/runtimes/enums.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from enum import Enum

digitalhub/stores/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/stores/client/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Client module for DigitalHub SDK.
+
+This module provides client implementations for interacting with different
+backends:
+- Local client for in-memory operations
+- DHCore client for remote backend communication
+
+The main entry point is through the get_client function which returns
+the appropriate client instance based on the configuration.
+"""

digitalhub/stores/client/_base/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/stores/client/_base/api_builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from abc import abstractmethod
@@ -13,4 +17,18 @@ class ClientApiBuilder:
     def build_api(self, category: str, operation: str, **kwargs) -> str:
         """
         Build the API for the client.
+
+        Parameters
+        ----------
+        category : str
+            The API category.
+        operation : str
+            The API operation.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        str
+            The formatted API endpoint.
         """

digitalhub/stores/client/_base/client.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -32,42 +36,130 @@ class Client:
     def create_object(self, api: str, obj: Any, **kwargs) -> dict:
         """
         Create object method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to create the object.
+        obj : Any
+            The object to create.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The created object.
         """
 
     @abstractmethod
     def read_object(self, api: str, **kwargs) -> dict:
         """
         Read object method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to read the object.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The retrieved object.
         """
 
     @abstractmethod
     def update_object(self, api: str, obj: Any, **kwargs) -> dict:
         """
         Update object method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to update the object.
+        obj : Any
+            The object to update.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The updated object.
         """
 
     @abstractmethod
     def delete_object(self, api: str, **kwargs) -> dict:
         """
         Delete object method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to delete the object.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The deletion result.
         """
 
     @abstractmethod
     def list_objects(self, api: str, **kwargs) -> dict:
         """
         List objects method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to list objects.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The list of objects.
         """
 
     @abstractmethod
     def list_first_object(self, api: str, **kwargs) -> dict:
         """
         Read first object method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to read the first object.
+        **kwargs : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        dict
+            The first object in the list.
         """
 
     @abstractmethod
     def search_objects(self, api: str, **kwargs) -> dict:
         """
         Search objects method.
+
+        Parameters
+        ----------
+        api : str
+            The API endpoint to search objects.
+        **kwargs : dict
+            Additional keyword arguments containing search parameters.
+
+        Returns
+        -------
+        dict
+            The search results.
         """
 
     ##############################
@@ -143,4 +235,9 @@ class Client:
     def is_local() -> bool:
         """
         Flag to check if client is local.
+
+        Returns
+        -------
+        bool
+            True if the client operates locally, False otherwise.
         """

digitalhub/stores/client/_base/key_builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from abc import abstractmethod
@@ -36,6 +40,16 @@ class ClientKeyBuilder:
     def base_entity_key(self, entity_id: str) -> str:
         """
         Build for base entity key.
+
+        Parameters
+        ----------
+        entity_id : str
+            The entity identifier.
+
+        Returns
+        -------
+        str
+            The formatted base entity key.
         """
 
     @abstractmethod
@@ -49,4 +63,22 @@ class ClientKeyBuilder:
     ) -> str:
         """
         Build for context entity key.
+
+        Parameters
+        ----------
+        project : str
+            The project name.
+        entity_type : str
+            The entity type.
+        entity_kind : str
+            The entity kind.
+        entity_name : str
+            The entity name.
+        entity_id : str, optional
+            The entity identifier. If None, key will not include version.
+
+        Returns
+        -------
+        str
+            The formatted context entity key.
         """

digitalhub/stores/client/_base/params_builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from abc import abstractmethod
@@ -13,4 +17,18 @@ class ClientParametersBuilder:
     def build_parameters(self, category: str, operation: str, **kwargs) -> dict:
         """
         Build the parameters for the client call.
+
+        Parameters
+        ----------
+        category : str
+            The API category.
+        operation : str
+            The API operation.
+        **kwargs : dict
+            Additional keyword arguments to build parameters from.
+
+        Returns
+        -------
+        dict
+            The formatted parameters for the client call.
         """

digitalhub/stores/client/api.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -14,14 +18,19 @@ def get_client(local: bool = False, config: dict | None = None) -> Client:
 
     Parameters
     ----------
-    local : bool
-        Whether to create a local client or not.
-    config : dict
-        DHCore environment configuration.
+    local : bool, default False
+        Whether to create a local client or not. If True, creates a
+        ClientLocal instance that operates in-memory. If False, creates
+        a ClientDHCore instance that communicates with a remote backend.
+    config : dict, optional
+        DHCore environment configuration. Only used when local=False.
+        If None, configuration will be loaded from environment variables
+        and configuration files.
 
     Returns
     -------
     Client
-        The client instance.
+        The client instance. Either ClientLocal or ClientDHCore depending
+        on the local parameter.
     """
     return client_builder.build(local, config)

digitalhub/stores/client/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -29,8 +33,10 @@ class ClientBuilder:
 
         Parameters
         ----------
-        local : bool
+        local : bool, default False
             Whether to create a local client or not.
+        config : dict, optional
+            DHCore environment configuration.
 
         Returns
         -------

digitalhub/stores/client/dhcore/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/stores/client/dhcore/api_builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
@@ -70,6 +74,23 @@ class ClientDHCoreApiBuilder(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.
         """
         project = kwargs["project"]
         if operation == BackendOperations.SEARCH.value: