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

digitalhub/entities/utils.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from digitalhub.entities.entity_types import EntityTypes
+from digitalhub.utils.env_utils import get_s3_bucket
+from digitalhub.utils.file_utils import get_file_mime_type
+from digitalhub.utils.uri_utils import check_local_path
+
+
+def parse_entity_key(key: str) -> tuple[str]:
+    """
+    Parse the entity key. Returns project, entity type, kind, name and uuid.
+
+    Parameters
+    ----------
+    key : str
+        The entity key.
+
+    Returns
+    -------
+    tuple[str]
+        Project, entity type, kind, name and uuid.
+    """
+    try:
+        # Remove "store://" from the key
+        key = key.replace("store://", "")
+
+        # Split the key into parts
+        parts = key.split("/")
+
+        # The project is the first part
+        project = parts[0]
+
+        # The entity type is the second part
+        entity_type = parts[1]
+
+        # The kind is the third part
+        kind = parts[2]
+
+        # Tasks and runs have no name and uuid
+        if entity_type in (EntityTypes.TASK.value, EntityTypes.RUN.value):
+            name = None
+            uuid = parts[3]
+
+        # The name and uuid are separated by a colon in the last part
+        else:
+            name, uuid = parts[3].split(":")
+
+        return project, entity_type, kind, name, uuid
+    except Exception as e:
+        raise ValueError("Invalid key format.") from e
+
+
+def eval_local_source(source: str | list[str]) -> None:
+    """
+    Evaluate if source is local.
+
+    Parameters
+    ----------
+    source : str | list[str]
+        Source(s).
+
+    Returns
+    -------
+    None
+    """
+    if isinstance(source, list):
+        if not source:
+            raise ValueError("Empty list of sources.")
+        source_is_local = all(check_local_path(s) for s in source)
+        for s in source:
+            if Path(s).is_dir():
+                raise ValueError(f"Invalid source path: {s}. List of paths must be list of files, not directories.")
+    else:
+        source_is_local = check_local_path(source)
+
+    if not source_is_local:
+        raise ValueError("Invalid source path. Source must be a local path.")
+
+
+def eval_zip_type(source: str | list[str]) -> bool:
+    """
+    Evaluate zip type.
+
+    Parameters
+    ----------
+    source : str | list[str]
+        Source(s).
+
+    Returns
+    -------
+    bool
+        True if path is zip.
+    """
+    if isinstance(source, list):
+        if len(source) > 1:
+            return False
+        else:
+            path = source[0]
+    else:
+        if Path(source).is_dir():
+            return False
+        path = source
+
+    extension = path.endswith(".zip")
+    mime_zip = get_file_mime_type(path) == "application/zip"
+    return extension or mime_zip
+
+
+def build_log_path_from_filename(
+    project: str,
+    entity_type: str,
+    name: str,
+    uuid: str,
+    filename: str,
+) -> str:
+    """
+    Build log path.
+
+    Parameters
+    ----------
+    project : str
+        Project name.
+    entity_type : str
+        Entity type.
+    name : str
+        Object name.
+    uuid : str
+        Object UUID.
+    filename : str
+        Filename.
+
+    Returns
+    -------
+    str
+        Log path.
+    """
+    return f"s3://{get_s3_bucket()}/{project}/{entity_type}/{name}/{uuid}/{filename}"
+
+
+def build_log_path_from_source(
+    project: str,
+    entity_type: str,
+    name: str,
+    uuid: str,
+    source: str | list[str],
+) -> str:
+    """
+    Build log path.
+
+    Parameters
+    ----------
+    project : str
+        Project name.
+    entity_type : str
+        Entity type.
+    name : str
+        Object name.
+    uuid : str
+        Object UUID.
+    source : str | list[str]
+        Source(s).
+
+    Returns
+    -------
+    str
+        Log path.
+    """
+    is_zip = eval_zip_type(source)
+    scheme = "zip+s3" if is_zip else "s3"
+    path = f"{scheme}://{get_s3_bucket()}/{project}/{entity_type}/{name}/{uuid}"
+
+    if isinstance(source, list) and len(source) >= 1:
+        if len(source) > 1:
+            path += "/"
+        else:
+            path += f"/{Path(source[0]).name}"
+    elif Path(source).is_dir():
+        path += "/"
+    elif Path(source).is_file():
+        path += f"/{Path(source).name}"
+
+    return path

