digitalhub 0.11.0b7__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/entities/_processors/base.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -16,11 +20,12 @@ if typing.TYPE_CHECKING:
 
 class BaseEntityOperationsProcessor:
     """
-    Processor for Base Entity operations.
+    Processor for base entity operations.
 
-    This object interacts with the context, check the category of the object,
-    and then calls the appropriate method to perform the requested operation.
-    Operations can be CRUD, search, list, etc.
+    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.
     """
 
     ##############################
@@ -35,23 +40,26 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> dict:
         """
-        Create object in backend.
+        Create a base entity in the backend.
+
+        Builds the appropriate API endpoint and sends a create request
+        to the backend for base-level entities.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for the API call.
         entity_type : str
-            Entity type.
+            The type of entity to create (e.g., 'project').
         entity_dict : dict
-            Object instance.
+            The entity data dictionary to create.
         **kwargs : dict
-            Parameters to pass to the API call.
+            Additional parameters to pass to the API call.
 
         Returns
         -------
         dict
-            Object instance.
+            The created entity data returned from the backend.
         """
         api = client.build_api(
             ApiCategories.BASE.value,
@@ -66,19 +74,25 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> Project:
         """
-        Create object in backend.
+        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
-            Object instance.
+        _entity : Project, optional
+            An existing project entity object to create. If None,
+            a new entity will be built from kwargs.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Parameters for entity creation, including 'local' flag
+            and entity-specific parameters.
 
         Returns
         -------
         Project
-            Object instance.
+            The created project entity with backend data populated.
         """
         if _entity is not None:
             client = _entity._client
@@ -98,23 +112,26 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> dict:
         """
-        Read object from backend.
+        Read a base entity from the backend.
+
+        Builds the appropriate API endpoint and sends a read request
+        to retrieve entity data from the backend.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for the API call.
         entity_type : str
-            Entity type.
+            The type of entity to read (e.g., 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the entity to read.
         **kwargs : dict
-            Parameters to pass to the API call.
+            Additional parameters to pass to the API call.
 
         Returns
         -------
         dict
-            Object instance.
+            The entity data retrieved from the backend.
         """
         api = client.build_api(
             ApiCategories.BASE.value,
@@ -131,21 +148,25 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> Project:
         """
-        Read object from backend.
+        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
-            Entity type.
+            The type of entity to read (typically 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the project to read.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Additional parameters including 'local' flag and
+            API call parameters.
 
         Returns
         -------
         Project
-            Object instance.
+            The project entity object populated with backend data.
         """
         client = get_client(kwargs.pop("local", False))
         obj = self._read_base_entity(client, entity_type, entity_name, **kwargs)
@@ -158,19 +179,28 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> Project:
         """
-        Import object from a YAML file and create a new object into the backend.
+        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 YAML file.
+            Path to the YAML file containing project configuration.
         **kwargs : dict
-            Additional keyword arguments.
+            Additional parameters including 'local' flag.
 
         Returns
         -------
         Project
-            Object instance.
+            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)
@@ -194,19 +224,23 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> Project:
         """
-        Load object from a YAML file and update an existing object into the backend.
+        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 YAML file.
+            Path to the YAML file containing project configuration.
         **kwargs : dict
-            Additional keyword arguments.
+            Additional parameters including 'local' flag.
 
         Returns
         -------
         Project
-            Object instance.
+            The loaded and updated project entity.
         """
         client = get_client(kwargs.pop("local", False))
         obj: dict = read_yaml(file)
@@ -230,21 +264,25 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> list[dict]:
         """
-        List objects from backend.
+        List base entities from the backend.
+
+        Builds the appropriate API endpoint and sends a list request
+        to retrieve multiple entities from the backend.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for the API call.
         entity_type : str
-            Entity type.
+            The type of entities to list (e.g., 'project').
         **kwargs : dict
-            Parameters to pass to the API call.
+            Additional parameters to pass to the API call for filtering
+            or pagination.
 
         Returns
         -------
         list[dict]
-            List of objects.
+            List of entity data dictionaries from the backend.
         """
         api = client.build_api(
             ApiCategories.BASE.value,
@@ -259,19 +297,23 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> list[Project]:
         """
-        List objects from backend.
+        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
-            Entity type.
+            The type of entities to list (typically 'project').
         **kwargs : dict
-            Parameters to pass to API call.
+            Additional parameters including 'local' flag and
+            API call parameters for filtering or pagination.
 
         Returns
         -------
         list[Project]
-            List of objects.
+            List of project entity objects.
         """
         client = get_client(kwargs.pop("local", False))
         objs = self._list_base_entities(client, entity_type, **kwargs)
@@ -291,25 +333,28 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> dict:
         """
-        Update object method.
+        Update a base entity in the backend.
+
+        Builds the appropriate API endpoint and sends an update request
+        to modify an existing entity in the backend.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for the API call.
         entity_type : str
-            Entity type.
+            The type of entity to update (e.g., 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the entity to update.
         entity_dict : dict
-            Object instance.
+            The updated entity data dictionary.
         **kwargs : dict
-            Parameters to pass to the API call.
+            Additional parameters to pass to the API call.
 
         Returns
         -------
         dict
-            Object instance.
+            The updated entity data returned from the backend.
         """
         api = client.build_api(
             ApiCategories.BASE.value,
@@ -327,23 +372,27 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> Project:
         """
-        Update object method.
+        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
-            Entity type.
+            The type of entity to update (typically 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the project to update.
         entity_dict : dict
-            Object instance.
+            The updated project data dictionary.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Additional parameters including 'local' flag and
+            API call parameters.
 
         Returns
         -------
         Project
-            Object instance.
+            The updated project entity object.
         """
         client = get_client(kwargs.pop("local", False))
         obj = self._update_base_entity(client, entity_type, entity_name, entity_dict, **kwargs)
@@ -358,23 +407,27 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> dict:
         """
-        Delete object method.
+        Delete a base entity from the backend.
+
+        Builds the appropriate API endpoint and parameters, then sends
+        a delete request to remove the entity from the backend.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for the API call.
         entity_type : str
-            Entity type.
+            The type of entity to delete (e.g., 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the entity to delete.
         **kwargs : dict
-            Parameters to pass to the API call.
+            Additional parameters to pass to the API call, such as
+            cascade deletion options.
 
         Returns
         -------
         dict
-            Response from backend.
+            Response data from the backend delete operation.
         """
         kwargs = client.build_parameters(
             ApiCategories.BASE.value,
@@ -396,21 +449,25 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> dict:
         """
-        Delete object method.
+        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
-            Entity type.
+            The type of entity to delete (typically 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the project to delete.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Additional parameters including 'local' flag, 'clean_context'
+            flag (default True), and API call parameters.
 
         Returns
         -------
         dict
-            Response from backend.
+            Response data from the backend delete operation.
         """
         if kwargs.pop("clean_context", True):
             delete_context(entity_name)
@@ -432,19 +489,22 @@ class BaseEntityOperationsProcessor:
         entity_id: str,
     ) -> str:
         """
-        Build object key.
+        Build a storage key for a base entity.
+
+        Creates a standardized key string that can be used to identify
+        and store the entity in various contexts.
 
         Parameters
         ----------
         client : Client
-            Client instance.
+            The client instance to use for key building.
         entity_id : str
-            Entity ID.
+            The unique identifier of the entity.
 
         Returns
         -------
         str
-            Object key.
+            The constructed entity key string.
         """
         return client.build_key(ApiCategories.BASE.value, entity_id)
 
@@ -454,19 +514,22 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> str:
         """
-        Build object key.
+        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
-            Entity ID.
+            The unique identifier of the project entity.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Additional parameters including 'local' flag.
 
         Returns
         -------
         str
-            Object key.
+            The constructed project entity key string.
         """
         client = get_client(kwargs.pop("local", False))
         return self._build_base_entity_key(client, entity_id)
@@ -478,20 +541,32 @@ class BaseEntityOperationsProcessor:
         **kwargs,
     ) -> None:
         """
-        Share object method.
+        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
-            Entity type.
+            The type of entity to share (typically 'project').
         entity_name : str
-            Entity name.
+            The name identifier of the project to share.
         **kwargs : dict
-            Parameters to pass to entity builder.
+            Additional parameters including:
+            - 'user': username to share with/unshare from
+            - 'unshare': boolean flag for unsharing (default False)
+            - 'local': boolean flag for local backend
 
         Returns
         -------
         None
+
+        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(