digitalhub 0.14.0b1__py3-none-any.whl → 0.14.0b3__py3-none-any.whl

digitalhub/entities/_processors/base/import_export.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from warnings import warn
+
+from digitalhub.factory.entity import entity_factory
+from digitalhub.stores.client.api import get_client
+from digitalhub.utils.exceptions import EntityAlreadyExistsError, EntityError, EntityNotExistsError
+from digitalhub.utils.io_utils import read_yaml
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities.project._base.entity import Project
+
+
+class BaseEntityImportExportProcessor:
+    """
+    Processor for import and export operations on base entities.
+
+    Handles loading entities from YAML files and importing/exporting
+    entity configurations between local files and the backend.
+    """
+
+    def import_project_entity(
+        self,
+        crud_processor,
+        file: str,
+        **kwargs,
+    ) -> Project:
+        """
+        Import a project entity from a YAML file and create it in the backend.
+
+        Reads project configuration from a YAML file, creates a new project
+        entity in the backend, and imports any related entities defined
+        in the file. Raises an error if the project already exists.
+
+        Parameters
+        ----------
+        crud_processor : BaseEntityCRUDProcessor
+            The CRUD processor instance for entity operations.
+        file : str
+            Path to the YAML file containing project configuration.
+        **kwargs : dict
+            Additional parameters including 'local' and 'reset_id' flags.
+
+        Returns
+        -------
+        Project
+            The imported and created project entity.
+
+        Raises
+        ------
+        EntityError
+            If the project already exists in the backend.
+        """
+        client = get_client(kwargs.pop("local", False))
+        obj: dict = read_yaml(file)
+        obj["status"] = {}
+        obj["local"] = client.is_local()
+        ent: Project = entity_factory.build_entity_from_dict(obj)
+        reset_id = kwargs.pop("reset_id", False)
+
+        try:
+            crud_processor._create_base_entity(ent._client, ent.ENTITY_TYPE, ent.to_dict())
+        except EntityAlreadyExistsError:
+            msg = f"Entity {ent.name} already exists."
+            if reset_id:
+                ent._import_entities(obj, reset_id=reset_id)
+                warn(f"{msg} Other entities ids have been imported.")
+                ent.refresh()
+                return ent
+            raise EntityError(f"{msg} If you want to update it, use load instead.")
+
+        # Import related entities
+        ent._import_entities(obj, reset_id=reset_id)
+        ent.refresh()
+        return ent
+
+    def load_project_entity(
+        self,
+        crud_processor,
+        file: str,
+        **kwargs,
+    ) -> Project:
+        """
+        Load a project entity from a YAML file and update it in the backend.
+
+        Reads project configuration from a YAML file and updates an existing
+        project in the backend. If the project doesn't exist, it creates a
+        new one. Also loads any related entities defined in the file.
+
+        Parameters
+        ----------
+        crud_processor : BaseEntityCRUDProcessor
+            The CRUD processor instance for entity operations.
+        file : str
+            Path to the YAML file containing project configuration.
+        **kwargs : dict
+            Additional parameters including 'local' flag.
+
+        Returns
+        -------
+        Project
+            The loaded and updated project entity.
+        """
+        client = get_client(kwargs.pop("local", False))
+        obj: dict = read_yaml(file)
+        obj["local"] = client.is_local()
+        ent: Project = entity_factory.build_entity_from_dict(obj)
+
+        try:
+            crud_processor._update_base_entity(ent._client, ent.ENTITY_TYPE, ent.name, ent.to_dict())
+        except EntityNotExistsError:
+            crud_processor._create_base_entity(ent._client, ent.ENTITY_TYPE, ent.to_dict())
+
+        # Load related entities
+        ent._load_entities(obj)
+        ent.refresh()
+        return ent

digitalhub/entities/_processors/base/processor.py

