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

digitalhub/entities/_processors/context/special_ops.py

@@ -0,0 +1,476 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from typing import Any
+
+from digitalhub.entities._processors.utils import get_context_from_project
+from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.context.entity import ContextEntity
+    from digitalhub.entities._processors.context.crud import ContextEntityCRUDProcessor
+
+
+class ContextEntitySpecialOpsProcessor:
+    """
+    Processor for specialized context entity operations.
+
+    Handles backend operations like secrets management, logging,
+    entity control (start/stop/resume), file operations, and metrics.
+    """
+
+    def build_context_entity_key(
+        self,
+        project: str,
+        entity_type: str,
+        entity_kind: str,
+        entity_name: str,
+        entity_id: str | None = None,
+    ) -> str:
+        """
+        Build a storage key for a context entity.
+
+        Creates a standardized key string for context entity identification
+        and storage, resolving the project context automatically.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity.
+        entity_kind : str
+            The kind/subtype of entity.
+        entity_name : str
+            The name of the entity.
+        entity_id : str, optional
+            The unique identifier of the entity version.
+
+        Returns
+        -------
+        str
+            The constructed context entity key string.
+        """
+        context = get_context_from_project(project)
+        return context.client.build_key(
+            ApiCategories.CONTEXT.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_kind=entity_kind,
+            entity_name=entity_name,
+            entity_id=entity_id,
+        )
+
+    def read_secret_data(
+        self,
+        project: str,
+        entity_type: str,
+        **kwargs,
+    ) -> dict:
+        """
+        Read secret data from the backend.
+
+        Retrieves secret data stored in the backend for a specific
+        project and entity type.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the secrets.
+        entity_type : str
+            The type of entity (typically 'secret').
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            Secret data retrieved from the backend.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.DATA.value,
+            project=context.name,
+            entity_type=entity_type,
+        )
+        return context.client.read_object(api, **kwargs)
+
+    def update_secret_data(
+        self,
+        project: str,
+        entity_type: str,
+        data: dict,
+        **kwargs,
+    ) -> None:
+        """
+        Update secret data in the backend.
+
+        Stores or updates secret data in the backend for a specific
+        project and entity type.
+
+        Parameters
+        ----------
+        project : str
+            The project name to store secrets in.
+        entity_type : str
+            The type of entity (typically 'secret').
+        data : dict
+            The secret data dictionary to store.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.DATA.value,
+            project=context.name,
+            entity_type=entity_type,
+        )
+        context.client.update_object(api, data, **kwargs)
+
+    def read_run_logs(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        **kwargs,
+    ) -> dict:
+        """
+        Read execution logs from the backend.
+
+        Retrieves logs for a specific run or task execution from
+        the backend.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity (typically 'run' or 'task').
+        entity_id : str
+            The unique identifier of the entity to get logs for.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            Log data retrieved from the backend.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.LOGS.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        return context.client.read_object(api, **kwargs)
+
+    def stop_entity(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        **kwargs,
+    ) -> None:
+        """
+        Stop a running entity in the backend.
+
+        Sends a stop signal to halt execution of a running entity
+        such as a workflow or long-running task.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity to stop.
+        entity_id : str
+            The unique identifier of the entity to stop.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.STOP.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        context.client.create_object(api, **kwargs)
+
+    def resume_entity(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        **kwargs,
+    ) -> None:
+        """
+        Resume a stopped entity in the backend.
+
+        Sends a resume signal to restart execution of a previously
+        stopped entity such as a workflow or task.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity to resume.
+        entity_id : str
+            The unique identifier of the entity to resume.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.RESUME.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        context.client.create_object(api, **kwargs)
+
+    def read_files_info(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        **kwargs,
+    ) -> list[dict]:
+        """
+        Read file information from the backend.
+
+        Retrieves metadata about files associated with an entity,
+        including file paths, sizes, and other attributes.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity to get file info for.
+        entity_id : str
+            The unique identifier of the entity.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        list[dict]
+            List of file information dictionaries from the backend.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.FILES.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        return context.client.read_object(api, **kwargs)
+
+    def update_files_info(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        entity_list: list[dict],
+        **kwargs,
+    ) -> None:
+        """
+        Get files info from backend.
+
+        Parameters
+        ----------
+        project : str
+            Project name.
+        entity_type : str
+            Entity type.
+        entity_id : str
+            Entity ID.
+        entity_list : list[dict]
+            Entity list.
+        **kwargs : dict
+            Parameters to pass to the API call.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.FILES.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+        )
+        return context.client.update_object(api, entity_list, **kwargs)
+
+    def read_metrics(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        metric_name: str | None = None,
+        **kwargs,
+    ) -> dict:
+        """
+        Read metrics from the backend for a specific entity.
+
+        Retrieves metrics data associated with an entity. Can fetch either
+        all metrics or a specific metric by name. Used for performance
+        monitoring and analysis of entity operations.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity to read metrics from.
+        entity_id : str
+            The unique identifier of the entity.
+        metric_name : str, optional
+            The name of a specific metric to retrieve.
+            If None, retrieves all available metrics.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            Dictionary containing metric data from the backend.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.METRICS.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            metric_name=metric_name,
+        )
+        return context.client.read_object(api, **kwargs)
+
+    def update_metric(
+        self,
+        project: str,
+        entity_type: str,
+        entity_id: str,
+        metric_name: str,
+        metric_value: Any,
+        **kwargs,
+    ) -> None:
+        """
+        Update or create a metric value for an entity in the backend.
+
+        Updates an existing metric or creates a new one with the specified
+        value. Metrics are used for tracking performance, status, and
+        other quantitative aspects of entity operations.
+
+        Parameters
+        ----------
+        project : str
+            The project name containing the entity.
+        entity_type : str
+            The type of entity to update metrics for.
+        entity_id : str
+            The unique identifier of the entity.
+        metric_name : str
+            The name of the metric to update or create.
+        metric_value : Any
+            The value to set for the metric.
+            Can be numeric, string, or other supported types.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+        """
+        context = get_context_from_project(project)
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.METRICS.value,
+            project=context.name,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            metric_name=metric_name,
+        )
+        context.client.update_object(api, metric_value, **kwargs)
+
+    def search_entity(
+        self,
+        crud_processor: ContextEntityCRUDProcessor,
+        project: str,
+        query: str | None = None,
+        entity_types: list[str] | None = None,
+        name: str | None = None,
+        kind: str | None = None,
+        created: str | None = None,
+        updated: str | None = None,
+        description: str | None = None,
+        labels: list[str] | None = None,
+        **kwargs,
+    ) -> list[ContextEntity]:
+        """
+        Search for entities in the backend using various criteria.
+
+        Performs a flexible search across multiple entity attributes,
+        allowing for complex queries and filtering. Returns matching
+        entities from the project context.
+
+        Parameters
+        ----------
+        crud_processor : ContextEntityCRUDProcessor
+            The CRUD processor instance for entity operations.
+        project : str
+            The project name to search within.
+        query : str, optional
+            Free-text search query to match against entity content.
+        entity_types : list[str], optional
+            List of entity types to filter by.
+            If None, searches all entity types.
+        name : str, optional
+            Entity name pattern to match.
+        kind : str, optional
+            Entity kind to filter by.
+        created : str, optional
+            Creation date filter (ISO format).
+        updated : str, optional
+            Last update date filter (ISO format).
+        description : str, optional
+            Description pattern to match.
+        labels : list[str], optional
+            List of label patterns to match.
+        **kwargs : dict
+            Additional search parameters to pass to the API call.
+
+        Returns
+        -------
+        list[ContextEntity]
+            List of matching entity instances from the search.
+        """
+        context = get_context_from_project(project)
+        kwargs = context.client.build_parameters(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.SEARCH.value,
+            query=query,
+            entity_types=entity_types,
+            name=name,
+            kind=kind,
+            created=created,
+            updated=updated,
+            description=description,
+            labels=labels,
+            **kwargs,
+        )
+        api = context.client.build_api(
+            ApiCategories.CONTEXT.value,
+            BackendOperations.SEARCH.value,
+            project=context.name,
+        )
+        entities_dict = context.client.read_object(api, **kwargs)
+        return [crud_processor.read_context_entity(entity["key"]) for entity in entities_dict["content"]]

