digitalhub 0.8.0b0__py3-none-any.whl → 0.8.0b2__py3-none-any.whl

digitalhub/entities/_base/entity/base.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import typing
+from abc import ABCMeta, abstractmethod
+
+from digitalhub.entities._base.base import ModelObj
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.metadata import Metadata
+    from digitalhub.entities._base.spec.base import Spec
+    from digitalhub.entities._base.status.base import Status
+
+
+class Entity(ModelObj, metaclass=ABCMeta):
+    """
+    Abstract class for entities.
+
+    An entity is a collection of metadata, specification and status
+    representing a variety of objects handled by Digitalhub.
+    """
+
+    # Entity type
+    # Need to be set in subclasses
+    ENTITY_TYPE: str
+
+    # Attributes to render as dict. Need to be expanded in subclasses.
+    _obj_attr = ["kind", "metadata", "spec", "status", "user", "key"]
+
+    def __init__(
+        self,
+        kind: str,
+        metadata: Metadata,
+        spec: Spec,
+        status: Status,
+        user: str | None = None,
+    ) -> None:
+        self.kind = kind
+        self.metadata = metadata
+        self.spec = spec
+        self.status = status
+        self.user = user
+
+        # Need to be set in subclasses
+        self.key: str
+
+    @abstractmethod
+    def save(self, update: bool = False) -> Entity:
+        """
+        Abstract save method.
+        """
+
+    @abstractmethod
+    def refresh(self) -> Entity:
+        """
+        Abstract refresh method.
+        """
+
+    def _update_attributes(self, obj: dict) -> None:
+        """
+        Update attributes.
+
+        Parameters
+        ----------
+        obj : dict
+            Mapping representation of object.
+
+        Returns
+        -------
+        None
+        """
+        new_obj = self.from_dict(obj)
+        self.metadata = new_obj.metadata
+        self.spec = new_obj.spec
+        self.status = new_obj.status
+        self.user = new_obj.user
+
+    @abstractmethod
+    def export(self, filename: str | None = None) -> str:
+        """
+        Abstract export method.
+        """
+
+    def to_dict(self) -> dict:
+        """
+        Override default to_dict method to add the possibility to exclude
+        some attributes. This requires to set a list of _obj_attr
+        attributes in the subclass.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the attributes of the entity instance.
+        """
+        return {k: v for k, v in super().to_dict().items() if k in self._obj_attr}
+
+    @classmethod
+    def from_dict(cls, obj: dict, validate: bool = True) -> Entity:
+        """
+        Create a new object from dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            Dictionary to create object from.
+        validate : bool
+            Flag to indicate if arguments validation against a pydantic schema must be ignored.
+
+        Returns
+        -------
+        Self
+            Self instance.
+        """
+        parsed_dict = cls._parse_dict(obj, validate=validate)
+        return cls(**parsed_dict)
+
+    @staticmethod
+    @abstractmethod
+    def _parse_dict(obj: dict, validate: bool = True) -> dict:
+        """
+        Abstract method to parse dictionary.
+        """
+
+    def __repr__(self) -> str:
+        """
+        Return string representation of the entity object.
+
+        Returns
+        -------
+        str
+            A string representing the entity instance.
+        """
+        return str(self.to_dict())

digitalhub/entities/_base/entity/context.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.context.builder import get_context
+from digitalhub.entities._base.crud import create_entity_api_ctx, read_entity_api_ctx, update_entity_api_ctx
+from digitalhub.entities._base.entity.base import Entity
+from digitalhub.utils.generic_utils import get_timestamp
+
+if typing.TYPE_CHECKING:
+    from digitalhub.context.context import Context
+    from digitalhub.entities._base.metadata import Metadata
+    from digitalhub.entities._base.spec.base import Spec
+    from digitalhub.entities._base.status.base import Status
+
+
+class ContextEntity(Entity):
+    def __init__(
+        self,
+        project: str,
+        kind: str,
+        metadata: Metadata,
+        spec: Spec,
+        status: Status,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(kind, metadata, spec, status, user)
+        self.project = project
+        self._obj_attr.extend(["project"])
+
+    ##############################
+    #  Save / Refresh / Export
+    ##############################
+
+    def save(self, update: bool = False) -> ContextEntity:
+        """
+        Save or update the entity into the backend.
+
+        Parameters
+        ----------
+        update : bool
+            Flag to indicate update.
+
+        Returns
+        -------
+        ContextEntity
+            Entity saved.
+        """
+        obj = self.to_dict()
+        if not update:
+            return self._save(obj)
+        return self._update(obj)
+
+    def _save(self, obj: dict) -> ContextEntity:
+        """
+        Save entity into backend.
+
+        Parameters
+        ----------
+        obj : dict
+            Object instance as dictionary.
+
+        Returns
+        -------
+        ContextEntity
+            Entity saved.
+        """
+        new_obj = create_entity_api_ctx(self.project, self.ENTITY_TYPE, obj)
+        self._update_attributes(new_obj)
+        return self
+
+    def _update(self, obj: dict) -> ContextEntity:
+        """
+        Update entity in backend.
+
+        Parameters
+        ----------
+        obj : dict
+            Object instance as dictionary.
+
+        Returns
+        -------
+        ContextEntity
+            Entity updated.
+        """
+        if self._context().local:
+            self.metadata.updated = obj["metadata"]["updated"] = get_timestamp()
+        new_obj = update_entity_api_ctx(self.project, self.ENTITY_TYPE, self.id, obj)
+        self._update_attributes(new_obj)
+        return self
+
+    def refresh(self) -> ContextEntity:
+        """
+        Refresh object from backend.
+
+        Returns
+        -------
+        ContextEntity
+            Entity refreshed.
+        """
+        new_obj = read_entity_api_ctx(self.key)
+        self._update_attributes(new_obj)
+        return self
+
+    ##############################
+    #  Context
+    ##############################
+
+    def _context(self) -> Context:
+        """
+        Get context.
+
+        Returns
+        -------
+        Context
+            Context object.
+        """
+        return get_context(self.project)

digitalhub/entities/_base/entity/executable.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._base.crud import list_entity_api_ctx
+from digitalhub.entities._base.entity.versioned import VersionedEntity
+from digitalhub.entities.entity_types import EntityTypes
+from digitalhub.entities.run.crud import delete_run, get_run, list_runs
+from digitalhub.entities.task.crud import delete_task, task_from_dict, task_from_parameters
+from digitalhub.utils.exceptions import EntityAlreadyExistsError, EntityError
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.metadata import Metadata
+    from digitalhub.entities._base.spec.base import Spec
+    from digitalhub.entities._base.status.base import Status
+    from digitalhub.entities.run.entity import Run
+    from digitalhub.entities.task.entity import Task
+
+
+class ExecutableEntity(VersionedEntity):
+    """
+    A class representing an entity that can be executed.
+    """
+
+    def __init__(
+        self,
+        project: str,
+        name: str,
+        uuid: str,
+        kind: str,
+        metadata: Metadata,
+        spec: Spec,
+        status: Status,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(project, name, uuid, kind, metadata, spec, status, user)
+
+        # Initialize tasks
+        self._tasks: dict[str, Task] = {}
+
+    ##############################
+    #  Helpers
+    ##############################
+
+    def _get_executable_string(self) -> str:
+        """
+        Get executable string.
+
+        Returns
+        -------
+        str
+            Executable string.
+        """
+        return f"{self.kind}://{self.project}/{self.name}:{self.id}"
+
+    ##############################
+    #  Tasks
+    ##############################
+
+    def _get_or_create_task(self, kind: str, **kwargs) -> Task:
+        """
+        Get or create task.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+
+        Returns
+        -------
+        Task
+            Task.
+        """
+        if self._tasks.get(kind) is None:
+            return self.new_task(kind)
+        return self._tasks[kind]
+
+    def import_tasks(self, tasks: list[dict]) -> None:
+        """
+        Import tasks from yaml.
+
+        Parameters
+        ----------
+        tasks : list[dict]
+            List of tasks to import.
+
+        Returns
+        -------
+        None
+        """
+        # Loop over tasks list, in the case where the function
+        # is imported from local file.
+        for task in tasks:
+            # If task is not a dictionary, skip it
+            if not isinstance(task, dict):
+                continue
+
+            # Create a new object from dictionary.
+            # the form in which tasks are stored in function
+            # status
+            task_obj = task_from_dict(task)
+
+            # Try to save it in backend to been able to use
+            # it for launching runs. In fact, tasks must be
+            # persisted in backend to be able to launch runs.
+            # Ignore if task already exists
+            try:
+                task_obj.save()
+            except EntityAlreadyExistsError:
+                pass
+
+            # Set task if function is the same. Overwrite
+            # status task dict with the new task object
+            if task_obj.spec.function == self._get_executable_string():
+                self._tasks[task_obj.kind] = task_obj
+
+    def new_task(self, task_kind: str, **kwargs) -> Task:
+        """
+        Create new task. If the task already exists, update it.
+
+        Parameters
+        ----------
+        task_kind : str
+            Kind the object.
+        **kwargs : dict
+            Keyword arguments.
+
+        Returns
+        -------
+        Task
+            New task.
+        """
+        self._raise_if_exists(task_kind)
+
+        if kwargs is None:
+            kwargs = {}
+
+        # Override kwargs
+        kwargs["project"] = self.project
+        kwargs["function"] = self._get_executable_string()
+        kwargs["kind"] = task_kind
+
+        # Create object instance
+        task = task_from_parameters(**kwargs)
+        task.save()
+
+        self._tasks[task_kind] = task
+        return task
+
+    def update_task(self, kind: str, **kwargs) -> Task:
+        """
+        Update task.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+        **kwargs : dict
+            Keyword arguments.
+
+        Returns
+        -------
+        Task
+            Task.
+        """
+        self._raise_if_not_exists(kind)
+
+        if kwargs is None:
+            kwargs = {}
+
+        # Update kwargs
+        kwargs["project"] = self.project
+        kwargs["kind"] = kind
+        kwargs["function"] = self._get_executable_string()
+        kwargs["uuid"] = self._tasks[kind].id
+
+        # Update task
+        task = task_from_parameters(**kwargs)
+        task.save(update=True)
+        self._tasks[kind] = task
+        return task
+
+    def get_task(self, kind: str) -> Task:
+        """
+        Get task.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+
+        Returns
+        -------
+        Task
+            Task.
+
+        Raises
+        ------
+        EntityError
+            If task is not created.
+        """
+        self._raise_if_not_exists(kind)
+        return self._tasks[kind]
+
+    def delete_task(self, kind: str, cascade: bool = True) -> dict:
+        """
+        Delete task.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+        cascade : bool
+            Flag to determine if cascade deletion must be performed.
+
+        Returns
+        -------
+        dict
+            Response from backend.
+        """
+        resp = delete_task(self._tasks[kind].key, cascade=cascade)
+        self._tasks.pop(kind, None)
+        return resp
+
+    def _check_task_in_backend(self, kind: str) -> bool:
+        """
+        Check if task exists in backend.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+
+        Returns
+        -------
+        bool
+            Flag to determine if task exists in backend.
+        """
+        # List tasks from backend filtered by function and kind
+        params = {"function": self._get_executable_string(), "kind": kind}
+        resp = list_entity_api_ctx(self.project, EntityTypes.TASK.value, params=params)
+        if not resp:
+            return False
+        return True
+
+    def _raise_if_exists(self, kind: str) -> None:
+        """
+        Raise error if task is created.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        EntityError
+            If task already exists.
+        """
+        if self._check_task_in_backend(kind):
+            raise EntityError(f"Task '{kind}' already exists.")
+
+    def _raise_if_not_exists(self, kind: str) -> None:
+        """
+        Raise error if task is not created.
+
+        Parameters
+        ----------
+        kind : str
+            Kind the object.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        EntityError
+            If task does not exist.
+        """
+        if self._tasks.get(kind) is None:
+            raise EntityError(f"Task '{kind}' does not exist.")
+
+    ##############################
+    #  Runs
+    ##############################
+
+    def get_run(
+        self,
+        identifier: str,
+        **kwargs,
+    ) -> Run:
+        """
+        Get object from backend.
+
+        Parameters
+        ----------
+        identifier : str
+            Entity key (store://...) or entity ID.
+        **kwargs : dict
+            Parameters to pass to the API call.
+
+        Returns
+        -------
+        Run
+            Object instance.
+
+        Examples
+        --------
+        Using entity key:
+        >>> obj = executable.get_run("store://my-secret-key")
+
+        Using entity ID:
+        >>> obj = executable.get_run("123")
+        """
+        obj = get_run(
+            identifier=identifier,
+            project=self.project,
+            **kwargs,
+        )
+        self.refresh()
+        return obj
+
+    def list_runs(self, **kwargs) -> list[Run]:
+        """
+        List all runs from backend.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Parameters to pass to the API call.
+
+        Returns
+        -------
+        list[Run]
+            List of object instances.
+
+        Examples
+        --------
+        >>> objs = executable.list_runs()
+        """
+        if kwargs is None:
+            kwargs = {}
+        kwargs["params"] = {"function": self._get_executable_string()}
+        return list_runs(self.project, **kwargs)
+
+    def delete_run(
+        self,
+        identifier: str,
+        **kwargs,
+    ) -> None:
+        """
+        Delete run from backend.
+
+        Parameters
+        ----------
+        identifier : str
+            Entity key (store://...) or entity ID.
+        **kwargs : dict
+            Parameters to pass to the API call.
+
+        Returns
+        -------
+        dict
+            Response from backend.
+
+        Examples
+        --------
+        >>> executable.delete_run("store://my-run-key")
+
+        """
+        delete_run(
+            identifier=identifier,
+            project=self.project,
+            **kwargs,
+        )