digitalhub/entities/workflow/builder.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+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.entities.workflow.entity import Workflow
+
+
+def workflow_from_parameters(
+    project: str,
+    name: str,
+    kind: str,
+    uuid: str | None = None,
+    description: str | None = None,
+    labels: list[str] | None = None,
+    embedded: bool = True,
+    **kwargs,
+) -> Workflow:
+    """
+    Create a new object.
+
+    Parameters
+    ----------
+    project : str
+        Project name.
+    name : str
+        Object name.
+    kind : str
+        Kind the object.
+    uuid : str
+        ID of the object (UUID4, e.g. 40f25c4b-d26b-4221-b048-9527aff291e2).
+    labels : list[str]
+        List of labels.
+    description : str
+        Description of the object (human readable).
+    embedded : bool
+        Flag to determine if object spec must be embedded in project spec.
+    **kwargs : dict
+        Spec keyword arguments.
+
+    Returns
+    -------
+    Workflow
+        Object instance.
+    """
+    name = build_name(name)
+    uuid = build_uuid(uuid)
+    spec = build_spec(
+        kind,
+        **kwargs,
+    )
+    metadata = build_metadata(
+        kind,
+        project=project,
+        name=name,
+        version=uuid,
+        description=description,
+        labels=labels,
+        embedded=embedded,
+    )
+    status = build_status(
+        kind,
+    )
+    return Workflow(
+        project=project,
+        name=name,
+        uuid=uuid,
+        kind=kind,
+        metadata=metadata,
+        spec=spec,
+        status=status,
+    )
+
+
+def workflow_from_dict(obj: dict) -> Workflow:
+    """
+    Create a new object from dictionary.
+
+    Parameters
+    ----------
+    obj : dict
+        Dictionary to create object from.
+
+    Returns
+    -------
+    Workflow
+        Object instance.
+    """
+    return Workflow.from_dict(obj)

digitalhub/entities/workflow/crud.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.context.builder import check_context
+from digitalhub.entities._base.crud import (
+    delete_entity_api_ctx,
+    list_entity_api_ctx,
+    read_entity_api_ctx,
+    read_entity_api_ctx_versions,
+)
+from digitalhub.entities.entity_types import EntityTypes
+from digitalhub.entities.workflow.builder import workflow_from_dict, workflow_from_parameters
+from digitalhub.utils.exceptions import EntityAlreadyExistsError
+from digitalhub.utils.io_utils import read_yaml
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities.workflow.entity import Workflow
+
+
+ENTITY_TYPE = EntityTypes.WORKFLOW.value
+
+
+def new_workflow(
+    project: str,
+    name: str,
+    kind: str,
+    uuid: str | None = None,
+    description: str | None = None,
+    labels: list[str] | None = None,
+    embedded: bool = True,
+    **kwargs,
+) -> Workflow:
+    """
+    Create a new object.
+
+    Parameters
+    ----------
+    project : str
+        Project name.
+    name : str
+        Object name.
+    uuid : str
+        ID of the object (UUID4, e.g. 40f25c4b-d26b-4221-b048-9527aff291e2).
+    description : str
+        Description of the object (human readable).
+    labels : list[str]
+        List of labels.
+    embedded : bool
+        Flag to determine if object spec must be embedded in project spec.
+    **kwargs : dict
+        Spec keyword arguments.
+
+    Returns
+    -------
+    Workflow
+        Object instance.
+
+    Examples
+    --------
+    >>> obj = new_function(project="my-project",
+    >>>                    name="my-workflow",
+    >>>                    kind="kfp",
+    >>>                    code_src="pipeline.py",
+    >>>                    handler="pipeline-handler")
+    """
+    check_context(project)
+    obj = workflow_from_parameters(
+        project=project,
+        name=name,
+        kind=kind,
+        uuid=uuid,
+        description=description,
+        labels=labels,
+        embedded=embedded,
+        **kwargs,
+    )
+    obj.save()
+    return obj
+
+
+def get_workflow(
+    identifier: str,
+    project: str | None = None,
+    entity_id: str | None = None,
+    **kwargs,
+) -> Workflow:
+    """
+    Get object from backend.
+
+    Parameters
+    ----------
+    identifier : str
+        Entity key (store://...) or entity name.
+    project : str
+        Project name.
+    entity_id : str
+        Entity ID.
+    **kwargs : dict
+        Parameters to pass to the API call.
+
+    Returns
+    -------
+    Workflow
+        Object instance.
+
+    Examples
+    --------
+    Using entity key:
+    >>> obj = get_workflow("store://my-workflow-key")
+
+    Using entity name:
+    >>> obj = get_workflow("my-workflow-name"
+    >>>                    project="my-project",
+    >>>                    entity_id="my-workflow-id")
+    """
+    obj = read_entity_api_ctx(
+        identifier,
+        ENTITY_TYPE,
+        project=project,
+        entity_id=entity_id,
+        **kwargs,
+    )
+    return workflow_from_dict(obj)
+
+
+def get_workflow_versions(
+    identifier: str,
+    project: str | None = None,
+    **kwargs,
+) -> list[Workflow]:
+    """
+    Get object versions from backend.
+
+    Parameters
+    ----------
+    identifier : str
+        Entity key (store://...) or entity name.
+    project : str
+        Project name.
+    **kwargs : dict
+        Parameters to pass to the API call.
+
+    Returns
+    -------
+    list[Workflow]
+        List of object instances.
+
+    Examples
+    --------
+    Using entity key:
+    >>> obj = get_workflow_versions("store://my-workflow-key")
+
+    Using entity name:
+    >>> obj = get_workflow_versions("my-workflow-name"
+    >>>                             project="my-project")
+    """
+    obj = read_entity_api_ctx_versions(
+        identifier,
+        entity_type=ENTITY_TYPE,
+        project=project,
+        **kwargs,
+    )
+    return [workflow_from_dict(o) for o in obj]
+
+
+def list_workflows(project: str, **kwargs) -> list[Workflow]:
+    """
+    List all latest version objects from backend.
+
+    Parameters
+    ----------
+    project : str
+        Project name.
+    **kwargs : dict
+        Parameters to pass to the API call.
+
+    Returns
+    -------
+    list[Workflow]
+        List of object instances.
+
+    Examples
+    --------
+    >>> objs = list_workflows(project="my-project")
+    """
+    objs = list_entity_api_ctx(
+        project=project,
+        entity_type=ENTITY_TYPE,
+        **kwargs,
+    )
+    return [workflow_from_dict(obj) for obj in objs]
+
+
+def import_workflow(file: str) -> Workflow:
+    """
+    Import object from a YAML file.
+
+    Parameters
+    ----------
+    file : str
+        Path to YAML file.
+
+    Returns
+    -------
+    Workflow
+        Object instance.
+
+    Examples
+    --------
+    >>> obj = import_workflow("my-workflow.yaml")
+    """
+    dict_obj: dict | list[dict] = read_yaml(file)
+    if isinstance(dict_obj, list):
+        wkf_dict = dict_obj[0]
+        tsk_dicts = dict_obj[1:]
+    else:
+        wkf_dict = dict_obj
+        tsk_dicts = []
+
+    check_context(wkf_dict.get("project"))
+    obj = workflow_from_dict(wkf_dict)
+
+    obj.import_tasks(tsk_dicts)
+
+    try:
+        obj.save()
+    except EntityAlreadyExistsError:
+        pass
+    finally:
+        return obj
+
+
+def update_workflow(entity: Workflow) -> Workflow:
+    """
+    Update object. Note that object spec are immutable.
+
+    Parameters
+    ----------
+    entity : Workflow
+        Object to update.
+
+    Returns
+    -------
+    Workflow
+        Entity updated.
+
+    Examples
+    --------
+    >>> obj = update_workflow(obj)
+    """
+    return entity.save(update=True)
+
+
+def delete_workflow(
+    identifier: str,
+    project: str | None = None,
+    entity_id: str | None = None,
+    delete_all_versions: bool = False,
+    cascade: bool = True,
+    **kwargs,
+) -> dict:
+    """
+    Delete object from backend.
+
+    Parameters
+    ----------
+    identifier : str
+        Entity key (store://...) or entity name.
+    project : str
+        Project name.
+    entity_id : str
+        Entity ID.
+    delete_all_versions : bool
+        Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+    cascade : bool
+        Cascade delete.
+    **kwargs : dict
+        Parameters to pass to the API call.
+
+    Returns
+    -------
+    dict
+        Response from backend.
+
+    Examples
+    --------
+    If delete_all_versions is False:
+    >>> obj = delete_workflow("store://my-workflow-key")
+
+    Otherwise:
+    >>> obj = delete_workflow("workflow-name",
+    >>>                       project="my-project",
+    >>>                       delete_all_versions=True)
+    """
+    return delete_entity_api_ctx(
+        identifier=identifier,
+        entity_type=ENTITY_TYPE,
+        project=project,
+        entity_id=entity_id,
+        delete_all_versions=delete_all_versions,
+        cascade=cascade,
+        **kwargs,
+    )

