digitalhub 0.14.0b2__py3-none-any.whl → 0.14.0b3__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._commons.enums import ApiCategories, BackendOperations
+from digitalhub.entities._processors.utils import get_context_from_project
+
+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/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
@@ -156,9 +156,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"
@@ -199,9 +197,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"
@@ -233,9 +229,7 @@ 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,
@@ -271,9 +265,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 +291,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 +312,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,
@@ -370,9 +356,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",

digitalhub/entities/dataitem/crud.py

@@ -8,7 +8,7 @@ import typing
 from typing import Any
 
 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.dataitem.utils import clean_tmp_path, eval_data, eval_source, post_process, process_kwargs
 from digitalhub.utils.types import SourcesOrListOfSources
 
@@ -185,9 +185,7 @@ def get_dataitem(
     Examples
     --------
     Using entity key:
-    >>> obj = get_dataitem(
-    ...     "store://my-dataitem-key"
-    ... )
+    >>> obj = get_dataitem("store://my-dataitem-key")
 
     Using entity name:
     >>> obj = get_dataitem("my-dataitem-name"
@@ -228,9 +226,7 @@ def get_dataitem_versions(
     Examples
     --------
     Using entity key:
-    >>> objs = get_dataitem_versions(
-    ...     "store://my-dataitem-key"
-    ... )
+    >>> objs = get_dataitem_versions("store://my-dataitem-key")
 
     Using entity name:
     >>> objs = get_dataitem_versions("my-dataitem-name",
@@ -262,9 +258,7 @@ def list_dataitems(project: str, **kwargs) -> list[Dataitem]:
 
     Examples
     --------
-    >>> objs = list_dataitems(
-    ...     project="my-project"
-    ... )
+    >>> objs = list_dataitems(project="my-project")
     """
     return context_processor.list_context_entities(
         project=project,
@@ -300,9 +294,7 @@ def import_dataitem(
 
     Examples
     --------
-    >>> obj = import_dataitem(
-    ...     "my-dataitem.yaml"
-    ... )
+    >>> obj = import_dataitem("my-dataitem.yaml")
     """
     return context_processor.import_context_entity(
         file,
@@ -328,9 +320,7 @@ def load_dataitem(file: str) -> Dataitem:
 
     Examples
     --------
-    >>> obj = load_dataitem(
-    ...     "my-dataitem.yaml"
-    ... )
+    >>> obj = load_dataitem("my-dataitem.yaml")
     """
     return context_processor.load_context_entity(file)
 
@@ -351,11 +341,7 @@ def update_dataitem(entity: Dataitem) -> Dataitem:
 
     Examples
     --------
-    >>> obj = (
-    ...     update_dataitem(
-    ...         obj
-    ...     )
-    ... )
+    >>> obj = update_dataitem(obj)
     """
     return context_processor.update_context_entity(
         project=entity.project,
@@ -399,9 +385,7 @@ def delete_dataitem(
     Examples
     --------
     If delete_all_versions is False:
-    >>> obj = delete_dataitem(
-    ...     "store://my-dataitem-key"
-    ... )
+    >>> obj = delete_dataitem("store://my-dataitem-key")
 
     Otherwise:
     >>> obj = delete_dataitem("my-dataitem-name",

digitalhub/entities/dataitem/table/entity.py

@@ -139,12 +139,8 @@ class DataitemTable(Dataitem):
         >>> import digitalhub as dh
         >>> import pandas as pd
         >>>
-        >>> p = dh.get_project(
-        ...     "my_project"
-        ... )
-        >>> df = pd.read_df(
-        ...     "data/my_data.csv"
-        ... )
+        >>> p = dh.get_project("my_project")
+        >>> df = pd.read_df("data/my_data.csv")
         >>> di = p.new_dataitem(
         ...     name="my_dataitem",
         ...     kind="table",