digitalhub/entities/_processors/processors.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from digitalhub.entities._processors.base.processor import BaseEntityOperationsProcessor
+from digitalhub.entities._processors.context.processor import ContextEntityOperationsProcessor
+
+# Base processor singleton instance
+base_processor = BaseEntityOperationsProcessor()
+
+# Context processor singleton instance
+context_processor = ContextEntityOperationsProcessor()

digitalhub/entities/_processors/utils.py

@@ -7,9 +7,10 @@ from __future__ import annotations
 import typing
 
 from digitalhub.context.api import get_context
-from digitalhub.entities._commons.enums import ApiCategories, BackendOperations, EntityTypes
+from digitalhub.entities._commons.enums import EntityTypes
 from digitalhub.entities._commons.utils import get_project_from_key, is_valid_key, parse_entity_key
 from digitalhub.factory.entity import entity_factory
+from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
 from digitalhub.stores.client.api import get_client
 from digitalhub.utils.exceptions import ContextError, EntityError, EntityNotExistsError
 

digitalhub/entities/artifact/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
 from digitalhub.entities.artifact._base.entity import Artifact
 from digitalhub.entities.artifact.utils import eval_source, process_kwargs
 from digitalhub.utils.types import SourcesOrListOfSources
@@ -132,7 +132,6 @@ def get_artifact(
     identifier: str,
     project: str | None = None,
     entity_id: str | None = None,
-    **kwargs,
 ) -> Artifact:
     """
     Get object from backend.
@@ -145,8 +144,6 @@ def get_artifact(
         Project name.
     entity_id : str
         Entity ID.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -156,9 +153,7 @@ def get_artifact(
     Examples
     --------
     Using entity key:
-    >>> obj = get_artifact(
-    ...     "store://my-artifact-key"
-    ... )
+    >>> obj = get_artifact("store://my-artifact-key")
 
     Using entity name:
     >>> obj = get_artifact("my-artifact-name"
@@ -170,14 +165,12 @@ def get_artifact(
         entity_type=ENTITY_TYPE,
         project=project,
         entity_id=entity_id,
-        **kwargs,
     )
 
 
 def get_artifact_versions(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> list[Artifact]:
     """
     Get object versions from backend.