digitalhub/entities/workflow/entity.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import typing
+
+from digitalhub.entities._base.entity.executable import ExecutableEntity
+from digitalhub.entities.entity_types import EntityTypes
+from digitalhub.runtimes.builder import get_kind_registry
+from digitalhub.utils.exceptions import BackendError
+
+if typing.TYPE_CHECKING:
+    from digitalhub.entities._base.metadata import Metadata
+    from digitalhub.entities.run.entity import Run
+    from digitalhub.entities.workflow.spec import WorkflowSpec
+    from digitalhub.entities.workflow.status import WorkflowStatus
+
+
+class Workflow(ExecutableEntity):
+    """
+    A class representing a workflow.
+    """
+
+    ENTITY_TYPE = EntityTypes.WORKFLOW.value
+
+    def __init__(
+        self,
+        project: str,
+        name: str,
+        uuid: str,
+        kind: str,
+        metadata: Metadata,
+        spec: WorkflowSpec,
+        status: WorkflowStatus,
+        user: str | None = None,
+    ) -> None:
+        super().__init__(project, name, uuid, kind, metadata, spec, status, user)
+
+        self.spec: WorkflowSpec
+        self.status: WorkflowStatus
+
+    ##############################
+    #  Workflow Methods
+    ##############################
+
+    def run(self, action: str | None = None, **kwargs) -> Run:
+        """
+        Run workflow.
+
+        Parameters
+        ----------
+        action : str
+            Action to execute.
+        **kwargs : dict
+            Keyword arguments passed to Run builder.
+
+        Returns
+        -------
+        Run
+            Run instance.
+        """
+        if action is None:
+            action = "pipeline"
+
+        # Get kind registry
+        kind_reg = get_kind_registry(self.kind)
+
+        # Get task and run kind
+        task_kind = kind_reg.get_task_kind_from_action(action=action)
+        run_kind = kind_reg.get_run_kind()
+
+        # Create or update new task
+        task = self._get_or_create_task(task_kind)
+
+        # Raise error if execution is not done by DHCore backend
+        if self._context().local:
+            raise BackendError("Cannot run workflow with local backend.")
+
+        return task.run(run_kind, local_execution=False, **kwargs)

digitalhub/entities/workflow/spec.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.spec.base import Spec, SpecParams
+
+
+class WorkflowSpec(Spec):
+    """
+    Workflow specifications.
+    """
+
+
+class WorkflowParams(SpecParams):
+    """
+    Workflow parameters.
+    """

digitalhub/entities/workflow/status.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from digitalhub.entities._base.status.base import Status
+
+
+class WorkflowStatus(Status):
+    """
+    Status class for workflow entities.
+    """