digitalhub 0.13.0b2__py3-none-any.whl → 0.13.0b4__py3-none-any.whl

digitalhub/factory/factory.py

@@ -55,9 +55,13 @@ class Factory:
         ----------
         name : str
             The unique identifier for the builder.
-        builder : EntityBuilder | RuntimeEntityBuilder
+        builder : EntityBuilder or RuntimeEntityBuilder
             The builder instance to register.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         BuilderError
@@ -78,6 +82,10 @@ class Factory:
         builder : RuntimeBuilder
             The builder instance to register.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         BuilderError
@@ -137,6 +145,8 @@ class Factory:
         ----------
         kind_to_build_from : str
             Entity type.
+        **kwargs
+            Additional spec parameters.
 
         Returns
         -------
@@ -154,6 +164,8 @@ class Factory:
         ----------
         kind_to_build_from : str
             Entity type.
+        **kwargs
+            Additional metadata parameters.
 
         Returns
         -------
@@ -171,6 +183,8 @@ class Factory:
         ----------
         kind_to_build_from : str
             Entity type.
+        **kwargs
+            Additional status parameters.
 
         Returns
         -------
@@ -265,7 +279,7 @@ class Factory:
 
         Returns
         -------
-        list[str]
+        list of str
             Task kinds.
         """
         self._raise_if_entity_builder_not_found(kind)
@@ -299,7 +313,7 @@ class Factory:
 
         Returns
         -------
-        list[str]
+        list of str
             All kinds.
         """
         return self._entity_builders[kind].get_all_kinds()
@@ -330,6 +344,10 @@ class Factory:
         kind : str
             The entity kind to verify.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         BuilderError
@@ -347,6 +365,10 @@ class Factory:
         kind : str
             The runtime kind to verify.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         BuilderError

digitalhub/factory/utils.py

@@ -50,7 +50,7 @@ def list_runtimes() -> list[str]:
 
     Returns
     -------
-    list[str]
+    list of str
         List of runtime package names.
 
     Raises
@@ -75,6 +75,10 @@ def register_runtimes_entities() -> None:
 
     Imports each runtime package and registers its entity and runtime
     builders with the global factory instance.
+
+    Returns
+    -------
+    None
     """
     for package in list_runtimes():
         module = import_module(package)
@@ -93,8 +97,12 @@ def register_entities() -> None:
     """
     Register core entity builders into the factory.
 
-    Imports the core entities module and registers all entity builders
-    with the global factory instance.
+    Imports the core entities module and registers all entity
+    builders with the global factory instance.
+
+    Returns
+    -------
+    None
 
     Raises
     ------

digitalhub/runtimes/_base.py

@@ -89,7 +89,7 @@ class Runtime:
             Function to execute.
         *args
             Function arguments.
-        **kwargs : dict
+        **kwargs
             Function keyword arguments.
 
         Returns

digitalhub/runtimes/builder.py

@@ -34,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/stores/client/__init__.py

@@ -1,3 +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/api_builder.py

@@ -17,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

@@ -36,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.
         """
 
     ##############################
@@ -147,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

@@ -40,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
@@ -53,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

@@ -17,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

@@ -18,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

@@ -33,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/api_builder.py

@@ -74,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: