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

digitalhub/entities/_base/entity/material.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import typing
+from pathlib import Path
+
+from digitalhub.entities._base.crud import files_info_get_api, files_info_put_api
+from digitalhub.entities._base.entity.versioned import VersionedEntity
+from digitalhub.stores.builder import get_store
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.metadata import Metadata
+    from digitalhub.entities._base.spec.material import MaterialSpec
+    from digitalhub.entities._base.status.material import MaterialStatus
+
+
+class MaterialEntity(VersionedEntity):
+    """
+    A class representing an entity that can be materialized
+    as file(s).
+    """
+
+    def __init__(
+        self,
+        project: str,
+        name: str,
+        uuid: str,
+        kind: str,
+        metadata: Metadata,
+        spec: MaterialSpec,
+        status: MaterialStatus,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(project, name, uuid, kind, metadata, spec, status, user)
+        self.spec: MaterialSpec
+        self.status: MaterialStatus
+
+    def save(self, update: bool = False) -> MaterialEntity:
+        """
+        Save entity into backend.
+
+        Parameters
+        ----------
+        update : bool
+            Flag to indicate update.
+
+        Returns
+        -------
+        MaterialEntity
+            Entity saved.
+        """
+        obj = self.to_dict()
+
+        files = None
+        if self.status.files is not None and len(self.status.files) > 5 and not self._context().local:
+            files = obj["status"].pop("files")
+
+        if not update:
+            new_obj: MaterialEntity = self._save(obj)
+        else:
+            new_obj: MaterialEntity = self._update(obj)
+
+        # Handle files info
+        if files is not None:
+            files_info_put_api(self.project, self.ENTITY_TYPE, self.id, files)
+            self.status.add_files_info(files)
+
+        return new_obj
+
+    ##############################
+    # I/O Methods
+    ##############################
+
+    def as_file(self) -> list[str]:
+        """
+        Get object as file(s). It downloads the object from storage in
+        a temporary folder and returns the list of downloaded files paths.
+
+        Returns
+        -------
+        list[str]
+            List of file paths.
+        """
+        store = get_store(self.spec.path)
+        paths = self.status.get_file_paths()
+        dst = store._build_temp()
+        return store.download(self.spec.path, dst=dst, src=paths)
+
+    def download(
+        self,
+        destination: str | None = None,
+        overwrite: bool = False,
+    ) -> str:
+        """
+        This function downloads one or more file from storage on local
+        machine.
+        It looks inside the object's status for the file(s) path under
+        files attribute. If it does not find it, it will try to download
+        what it can from spec.path.
+        The files are downloaded into a destination folder. If the destination
+        is not specified, it will set by default under the context path
+        as '<ctx-root>/<entity_type>', e.g. './dataitem'.
+        The overwrite flag allows to overwrite existing file(s) in the
+        destination folder.
+
+        Parameters
+        ----------
+        destination : str
+            Destination path as filename or directory.
+        overwrite : bool
+            Specify if overwrite existing file(s). If file(s) already
+            exist and overwrite is False, it will raise an error.
+
+        Returns
+        -------
+        str
+            Downloaded path.
+
+        Examples
+        --------
+        Download a single file:
+
+        >>> entity.status.files[0]
+        {
+            "path ": "data.csv",
+            "name ": "data.csv",
+            "content_type ": "text/csv;charset=utf-8 "
+        }
+        >>> path = entity.download()
+        >>> print(path)
+        dataitem/data.csv
+        """
+        store = get_store(self.spec.path)
+        paths = self.status.get_file_paths()
+
+        if destination is None:
+            dst = self._context().root / self.ENTITY_TYPE
+        else:
+            dst = Path(destination)
+
+        return store.download(self.spec.path, dst=dst, src=paths, overwrite=overwrite)
+
+    def upload(self, source: str | list[str]) -> None:
+        """
+        Upload object from given local path to spec path destination.
+        Source must be a local path. If the path is a folder, destination
+        path (object's spec path) must be a folder or a partition ending
+        with '/' (s3).
+
+        Parameters
+        ----------
+        source : str | list[str]
+            Local filepath, directory or list of filepaths.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        Upload a single file:
+
+        >>> entity.spec.path = 's3://bucket/data.csv'
+        >>> entity.upload('./data.csv')
+
+        Upload a folder:
+        >>> entity.spec.path = 's3://bucket/data/'
+        >>> entity.upload('./data')
+        """
+        # Get store and upload object
+        store = get_store(self.spec.path)
+        paths = store.upload(source, self.spec.path)
+
+        # Update files info
+        files_info = store.get_file_info(paths)
+        self._update_files_info(files_info)
+
+    ##############################
+    #  Private Helpers
+    ##############################
+
+    def _update_files_info(self, files_info: list[dict] | None = None) -> None:
+        """
+        Update files info.
+
+        Parameters
+        ----------
+        files_info : list[dict] | None
+            Files info.
+
+        Returns
+        -------
+        None
+        """
+        if files_info is None:
+            return
+        self.refresh()
+        self.status.add_files_info(files_info)
+        self.save(update=True)
+
+    def _get_files_info(self) -> None:
+        """
+        Get files info from backend.
+
+        Returns
+        -------
+        None
+        """
+        if not self._context().local and not self.status.files:
+            files = files_info_get_api(
+                project=self.project,
+                entity_type=self.ENTITY_TYPE,
+                entity_id=self.id,
+            )
+            self.status.add_files_info(files)

digitalhub/entities/_base/entity/unversioned.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._base.entity.context import ContextEntity
+from digitalhub.entities._builders.metadata import build_metadata
+from digitalhub.entities._builders.spec import build_spec
+from digitalhub.entities._builders.status import build_status
+from digitalhub.entities._builders.uuid import build_uuid
+from digitalhub.utils.io_utils import write_yaml
+
+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 UnversionedEntity(ContextEntity):
+    def __init__(
+        self,
+        project: str,
+        uuid: str,
+        kind: str,
+        metadata: Metadata,
+        spec: Spec,
+        status: Status,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(project, kind, metadata, spec, status, user)
+        self.id = uuid
+        self.key = f"store://{project}/{self.ENTITY_TYPE}/{kind}/{uuid}"
+        self._obj_attr.extend(["id"])
+
+    def export(self, filename: str | None = None) -> str:
+        """
+        Export object as a YAML file.
+
+        Parameters
+        ----------
+        filename : str
+            Name of the export YAML file. If not specified, the default value is used.
+
+        Returns
+        -------
+        str
+            Exported file.
+        """
+        obj = self.to_dict()
+        if filename is None:
+            filename = f"{self.ENTITY_TYPE}-{self.id}.yml"
+        pth = self._context().root / filename
+        write_yaml(pth, obj)
+        return str(pth)
+
+    @staticmethod
+    def _parse_dict(obj: dict, validate: bool = True) -> dict:
+        """
+        Get dictionary and parse it to a valid entity dictionary.
+
+        Parameters
+        ----------
+        entity : str
+            Entity type.
+        obj : dict
+            Dictionary to parse.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the attributes of the entity instance.
+        """
+        project = obj.get("project")
+        kind = obj.get("kind")
+        uuid = build_uuid(obj.get("id"))
+        metadata = build_metadata(kind, **obj.get("metadata", {}))
+        spec = build_spec(kind, validate=validate, **obj.get("spec", {}))
+        status = build_status(kind, **obj.get("status", {}))
+        user = obj.get("user")
+        return {
+            "project": project,
+            "uuid": uuid,
+            "kind": kind,
+            "metadata": metadata,
+            "spec": spec,
+            "status": status,
+            "user": user,
+        }

digitalhub/entities/_base/entity/versioned.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._base.entity.context import ContextEntity
+from digitalhub.entities._builders.metadata import build_metadata
+from digitalhub.entities._builders.name import build_name
+from digitalhub.entities._builders.spec import build_spec
+from digitalhub.entities._builders.status import build_status
+from digitalhub.entities._builders.uuid import build_uuid
+from digitalhub.utils.io_utils import write_yaml
+
+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 VersionedEntity(ContextEntity):
+    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, kind, metadata, spec, status, user)
+        self.name = name
+        self.id = uuid
+        self.key = f"store://{project}/{self.ENTITY_TYPE}/{kind}/{name}:{uuid}"
+
+        # Add attributes to be used in the to_dict method
+        self._obj_attr.extend(["name", "id"])
+
+    def export(self, filename: str | None = None) -> str:
+        """
+        Export object as a YAML file.
+
+        Parameters
+        ----------
+        filename : str
+            Name of the export YAML file. If not specified, the default value is used.
+
+        Returns
+        -------
+        str
+            Exported file.
+        """
+        obj = self.to_dict()
+        if filename is None:
+            filename = f"{self.ENTITY_TYPE}-{self.name}-{self.id}.yml"
+        pth = self._context().root / filename
+        write_yaml(pth, obj)
+        return str(pth)
+
+    @staticmethod
+    def _parse_dict(obj: dict, validate: bool = True) -> dict:
+        """
+        Get dictionary and parse it to a valid entity dictionary.
+
+        Parameters
+        ----------
+        entity : str
+            Entity type.
+        obj : dict
+            Dictionary to parse.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the attributes of the entity instance.
+        """
+        project = obj.get("project")
+        kind = obj.get("kind")
+        name = build_name(obj.get("name"))
+        uuid = build_uuid(obj.get("id"))
+        metadata = build_metadata(kind, **obj.get("metadata", {}))
+        spec = build_spec(kind, validate=validate, **obj.get("spec", {}))
+        status = build_status(kind, **obj.get("status", {}))
+        user = obj.get("user")
+        return {
+            "project": project,
+            "name": name,
+            "uuid": uuid,
+            "kind": kind,
+            "metadata": metadata,
+            "spec": spec,
+            "status": status,
+            "user": user,
+        }

digitalhub/entities/_base/metadata.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.base import ModelObj
+
+
+class Metadata(ModelObj):
+    """
+    A class representing the metadata of an entity.
+    Metadata is a collection of information about an entity thought
+    to be modifiable by the user. The information contained in the
+    metadata can be discordant with the actual state of the entity,
+    for example the name of the entity in the database.
+    """
+
+    def __init__(
+        self,
+        project: str | None = None,
+        name: str | None = None,
+        version: str | None = None,
+        description: str | None = None,
+        labels: list[str] | None = None,
+        created: str | None = None,
+        created_by: str | None = None,
+        updated: str | None = None,
+        updated_by: str | None = None,
+        embedded: bool | None = None,
+        ref: str | None = None,
+        **kwargs,
+    ) -> None:
+        self.project = project
+        self.name = name
+        self.version = version
+        self.description = description
+        self.labels = labels
+        self.created = created
+        self.updated = updated
+        self.created_by = created_by
+        self.updated_by = updated_by
+        self.embedded = embedded
+        self.ref = ref
+
+        self._any_setter(**kwargs)
+
+    @classmethod
+    def from_dict(cls, obj: dict) -> Metadata:
+        """
+        Return entity metadata object from dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            A dictionary containing the attributes of the entity metadata.
+
+        Returns
+        -------
+        Metadata
+            An entity metadata object.
+        """
+        return cls(**obj)

digitalhub/entities/_base/spec/base.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from digitalhub.entities._base.base import ModelObj
+
+
+class Spec(ModelObj):
+    """
+    A class representing the specification of an entity.
+    Specification is a collection of information about an entity
+    thought to be immutable by the user.
+    """
+
+    @classmethod
+    def from_dict(cls, obj: dict) -> Spec:
+        """
+        Return entity specification object from dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            A dictionary containing the attributes of the entity specification.
+
+        Returns
+        -------
+        EntitySpec
+            An entity specification object.
+        """
+        return cls(**obj)
+
+
+class SpecParams(BaseModel, extra="ignore"):
+    """
+    A class representing the parameters of an entity.
+    This base class is used to define the parameters of an entity
+    specification and is used to validate the parameters passed
+    to the constructor.
+    """
+
+
+class MaterialSpec(Spec):
+    """
+    Material specification class.
+    """
+
+    def __init__(self, path: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.path = path
+
+
+class MaterialParams(SpecParams):
+    """
+    Material parameters class.
+    """
+
+    path: str
+    """Target path to file(s)"""

digitalhub/entities/_base/spec/material.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.spec.base import Spec, SpecParams
+
+
+class MaterialSpec(Spec):
+    """
+    Material specification class.
+    """
+
+    def __init__(self, path: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.path = path
+
+
+class MaterialParams(SpecParams):
+    """
+    Material parameters class.
+    """
+
+    path: str
+    """Target path to file(s)"""

digitalhub/entities/_base/state.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class State(Enum):
+    """
+    State enumeration.
+    """
+
+    BUILT = "BUILT"
+    CANCELLED = "CANCELLED"
+    COMPLETED = "COMPLETED"
+    CREATED = "CREATED"
+    CREATING = "CREATING"
+    DELETED = "DELETED"
+    DELETING = "DELETING"
+    ERROR = "ERROR"
+    FSM_ERROR = "FSM_ERROR"
+    IDLE = "IDLE"
+    NONE = "NONE"
+    ONLINE = "ONLINE"
+    PENDING = "PENDING"
+    READY = "READY"
+    RESUME = "RESUME"
+    RUN_ERROR = "RUN_ERROR"
+    RUNNING = "RUNNING"
+    STOP = "STOP"
+    STOPPED = "STOPPED"
+    SUCCESS = "SUCCESS"
+    UNKNOWN = "UNKNOWN"

digitalhub/entities/_base/status/base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.base import ModelObj
+
+
+class Status(ModelObj):
+    """
+    Base Status class.
+    The status class contains information about the state of an entity,
+    for example, the state of a RUNNING run, and eventual error message.
+    """
+
+    def __init__(self, state: str, message: str | None = None) -> None:
+        self.state = state
+        self.message = message
+
+    @classmethod
+    def from_dict(cls, obj: dict) -> Status:
+        """
+        Return entity status object from dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            A dictionary containing the attributes of the entity status.
+
+        Returns
+        -------
+        EntityStatus
+            An entity status object.
+        """
+        return cls(**obj)

digitalhub/entities/_base/status/material.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.status.base import Status
+
+
+class MaterialStatus(Status):
+    """
+    Material Status class.
+    """
+
+    def __init__(
+        self,
+        state: str,
+        message: str | None = None,
+        files: list[dict] | None = None,
+    ) -> None:
+        super().__init__(state, message)
+        if files is None:
+            files = []
+        self.files = files
+
+    def add_files_info(self, files: list[dict]) -> None:
+        """
+        Add a file to the status.
+
+        Parameters
+        ----------
+        files : list[dict]
+            Files to add.
+
+        Returns
+        -------
+        None
+        """
+        path_list = self.get_file_paths()
+        for f in files:
+            if f.get("path") not in path_list:
+                self.files.append(f)
+
+    def get_file_paths(self) -> list[str]:
+        """
+        Get the paths of the files in the status.
+
+        Returns
+        -------
+        list[str]
+            Paths of the files in the status.
+        """
+        return [f.get("path") for f in self.files]