digitalhub 0.13.0b3__py3-none-any.whl → 0.14.9__py3-none-any.whl

digitalhub/entities/_constructors/_resources.py

@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+ANIMALS = [
+    "ant",
+    "bear",
+    "bee",
+    "bison",
+    "cat",
+    "cheetah",
+    "cougar",
+    "crane",
+    "deer",
+    "dolphin",
+    "duck",
+    "eagle",
+    "falcon",
+    "finch",
+    "fox",
+    "frog",
+    "gecko",
+    "hawk",
+    "heron",
+    "horse",
+    "jaguar",
+    "koala",
+    "leopard",
+    "lion",
+    "llama",
+    "lynx",
+    "mole",
+    "moose",
+    "otter",
+    "owl",
+    "panda",
+    "penguin",
+    "rabbit",
+    "robin",
+    "seal",
+    "shark",
+    "sparrow",
+    "tiger",
+    "tortoise",
+    "wolf",
+]
+
+ADJECTIVES = [
+    "able",
+    "agile",
+    "alert",
+    "alpha",
+    "amber",
+    "apex",
+    "arctic",
+    "atomic",
+    "balanced",
+    "basic",
+    "bold",
+    "bright",
+    "brisk",
+    "calm",
+    "clever",
+    "clear",
+    "cloudy",
+    "crisp",
+    "curious",
+    "cyber",
+    "daring",
+    "deep",
+    "delta",
+    "digital",
+    "dynamic",
+    "early",
+    "easy",
+    "electric",
+    "epic",
+    "fast",
+    "firm",
+    "fluent",
+    "focused",
+    "fresh",
+    "friendly",
+    "full",
+    "future",
+    "gentle",
+    "global",
+    "golden",
+    "grand",
+    "great",
+    "green",
+    "happy",
+    "high",
+    "honest",
+    "hyper",
+    "ideal",
+    "infinite",
+    "inner",
+    "instant",
+    "keen",
+    "kind",
+    "known",
+    "large",
+    "light",
+    "linear",
+    "logical",
+    "lucky",
+    "lunar",
+    "magic",
+    "major",
+    "mega",
+    "mild",
+    "modern",
+    "neat",
+    "noble",
+    "open",
+    "outer",
+    "peak",
+    "perfect",
+    "plain",
+    "prime",
+    "pure",
+    "quick",
+    "quiet",
+    "rapid",
+    "rare",
+    "ready",
+    "real",
+    "red",
+    "right",
+    "safe",
+    "sharp",
+    "silent",
+    "simple",
+    "smart",
+    "solid",
+    "solar",
+    "speedy",
+    "stable",
+    "steady",
+    "stellar",
+    "strong",
+    "swift",
+    "true",
+    "ultra",
+    "vast",
+    "vital",
+    "wise",
+]

digitalhub/entities/{_base/entity/_constructors → _constructors}/name.py

@@ -4,8 +4,12 @@
 
 from __future__ import annotations
 
+import random
+
 from pydantic import BaseModel, Field
 
+from digitalhub.entities._constructors._resources import ADJECTIVES, ANIMALS
+
 NAME_REGEX = r"^[a-zA-Z0-9._+-]+$"
 
 
@@ -33,3 +37,17 @@ def build_name(name: str) -> str:
     """
     NameValidator(name=name)
     return name
+
+
+def random_name() -> str:
+    """
+    Generate a random name.
+
+    Returns
+    -------
+    str
+        The random name.
+    """
+    adjective = random.choice(ADJECTIVES)
+    animal = random.choice(ANIMALS)
+    return f"{adjective}-{animal}"

digitalhub/entities/_processors/base/crud.py

@@ -0,0 +1,381 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+
+from digitalhub.context.api import delete_context
+from digitalhub.factory.entity import entity_factory
+from digitalhub.stores.client.builder import get_client
+from digitalhub.stores.client.enums import ApiCategories, BackendOperations
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities.project._base.entity import Project
+    from digitalhub.stores.client.client import Client
+
+
+class BaseEntityCRUDProcessor:
+    """
+    Processor for core CRUD operations on base entities.
+
+    Handles creation, reading, updating, deletion, and listing of
+    base-level entities (primarily projects) within the backend.
+    """
+
+    def _create_base_entity(
+        self,
+        client: Client,
+        entity_type: str,
+        entity_dict: dict,
+        **kwargs,
+    ) -> dict:
+        """
+        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
+            The client instance to use for the API call.
+        entity_type : str
+            The type of entity to create (e.g., 'project').
+        entity_dict : dict
+            The entity data dictionary to create.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            The created entity data returned from the backend.
+        """
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.CREATE.value,
+            entity_type=entity_type,
+        )
+        return client.create_object(api, entity_dict, **kwargs)
+
+    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.
+
+        Parameters
+        ----------
+        _entity : Project
+            An existing project entity object to create. If None,
+            a new entity will be built from kwargs.
+        **kwargs : dict
+            Parameters for entity creation.
+
+        Returns
+        -------
+        Project
+            The created project entity with backend data populated.
+        """
+        if _entity is not None:
+            client = _entity._client
+            obj = _entity
+        else:
+            client = get_client()
+            obj = entity_factory.build_entity_from_params(**kwargs)
+        ent = self._create_base_entity(client, obj.ENTITY_TYPE, obj.to_dict())
+        return entity_factory.build_entity_from_dict(ent)
+
+    def _read_base_entity(
+        self,
+        client: Client,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> dict:
+        """
+        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
+            The client instance to use for the API call.
+        entity_type : str
+            The type of entity to read (e.g., 'project').
+        entity_name : str
+            The name identifier of the entity to read.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            The entity data retrieved from the backend.
+        """
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.READ.value,
+            entity_type=entity_type,
+            entity_name=entity_name,
+        )
+        return client.read_object(api, **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.
+        """
+        client = get_client()
+        obj = self._read_base_entity(client, entity_type, entity_name, **kwargs)
+        return entity_factory.build_entity_from_dict(obj)
+
+    def _list_base_entities(
+        self,
+        client: Client,
+        entity_type: str,
+        **kwargs,
+    ) -> list[dict]:
+        """
+        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
+            The client instance to use for the API call.
+        entity_type : str
+            The type of entities to list (e.g., 'project').
+        **kwargs : dict
+            Additional parameters to pass to the API call for filtering
+            or pagination.
+
+        Returns
+        -------
+        list[dict]
+            List of entity data dictionaries from the backend.
+        """
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.LIST.value,
+            entity_type=entity_type,
+        )
+        return client.list_objects(api, **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.
+
+        Returns
+        -------
+        list[Project]
+            List of project entity objects.
+        """
+        client = get_client()
+        objs = self._list_base_entities(client, entity_type, **kwargs)
+        entities = []
+        for obj in objs:
+            ent = entity_factory.build_entity_from_dict(obj)
+            entities.append(ent)
+        return entities
+
+    def _update_base_entity(
+        self,
+        client: Client,
+        entity_type: str,
+        entity_name: str,
+        entity_dict: dict,
+        **kwargs,
+    ) -> dict:
+        """
+        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
+            The client instance to use for the API call.
+        entity_type : str
+            The type of entity to update (e.g., 'project').
+        entity_name : str
+            The name identifier of the entity to update.
+        entity_dict : dict
+            The updated entity data dictionary.
+        **kwargs : dict
+            Additional parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            The updated entity data returned from the backend.
+        """
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.UPDATE.value,
+            entity_type=entity_type,
+            entity_name=entity_name,
+        )
+        return client.update_object(api, entity_dict, **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.
+
+        Returns
+        -------
+        Project
+            The updated project entity object.
+        """
+        client = get_client()
+        obj = self._update_base_entity(client, entity_type, entity_name, entity_dict, **kwargs)
+        return entity_factory.build_entity_from_dict(obj)
+
+    def _delete_base_entity(
+        self,
+        client: Client,
+        entity_type: str,
+        entity_name: str,
+        **kwargs,
+    ) -> dict:
+        """
+        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
+            The client instance to use for the API call.
+        entity_type : str
+            The type of entity to delete (e.g., 'project').
+        entity_name : str
+            The name identifier of the entity to delete.
+        **kwargs : dict
+            Additional parameters to pass to the API call, such as
+            cascade deletion options.
+
+        Returns
+        -------
+        dict
+            Response data from the backend delete operation.
+        """
+        kwargs = client.build_parameters(
+            ApiCategories.BASE.value,
+            BackendOperations.DELETE.value,
+            **kwargs,
+        )
+        api = client.build_api(
+            ApiCategories.BASE.value,
+            BackendOperations.DELETE.value,
+            entity_type=entity_type,
+            entity_name=entity_name,
+        )
+        return client.delete_object(api, **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.
+
+        Parameters
+        ----------
+        crud_processor : BaseEntityCRUDProcessor
+            The CRUD processor instance for entity operations.
+        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 'clean_context'.
+
+        Returns
+        -------
+        dict
+            Response data from the backend delete operation.
+        """
+        if kwargs.pop("clean_context", True):
+            delete_context(entity_name)
+        client = get_client()
+        return self._delete_base_entity(
+            client,
+            entity_type,
+            entity_name,
+            **kwargs,
+        )

digitalhub/entities/_processors/base/import_export.py

@@ -0,0 +1,118 @@
+# 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.utils.exceptions import EntityAlreadyExistsError, EntityError, EntityNotExistsError
+from digitalhub.utils.io_utils import read_yaml
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._processors.base.crud import BaseEntityCRUDProcessor
+    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: BaseEntityCRUDProcessor,
+        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.
+        """
+        obj: dict = read_yaml(file)
+        obj["status"] = {}
+        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: BaseEntityCRUDProcessor,
+        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.
+        """
+        obj: dict = read_yaml(file)
+        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