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

digitalhub/entities/workflow/crud.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._commons.enums import EntityTypes
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import context_processor
 
 if typing.TYPE_CHECKING:
     from digitalhub.entities.workflow._base.entity import Workflow
@@ -75,7 +75,6 @@ def get_workflow(
     identifier: str,
     project: str | None = None,
     entity_id: str | None = None,
-    **kwargs,
 ) -> Workflow:
     """
     Get object from backend.
@@ -88,8 +87,6 @@ def get_workflow(
         Project name.
     entity_id : str
         Entity ID.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -99,9 +96,7 @@ def get_workflow(
     Examples
     --------
     Using entity key:
-    >>> obj = get_workflow(
-    ...     "store://my-workflow-key"
-    ... )
+    >>> obj = get_workflow("store://my-workflow-key")
 
     Using entity name:
     >>> obj = get_workflow("my-workflow-name"
@@ -109,18 +104,16 @@ def get_workflow(
     >>>                    entity_id="my-workflow-id")
     """
     return context_processor.read_context_entity(
-        identifier,
+        identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
         entity_id=entity_id,
-        **kwargs,
     )
 
 
 def get_workflow_versions(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> list[Workflow]:
     """
     Get object versions from backend.
@@ -131,8 +124,6 @@ def get_workflow_versions(
         Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -142,23 +133,30 @@ def get_workflow_versions(
     Examples
     --------
     Using entity key:
-    >>> obj = get_workflow_versions(
-    ...     "store://my-workflow-key"
-    ... )
+    >>> obj = get_workflow_versions("store://my-workflow-key")
 
     Using entity name:
     >>> obj = get_workflow_versions("my-workflow-name"
     >>>                             project="my-project")
     """
     return context_processor.read_context_entity_versions(
-        identifier,
+        identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_workflows(project: str, **kwargs) -> list[Workflow]:
+def list_workflows(
+    project: str,
+    q: str | None = None,
+    name: str | None = None,
+    kind: str | None = None,
+    user: str | None = None,
+    state: str | None = None,
+    created: str | None = None,
+    updated: str | None = None,
+    version: str | None = None,
+) -> list[Workflow]:
     """
     List all latest version objects from backend.
 
@@ -166,8 +164,22 @@ def list_workflows(project: str, **kwargs) -> list[Workflow]:
     ----------
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
+    q : str
+        Query string to filter objects.
+    name : str
+        Object name.
+    kind : str
+        Kind of the object.
+    user : str
+        User that created the object.
+    state : str
+        Object state.
+    created : str
+        Creation date filter.
+    updated : str
+        Update date filter.
+    version : str
+        Object version, default is latest.
 
     Returns
     -------
@@ -176,14 +188,19 @@ def list_workflows(project: str, **kwargs) -> list[Workflow]:
 
     Examples
     --------
-    >>> objs = list_workflows(
-    ...     project="my-project"
-    ... )
+    >>> objs = list_workflows(project="my-project")
     """
     return context_processor.list_context_entities(
         project=project,
         entity_type=ENTITY_TYPE,
-        **kwargs,
+        q=q,
+        name=name,
+        kind=kind,
+        user=user,
+        state=state,
+        created=created,
+        updated=updated,
+        version=version,
     )
 
 
@@ -214,9 +231,7 @@ def import_workflow(
 
     Examples
     --------
-    >>> obj = import_workflow(
-    ...     "my-workflow.yaml"
-    ... )
+    >>> obj = import_workflow("my-workflow.yaml")
     """
     return context_processor.import_executable_entity(file, key, reset_id, context)
 
@@ -237,9 +252,7 @@ def load_workflow(file: str) -> Workflow:
 
     Examples
     --------
-    >>> obj = load_workflow(
-    ...     "my-workflow.yaml"
-    ... )
+    >>> obj = load_workflow("my-workflow.yaml")
     """
     return context_processor.load_executable_entity(file)
 
@@ -260,11 +273,7 @@ def update_workflow(entity: Workflow) -> Workflow:
 
     Examples
     --------
-    >>> obj = (
-    ...     update_workflow(
-    ...         obj
-    ...     )
-    ... )
+    >>> obj = update_workflow(obj)
     """
     return context_processor.update_context_entity(
         project=entity.project,
@@ -294,7 +303,8 @@ def delete_workflow(
     entity_id : str
         Entity ID.
     delete_all_versions : bool
-        Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+        Delete all versions of the named entity.
+        If True, use entity name instead of entity key as identifier.
     cascade : bool
         Cascade delete.
     **kwargs : dict
@@ -308,9 +318,7 @@ def delete_workflow(
     Examples
     --------
     If delete_all_versions is False:
-    >>> obj = delete_workflow(
-    ...     "store://my-workflow-key"
-    ... )
+    >>> obj = delete_workflow("store://my-workflow-key")
 
     Otherwise:
     >>> obj = delete_workflow("workflow-name",
@@ -324,5 +332,4 @@ def delete_workflow(
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
         cascade=cascade,
-        **kwargs,
     )

digitalhub/factory/registry.py

@@ -47,10 +47,6 @@ class BuilderRegistry:
         builder : type[EntityBuilder] | type[RuntimeEntityBuilder]
             The builder class to register. It will be instantiated immediately.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         BuilderError
@@ -71,10 +67,6 @@ class BuilderRegistry:
         builder : type[RuntimeBuilder]
             The builder class to register. It will be instantiated immediately.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         BuilderError
@@ -141,10 +133,6 @@ class BuilderRegistry:
     def _ensure_entities_registered(self) -> None:
         """
         Ensure core entities are registered on-demand.
-
-        Returns
-        -------
-        None
         """
         if self._entities_registered:
             return
@@ -160,10 +148,6 @@ class BuilderRegistry:
 
         Imports the core entities module and registers all entity
         builders with the registry.
-
-        Returns
-        -------
-        None
         """
         try:
             module = import_module(FactoryEnum.REG_ENTITIES.value)
@@ -178,10 +162,6 @@ class BuilderRegistry:
     def _ensure_runtimes_registered(self) -> None:
         """
         Ensure runtime entities are registered on-demand.
-
-        Returns
-        -------
-        None
         """
         if self._runtimes_registered:
             return
@@ -197,10 +177,6 @@ class BuilderRegistry:
 
         Imports each runtime package and registers its entity and runtime
         builders with the registry.
-
-        Returns
-        -------
-        None
         """
         try:
             for package in list_runtimes():

digitalhub/stores/client/_base/enums.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ApiCategories(Enum):
+    """
+    API categories.
+    """
+
+    BASE = "base"
+    CONTEXT = "context"
+
+
+class BackendOperations(Enum):
+    """
+    Backend operations.
+    """
+
+    CREATE = "create"
+    READ = "read"
+    READ_ALL_VERSIONS = "read_all_versions"
+    UPDATE = "update"
+    DELETE = "delete"
+    DELETE_ALL_VERSIONS = "delete_all_versions"
+    LIST = "list"
+    LIST_FIRST = "list_first"
+    STOP = "stop"
+    RESUME = "resume"
+    DATA = "data"
+    FILES = "files"
+    LOGS = "logs"
+    SEARCH = "search"
+    SHARE = "share"
+    METRICS = "metrics"

digitalhub/stores/client/_base/key_builder.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from abc import abstractmethod
 
-from digitalhub.entities._commons.enums import ApiCategories
+from digitalhub.stores.client._base.enums import ApiCategories
 
 
 class ClientKeyBuilder:

digitalhub/stores/client/_base/params_builder.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 from abc import abstractmethod
+from typing import Any
 
 
 class ClientParametersBuilder:
@@ -32,3 +33,50 @@ class ClientParametersBuilder:
         dict
             The formatted parameters for the client call.
         """
+
+    @staticmethod
+    def _ensure_params(**kwargs) -> dict:
+        """
+        Initialize parameter dictionary with query parameters structure.
+
+        Ensures parameter dictionary has 'params' key for HTTP query parameters,
+        guaranteeing consistent structure for all parameter building methods.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with guaranteed 'params' key containing
+            empty dict if not already present.
+        """
+        if "params" not in kwargs:
+            kwargs["params"] = {}
+        return kwargs
+
+    @staticmethod
+    def _add_param(key: str, value: Any | None, **kwargs) -> dict:
+        """
+        Add a single query parameter to kwargs.
+
+        Parameters
+        ----------
+        key : str
+            Parameter key.
+        value : Any
+            Parameter value.
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with added key-value pair in 'params'.
+        """
+        kwargs["params"][key] = value
+        return kwargs

digitalhub/stores/client/dhcore/api_builder.py

@@ -4,8 +4,8 @@
 
 from __future__ import annotations
 
-from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
 from digitalhub.stores.client._base.api_builder import ClientApiBuilder
+from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
 from digitalhub.utils.exceptions import BackendError
 
 API_BASE = "/api/v1"
@@ -100,6 +100,7 @@ class ClientDHCoreApiBuilder(ClientApiBuilder):
         if operation in (
             BackendOperations.CREATE.value,
             BackendOperations.LIST.value,
+            BackendOperations.DELETE_ALL_VERSIONS.value,
         ):
             return f"{API_CONTEXT}/{project}/{entity_type}"
         elif operation in (

digitalhub/stores/client/dhcore/client.py

@@ -29,6 +29,9 @@ MAX_API_LEVEL = 20
 MIN_API_LEVEL = 14
 LIB_VERSION = 14
 
+# Default timeout for requests (in seconds)
+DEFAULT_TIMEOUT = 60
+
 
 class ClientDHCore(Client):
     """
@@ -58,16 +61,6 @@ class ClientDHCore(Client):
         Parses backend responses and raises appropriate exceptions.
     _configurator : ClientDHCoreConfigurator
         Manages client configuration and authentication.
-
-    Examples
-    --------
-    >>> from digitalhub.stores.client.api import (
-    ...     get_client,
-    ... )
-    >>> client = get_client(
-    ...     local=False
-    ... )
-    >>> # Client is now ready for API operations
     """
 
     def __init__(self, config: dict | None = None) -> None:
@@ -79,21 +72,17 @@ class ClientDHCore(Client):
         config : dict, optional
             DHCore environment configuration. If None, loads from environment
             variables and configuration files.
-
-        Returns
-        -------
-        None
         """
         super().__init__()
 
         # API builder
-        self._api_builder = ClientDHCoreApiBuilder()
+        self._api_builder: ClientDHCoreApiBuilder = ClientDHCoreApiBuilder()
 
         # Key builder
-        self._key_builder = ClientDHCoreKeyBuilder()
+        self._key_builder: ClientDHCoreKeyBuilder = ClientDHCoreKeyBuilder()
 
         # Parameters builder
-        self._params_builder = ClientDHCoreParametersBuilder()
+        self._params_builder: ClientDHCoreParametersBuilder = ClientDHCoreParametersBuilder()
 
         # Error parser
         self._error_parser = ErrorParser()
@@ -132,9 +121,7 @@ class ClientDHCore(Client):
         ClientError
             If there are client-side configuration issues.
         """
-        if "headers" not in kwargs:
-            kwargs["headers"] = {}
-        kwargs["headers"]["Content-Type"] = "application/json"
+        kwargs = self._set_application_json_header(**kwargs)
         kwargs["data"] = dump_json(obj)
         return self._prepare_call("POST", api, **kwargs)
 
@@ -192,9 +179,7 @@ class ClientDHCore(Client):
         EntityNotExistsError
             If the object to update does not exist.
         """
-        if "headers" not in kwargs:
-            kwargs["headers"] = {}
-        kwargs["headers"]["Content-Type"] = "application/json"
+        kwargs = self._set_application_json_header(**kwargs)
         kwargs["data"] = dump_json(obj)
         return self._prepare_call("PUT", api, **kwargs)
 
@@ -254,22 +239,17 @@ class ClientDHCore(Client):
         BackendError
             If the backend returns an error response.
         """
-        if "params" not in kwargs:
-            kwargs["params"] = {}
-
-        start_page = 0
-        if "page" not in kwargs["params"]:
-            kwargs["params"]["page"] = start_page
+        kwargs = self._params_builder.set_pagination(partial=True, **kwargs)
 
         objects = []
         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.extend(contents)
-            kwargs["params"]["page"] += 1
+            if not contents or self._params_builder.read_page_number(**kwargs) >= (total_pages - 1):
+                break
+            self._params_builder.increment_page_number(**kwargs)
 
         return objects
 
@@ -328,29 +308,16 @@ class ClientDHCore(Client):
         BackendError
             If the backend returns an error response.
         """
-        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"
-
+        kwargs = self._params_builder.set_pagination(**kwargs)
         objects_with_highlights: list[dict] = []
         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
+            if not contents or self._params_builder.read_page_number(**kwargs) >= (total_pages - 1):
+                break
+            self._params_builder.increment_page_number(**kwargs)
 
         objects = []
         for obj in objects_with_highlights:
@@ -395,25 +362,6 @@ class ClientDHCore(Client):
         full_kwargs = self._configurator.get_auth_parameters(kwargs)
         return self._make_call(call_type, url, **full_kwargs)
 
-    def _build_url(self, api: str) -> str:
-        """
-        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. Automatically removes leading
-        slashes from the API path to ensure proper URL construction.
-
-        Parameters
-        ----------
-        api : str
-            The API endpoint path. Leading slashes are automatically handled.
-
-        Returns
-        -------
-        str
-            The complete URL for the API call.
-        """
-
     def _build_url(self, api: str) -> str:
         """
         Build complete URL for API call.
@@ -468,7 +416,7 @@ class ClientDHCore(Client):
             If authentication fails and token refresh not possible.
         """
         # Call the API
-        response = request(call_type, url, timeout=60, **kwargs)
+        response = request(call_type, url, timeout=DEFAULT_TIMEOUT, **kwargs)
 
         # Evaluate DHCore API version
         self._check_core_version(response)
@@ -494,10 +442,6 @@ class ClientDHCore(Client):
         response : Response
             HTTP response containing X-Api-Level header.
 
-        Returns
-        -------
-        None
-
         Raises
         ------
         ClientError
@@ -557,3 +501,53 @@ class ClientDHCore(Client):
             False, indicating this client communicates with remote DHCore backend.
         """
         return False
+
+    ##############################
+    # Utility methods
+    ##############################
+
+    @staticmethod
+    def _ensure_header(**kwargs) -> dict:
+        """
+        Initialize header dictionary.
+
+        Ensures parameter dictionary has 'headers' key for HTTP headers,
+        guaranteeing consistent structure for all parameter building methods.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Headers dictionary with guaranteed 'headers' key containing
+            empty dict if not already present.
+        """
+        if "headers" not in kwargs:
+            kwargs["headers"] = {}
+        return kwargs
+
+    def _set_application_json_header(self, **kwargs) -> dict:
+        """
+        Set Content-Type header to application/json.
+
+        Ensures that the 'Content-Type' header is set to 'application/json'
+        for requests that require JSON payloads.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Headers dictionary with 'Content-Type' set to 'application/json'.
+        """
+        kwargs = self._ensure_header(**kwargs)
+        kwargs["headers"]["Content-Type"] = "application/json"
+        return kwargs