digitalhub 0.7.0b2__py3-none-any.whl → 0.8.0__py3-none-any.whl

digitalhub/entities/_base/entity/_constructors/status.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities.utils.state import State
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.entity.status import Status
+
+
+def build_status(status_cls: Status, **kwargs) -> Status:
+    """
+    Build entity status object. This method is used to build entity
+    status.
+
+    Parameters
+    ----------
+    status_cls : Status
+        Entity status class.
+    **kwargs : dict
+        Keyword arguments.
+
+    Returns
+    -------
+    Status
+        Entity status object.
+    """
+    kwargs = parse_arguments(**kwargs)
+    return status_cls(**kwargs)
+
+
+def parse_arguments(**kwargs) -> dict:
+    """
+    Parse keyword arguments and add default values if necessary.
+
+    Parameters
+    ----------
+    **kwargs : dict
+        Keyword arguments.
+
+    Returns
+    -------
+    dict
+        Keyword arguments with default values.
+    """
+    state = kwargs.get("state")
+    if state is None:
+        kwargs["state"] = State.CREATED.value
+    else:
+        if kwargs["state"] not in State.__members__:
+            raise ValueError(f"Invalid state: {state}")
+    return kwargs

digitalhub/entities/_base/entity/_constructors/uuid.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from digitalhub.utils.generic_utils import slugify_string
+
+
+def build_uuid(uuid: str | None = None) -> str:
+    """
+    Create a uuid if not given. If given, validate it.
+
+    Parameters
+    ----------
+    uuid : str
+        ID of the object.
+
+    Returns
+    -------
+    str
+        Validated UUID4.
+    """
+    if uuid is not None:
+        if slugify_string(uuid) != uuid:
+            raise ValueError(f"Invalid ID: {uuid}. Must pass slugified ID.")
+        return uuid
+    return str(uuid4())

digitalhub/entities/_base/entity/builder.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import typing
+from abc import abstractmethod
+
+from digitalhub.entities._base.entity._constructors.metadata import build_metadata
+from digitalhub.entities._base.entity._constructors.name import build_name
+from digitalhub.entities._base.entity._constructors.spec import build_spec
+from digitalhub.entities._base.entity._constructors.status import build_status
+from digitalhub.entities._base.entity._constructors.uuid import build_uuid
+from digitalhub.utils.exceptions import BuilderError
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.entity.entity import Entity
+    from digitalhub.entities._base.entity.metadata import Metadata
+    from digitalhub.entities._base.entity.spec import Spec, SpecValidator
+    from digitalhub.entities._base.entity.status import Status
+
+
+class EntityBuilder:
+    """
+    Builder class for building entities.
+    """
+
+    # Class variables
+    ENTITY_TYPE: str = None
+    ENTITY_CLASS: Entity = None
+    ENTITY_SPEC_CLASS: Spec = None
+    ENTITY_SPEC_VALIDATOR: SpecValidator = None
+    ENTITY_STATUS_CLASS: Status = None
+    ENTITY_KIND: str = None
+
+    def __init__(self) -> None:
+        if self.ENTITY_TYPE is None:
+            raise BuilderError("ENTITY_TYPE must be set")
+        if self.ENTITY_CLASS is None:
+            raise BuilderError("ENTITY_CLASS must be set")
+        if self.ENTITY_SPEC_CLASS is None:
+            raise BuilderError("ENTITY_SPEC_CLASS must be set")
+        if self.ENTITY_SPEC_VALIDATOR is None:
+            raise BuilderError("ENTITY_SPEC_VALIDATOR must be set")
+        if self.ENTITY_STATUS_CLASS is None:
+            raise BuilderError("ENTITY_STATUS_CLASS must be set")
+        if self.ENTITY_KIND is None:
+            raise BuilderError("ENTITY_KIND must be set")
+
+    def build_name(self, name: str) -> str:
+        """
+        Build entity name.
+
+        Parameters
+        ----------
+        name : str
+            Entity name.
+
+        Returns
+        -------
+        str
+            Entity name.
+        """
+        return build_name(name)
+
+    def build_uuid(self, uuid: str) -> str:
+        """
+        Build entity uuid.
+
+        Parameters
+        ----------
+        uuid : str
+            Entity uuid.
+
+        Returns
+        -------
+        str
+            Entity uuid.
+        """
+        return build_uuid(uuid)
+
+    def build_metadata(self, **kwargs) -> Metadata:
+        """
+        Build entity metadata object.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for the constructor.
+
+        Returns
+        -------
+        Metadata
+            Metadata object.
+        """
+        return build_metadata(**kwargs)
+
+    def build_spec(self, validate: bool = True, **kwargs) -> Spec:
+        """
+        Build entity spec object.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for the constructor.
+
+        Returns
+        -------
+        Spec
+            Spec object.
+        """
+        return build_spec(self.ENTITY_SPEC_CLASS, self.ENTITY_SPEC_VALIDATOR, validate=validate, **kwargs)
+
+    def build_status(self, **kwargs) -> Status:
+        """
+        Build entity status object.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for the constructor.
+
+        Returns
+        -------
+        Status
+            Status object.
+        """
+        return build_status(self.ENTITY_STATUS_CLASS, **kwargs)
+
+    def build_entity(self, **kwargs) -> Entity:
+        """
+        Build entity object.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for the constructor.
+
+        Returns
+        -------
+        Entity
+            Entity object.
+        """
+        return self.ENTITY_CLASS(**kwargs)
+
+    @abstractmethod
+    def build(self, *args, **kwargs) -> Entity:
+        """
+        Build entity object.
+        """
+
+    @abstractmethod
+    def from_dict(self, obj: dict, validate: bool = True) -> Entity:
+        """
+        Build entity object from dictionary.
+        """
+
+    def get_entity_type(self) -> str:
+        """
+        Get entity type.
+
+        Returns
+        -------
+        str
+            Entity type.
+        """
+        return self.ENTITY_TYPE
+
+    def get_kind(self) -> str:
+        """
+        Get entity kind.
+
+        Returns
+        -------
+        str
+            Entity kind.
+        """
+        return self.ENTITY_KIND