@@ -0,0 +1,302 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._processors.base.crud import BaseEntityCRUDProcessor
+from digitalhub.entities._processors.base.import_export import BaseEntityImportExportProcessor
+from digitalhub.entities._processors.base.special_ops import BaseEntitySpecialOpsProcessor
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities.project._base.entity import Project
+
+
+class BaseEntityOperationsProcessor:
+    """
+    Processor for base entity operations.
+
+    This class handles CRUD operations and other entity management tasks
+    for base-level entities (primarily projects). It interacts with the
+    client layer to perform backend operations and manages entity lifecycle
+    including creation, reading, updating, deletion, and sharing.
+
+    Uses composition with specialized processors for different operation types.
+    """
+
+    def __init__(self):
+        self.crud_processor = BaseEntityCRUDProcessor()
+        self.import_export_processor = BaseEntityImportExportProcessor()
+        self.special_ops_processor = BaseEntitySpecialOpsProcessor()
+
+    ##############################
+    # CRUD base entity
+    ##############################
+
+    def create_project_entity(
+        self,
+        _entity: Project | None = None,
+        **kwargs,
+    ) -> Project:
+        """
+        Create a project entity in the backend.
+
+        Creates a new project either from an existing entity object or
+        by building one from the provided parameters. Handles both
+        local and remote backend creation.
+
+        Parameters
+        ----------
+        _entity : Project, optional
+            An existing project entity object to create. If None,
+            a new entity will be built from kwargs.
+        **kwargs : dict
+            Parameters for entity creation, including 'local' flag
+            and entity-specific parameters.
+
+        Returns
+        -------
+        Project
+            The created project entity with backend data populated.
+        """
+        return self.crud_processor.create_project_entity(_entity, **kwargs)
+
+    def read_project_entity(
+        self,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> Project:
+        """
+        Read a project entity from the backend.
+
+        Retrieves project data from the backend and constructs a
+        Project entity object with the retrieved data.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entity to read (typically 'project').
+        entity_name : str
+            The name identifier of the project to read.
+        **kwargs : dict
+            Additional parameters including 'local' flag and
+            API call parameters.
+
+        Returns
+        -------
+        Project
+            The project entity object populated with backend data.
+        """
+        return self.crud_processor.read_project_entity(entity_type, entity_name, **kwargs)
+
+    def update_project_entity(
+        self,
+        entity_type: str,
+        entity_name: str,
+        entity_dict: dict,
+        **kwargs,
+    ) -> Project:
+        """
+        Update a project entity in the backend.
+
+        Updates an existing project with new data and returns the
+        updated Project entity object.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entity to update (typically 'project').
+        entity_name : str
+            The name identifier of the project to update.
+        entity_dict : dict
+            The updated project data dictionary.
+        **kwargs : dict
+            Additional parameters including 'local' flag and
+            API call parameters.
+
+        Returns
+        -------
+        Project
+            The updated project entity object.
+        """
+        return self.crud_processor.update_project_entity(entity_type, entity_name, entity_dict, **kwargs)
+
+    def delete_project_entity(
+        self,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> dict:
+        """
+        Delete a project entity from the backend.
+
+        Deletes a project from the backend and optionally cleans up
+        the associated context. Handles both local and remote backends.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entity to delete (typically 'project').
+        entity_name : str
+            The name identifier of the project to delete.
+        **kwargs : dict
+            Additional parameters including 'local' flag, 'clean_context'
+            flag (default True), and API call parameters.
+
+        Returns
+        -------
+        dict
+            Response data from the backend delete operation.
+        """
+        return self.crud_processor.delete_project_entity(entity_type, entity_name, **kwargs)
+
+    def list_project_entities(
+        self,
+        entity_type: str,
+        **kwargs,
+    ) -> list[Project]:
+        """
+        List project entities from the backend.
+
+        Retrieves a list of projects from the backend and converts
+        them to Project entity objects.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entities to list (typically 'project').
+        **kwargs : dict
+            Additional parameters including 'local' flag and
+            API call parameters for filtering or pagination.
+
+        Returns
+        -------
+        list[Project]
+            List of project entity objects.
+        """
+        return self.crud_processor.list_project_entities(entity_type, **kwargs)
+
+    ##############################
+    # Import/Export operations
+    ##############################
+
+    def import_project_entity(
+        self,
+        file: str,
+        **kwargs,
+    ) -> Project:
+        """
+        Import a project entity from a YAML file and create it in the backend.
+
+        Reads project configuration from a YAML file, creates a new project
+        entity in the backend, and imports any related entities defined
+        in the file. Raises an error if the project already exists.
+
+        Parameters
+        ----------
+        file : str
+            Path to the YAML file containing project configuration.
+        **kwargs : dict
+            Additional parameters including 'local' and 'reset_id' flags.
+
+        Returns
+        -------
+        Project
+            The imported and created project entity.
+
+        Raises
+        ------
+        EntityError
+            If the project already exists in the backend.
+        """
+        return self.import_export_processor.import_project_entity(file, **kwargs)
+
+    def load_project_entity(
+        self,
+        file: str,
+        **kwargs,
+    ) -> Project:
+        """
+        Load a project entity from a YAML file and update it in the backend.
+
+        Reads project configuration from a YAML file and updates an existing
+        project in the backend. If the project doesn't exist, it creates a
+        new one. Also loads any related entities defined in the file.
+
+        Parameters
+        ----------
+        file : str
+            Path to the YAML file containing project configuration.
+        **kwargs : dict
+            Additional parameters including 'local' flag.
+
+        Returns
+        -------
+        Project
+            The loaded and updated project entity.
+        """
+        return self.import_export_processor.load_project_entity(file, **kwargs)
+
+    ##############################
+    # Base entity operations
+    ##############################
+
+    def build_project_key(
+        self,
+        entity_id: str,
+        **kwargs,
+    ) -> str:
+        """
+        Build a storage key for a project entity.
+
+        Creates a standardized key string for project identification
+        and storage, handling both local and remote client contexts.
+
+        Parameters
+        ----------
+        entity_id : str
+            The unique identifier of the project entity.
+        **kwargs : dict
+            Additional parameters including 'local' flag.
+
+        Returns
+        -------
+        str
+            The constructed project entity key string.
+        """
+        return self.special_ops_processor.build_project_key(entity_id, **kwargs)
+
+    def share_project_entity(
+        self,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> None:
+        """
+        Share or unshare a project entity with a user.
+
+        Manages project access permissions by sharing the project with
+        a specified user or removing user access. Handles both sharing
+        and unsharing operations based on the 'unshare' parameter.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entity to share (typically 'project').
+        entity_name : str
+            The name identifier of the project to share.
+        **kwargs : dict
+            Additional parameters including:
+            - 'user': username to share with/unshare from
+            - 'unshare': boolean flag for unsharing (default False)
+            - 'local': boolean flag for local backend
+
+        Raises
+        ------
+        ValueError
+            If trying to unshare from a user who doesn't have access.
+        """
+        return self.special_ops_processor.share_project_entity(entity_type, entity_name, **kwargs)

digitalhub/entities/_processors/base/special_ops.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._commons.enums import ApiCategories, BackendOperations
+from digitalhub.stores.client.api import get_client
+
+if typing.TYPE_CHECKING:
+    pass
+
+
+class BaseEntitySpecialOpsProcessor:
+    """
+    Processor for specialized base entity operations.
+
+    Handles backend operations like sharing, key building, and other
+    specialized functionality for base-level entities.
+    """
+
+    def build_project_key(
+        self,
+        entity_id: str,
+        **kwargs,
+    ) -> str:
+        """
+        Build a storage key for a project entity.
+
+        Creates a standardized key string for project identification
+        and storage, handling both local and remote client contexts.
+
+        Parameters
+        ----------
+        entity_id : str
+            The unique identifier of the project entity.
+        **kwargs : dict
+            Additional parameters including 'local' flag.
+
+        Returns
+        -------
+        str
+            The constructed project entity key string.
+        """
+        client = get_client(kwargs.pop("local", False))
+        return client.build_key(ApiCategories.BASE.value, entity_id)
+
+    def share_project_entity(
+        self,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> None:
+        """
+        Share or unshare a project entity with a user.
+
+        Manages project access permissions by sharing the project with
+        a specified user or removing user access. Handles both sharing
+        and unsharing operations based on the 'unshare' parameter.
+
+        Parameters
+        ----------
+        entity_type : str
+            The type of entity to share (typically 'project').
+        entity_name : str
+            The name identifier of the project to share.
+        **kwargs : dict
+            Additional parameters including:
+            - 'user': username to share with/unshare from
+            - 'unshare': boolean flag for unsharing (default False)
+            - 'local': boolean flag for local backend
+
+        Raises
+        ------
+        ValueError
+            If trying to unshare from a user who doesn't have access.
+        """
+        client = get_client(kwargs.pop("local", False))
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.SHARE.value,
+            entity_type=entity_type,
+            entity_name=entity_name,
+        )
+
+        user = kwargs.pop("user", None)
+        if unshare := kwargs.pop("unshare", False):
+            users = client.read_object(api, **kwargs)
+            for u in users:
+                if u["user"] == user:
+                    kwargs["id"] = u["id"]
+                break
+            else:
+                raise ValueError(f"User '{user}' does not have access to project.")
+
+        kwargs = client.build_parameters(
+            ApiCategories.BASE.value,
+            BackendOperations.SHARE.value,
+            unshare=unshare,
+            user=user,
+            **kwargs,
+        )
+        if unshare:
+            client.delete_object(api, **kwargs)
+            return
+        client.create_object(api, obj={}, **kwargs)

digitalhub/entities/_processors/context/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0