digitalhub 0.14.0b1__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/_processors/utils.py

@@ -9,7 +9,7 @@ import typing
 from digitalhub.context.api import get_context
 from digitalhub.entities._commons.enums import ApiCategories, BackendOperations, EntityTypes
 from digitalhub.entities._commons.utils import get_project_from_key, is_valid_key, parse_entity_key
-from digitalhub.factory.factory import factory
+from digitalhub.factory.entity import entity_factory
 from digitalhub.stores.client.api import get_client
 from digitalhub.utils.exceptions import ContextError, EntityError, EntityNotExistsError
 
@@ -161,7 +161,7 @@ def get_context_from_remote(
     try:
         client = get_client()
         obj = _read_base_entity(client, EntityTypes.PROJECT.value, project)
-        factory.build_entity_from_dict(obj)
+        entity_factory.build_entity_from_dict(obj)
         return get_context(project)
     except EntityNotExistsError:
         raise ContextError(f"Project '{project}' not found.")

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

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
 
@@ -87,6 +87,7 @@ def log_dataitem(
     data: Any | None = None,
     path: str | None = None,
     file_format: str | None = None,
+    read_df_params: dict | None = None,
     engine: str | None = "pandas",
     **kwargs,
 ) -> Dataitem:
@@ -108,7 +109,9 @@ def log_dataitem(
     path : str
         Destination path of the dataitem. If not provided, it's generated.
     file_format : str
-        Extension of the file.
+        Extension of the file source (parquet, csv, json, xlsx, txt).
+    read_df_params : dict
+        Parameters to pass to the dataframe reader.
     engine : str
         Dataframe engine (pandas, polars, etc.).
     **kwargs : dict
@@ -131,7 +134,7 @@ def log_dataitem(
         cleanup = True
 
     source = eval_source(source, data, kind, name, project)
-    data = eval_data(kind, source, data, file_format, engine)
+    data = eval_data(kind, source, data, file_format, read_df_params, engine)
     kwargs = process_kwargs(
         project,
         name,

digitalhub/entities/dataitem/table/entity.py

@@ -115,13 +115,17 @@ class DataitemTable(Dataitem):
         Write DataFrame as parquet/csv/table into dataitem spec.path.
         keyword arguments will be passed to the DataFrame reader function such as
         pandas's to_csv or to_parquet.
+        Note that by default the index is dropped when writing the dataframe. To
+        keep the index, you can pass index=True as a keyword argument.
+        If the dataitem path is a SQL scheme, the dataframe will be written to the
+        table specified in the path (sql://<database_name>(/<schema_name>)/<table_name>).
 
         Parameters
         ----------
         df : Any
             DataFrame to write.
         extension : str
-            Extension of the file.
+            Extension of the file (supported parquet and csv).
         **kwargs : dict
             Keyword arguments passed to the write_df function.
 
@@ -129,6 +133,25 @@ class DataitemTable(Dataitem):
         -------
         str
             Path to the written dataframe.
+
+        Examples
+        --------
+        >>> import digitalhub as dh
+        >>> import pandas as pd
+        >>>
+        >>> p = dh.get_project("my_project")
+        >>> df = pd.read_df("data/my_data.csv")
+        >>> di = p.new_dataitem(
+        ...     name="my_dataitem",
+        ...     kind="table",
+        ...     path="s3://my-bucket/my-data.parquet",
+        ... )
+        >>> di.write_df(
+        ...     df,
+        ...     extension="parquet",
+        ...     index=True,
+        ... )
+        's3://my-bucket/my-data.parquet'
         """
         return get_store(self.spec.path).write_df(
             df,

digitalhub/entities/dataitem/utils.py

@@ -89,6 +89,7 @@ def eval_data(
     source: SourcesOrListOfSources,
     data: Any | None = None,
     file_format: str | None = None,
+    read_df_params: dict | None = None,
     engine: str | None = None,
 ) -> Any:
     """
@@ -121,10 +122,13 @@ def eval_data(
     """
     if kind == EntityKinds.DATAITEM_TABLE.value:
         if data is None:
+            if read_df_params is None:
+                read_df_params = {}
             return get_store(source).read_df(
                 source,
                 file_format=file_format,
                 engine=engine,
+                **read_df_params,
             )
     return data
 

digitalhub/entities/function/_base/entity.py

@@ -9,7 +9,7 @@ from concurrent.futures import ThreadPoolExecutor
 
 from digitalhub.entities._base.executable.entity import ExecutableEntity
 from digitalhub.entities._commons.enums import EntityTypes, Relationship
-from digitalhub.factory.factory import factory
+from digitalhub.factory.entity import entity_factory
 from digitalhub.utils.exceptions import BackendError
 
 if typing.TYPE_CHECKING:
@@ -76,8 +76,8 @@ class Function(ExecutableEntity):
             Run instance.
         """
         # Get task and run kind
-        task_kind = factory.get_task_kind_from_action(self.kind, action)
-        run_kind = factory.get_run_kind_from_action(self.kind, action)
+        task_kind = entity_factory.get_task_kind_from_action(self.kind, action)
+        run_kind = entity_factory.get_run_kind_from_action(self.kind, action)
 
         # Create or update new task
         task = self._get_or_create_task(task_kind)

digitalhub/entities/function/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.function._base.entity import Function