digitalhub/entities/_base/entity/entity.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import typing
+from abc import ABCMeta, abstractmethod
+
+from digitalhub.entities._base._base.entity import Base
+from digitalhub.factory.api import build_entity_from_dict
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.entity.metadata import Metadata
+    from digitalhub.entities._base.entity.spec import Spec
+    from digitalhub.entities._base.entity.status import Status
+
+
+class Entity(Base, metaclass=ABCMeta):
+    """
+    Abstract class for entities.
+
+    An entity is a collection of metadata, specifications.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 = build_entity_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}
+
+    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/metadata.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from digitalhub.entities._base._base.entity import Base
+
+
+class Metadata(Base):
+    """
+    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/entity/spec.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from digitalhub.entities._base._base.entity import Base
+
+
+class Spec(Base):
+    """
+    A class representing the specifications.of an entity.
+    specifications.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 specifications.object from dictionary.
+
+        Parameters
+        ----------
+        obj : dict
+            A dictionary containing the attributes of the entity specifications.
+
+        Returns
+        -------
+        EntitySpec
+            An entity specifications.object.
+        """
+        return cls(**obj)
+
+
+class SpecValidator(BaseModel, extra="ignore"):
+    """
+    A class representing the parameters of an entity.
+    This base class is used to define the parameters of an entity
+    specifications.and is used to validate the parameters passed
+    to the constructor.
+    """
+
+
+class MaterialSpec(Spec):
+    """
+    Material specifications.class.
+    """
+
+    def __init__(self, path: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.path = path
+
+
+class MaterialValidator(SpecValidator):
+    """
+    Material parameters class.
+    """
+
+    path: str
+    """Target path to file(s)"""

digitalhub/entities/_base/entity/status.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from digitalhub.entities._base._base.entity import Base
+
+
+class Status(Base):
+    """
+    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,
+        transitions: list[dict] | None = None,
+        k8s: dict | None = None,
+        **kwargs,
+    ) -> None:
+        self.state = state
+        self.message = message
+        self.transitions = transitions
+        self.k8s = k8s
+
+        self._any_setter(**kwargs)
+
+    @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)