@@ -188,8 +181,6 @@ def get_artifact_versions(
         Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -199,9 +190,7 @@ def get_artifact_versions(
     Examples
     --------
     Using entity key:
-    >>> obj = get_artifact_versions(
-    ...     "store://my-artifact-key"
-    ... )
+    >>> obj = get_artifact_versions("store://my-artifact-key")
 
     Using entity name:
     >>> obj = get_artifact_versions("my-artifact-name"
@@ -211,11 +200,20 @@ def get_artifact_versions(
         identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_artifacts(project: str, **kwargs) -> list[Artifact]:
+def list_artifacts(
+    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[Artifact]:
     """
     List all latest version objects from backend.
 
@@ -223,8 +221,22 @@ def list_artifacts(project: str, **kwargs) -> list[Artifact]:
     ----------
     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
     -------
@@ -233,14 +245,19 @@ def list_artifacts(project: str, **kwargs) -> list[Artifact]:
 
     Examples
     --------
-    >>> objs = list_artifacts(
-    ...     project="my-project"
-    ... )
+    >>> objs = list_artifacts(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,
     )
 
 
@@ -271,9 +288,7 @@ def import_artifact(
 
     Examples
     --------
-    >>> obj = import_artifact(
-    ...     "my-artifact.yaml"
-    ... )
+    >>> obj = import_artifact("my-artifact.yaml")
     """
     return context_processor.import_context_entity(
         file,
@@ -299,9 +314,7 @@ def load_artifact(file: str) -> Artifact:
 
     Examples
     --------
-    >>> obj = load_artifact(
-    ...     "my-artifact.yaml"
-    ... )
+    >>> obj = load_artifact("my-artifact.yaml")
     """
     return context_processor.load_context_entity(file)
 
@@ -322,11 +335,7 @@ def update_artifact(entity: Artifact) -> Artifact:
 
     Examples
     --------
-    >>> obj = (
-    ...     update_artifact(
-    ...         obj
-    ...     )
-    ... )
+    >>> obj = update_artifact(obj)
     """
     return context_processor.update_context_entity(
         project=entity.project,
@@ -342,7 +351,6 @@ def delete_artifact(
     entity_id: str | None = None,
     delete_all_versions: bool = False,
     cascade: bool = True,
-    **kwargs,
 ) -> dict:
     """
     Delete object from backend.
@@ -356,11 +364,10 @@ def delete_artifact(
     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
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -370,9 +377,7 @@ def delete_artifact(
     Examples
     --------
     If delete_all_versions is False:
-    >>> delete_artifact(
-    ...     "store://my-artifact-key"
-    ... )
+    >>> delete_artifact("store://my-artifact-key")
 
     Otherwise:
     >>> delete_artifact("my-artifact-name",
@@ -386,5 +391,4 @@ def delete_artifact(
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
         cascade=cascade,
-        **kwargs,
     )