feat(core): add workspace hydration service protocols (#1744)

Author: radu-mocanu

packages/uipath-core/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-core"
-version = "0.5.21"
+version = "0.5.22"
 description = "UiPath Core abstractions"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-core/src/uipath/core/workspace/__init__.py

@@ -0,0 +1,8 @@
+"""UiPath workspace hydration shared contracts."""
+
+from .protocols import AttachmentsProtocol, JobsProtocol
+
+__all__ = [
+    "AttachmentsProtocol",
+    "JobsProtocol",
+]

packages/uipath-core/src/uipath/core/workspace/protocols.py

@@ -0,0 +1,56 @@
+"""Service protocols for workspace hydration backend interactions."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+
+@runtime_checkable
+class AttachmentsProtocol(Protocol):
+    """Subset of the UiPath attachments service used by workspace hydration."""
+
+    async def download_async(
+        self,
+        *,
+        key: UUID,
+        destination_path: str,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> str:
+        """Download an attachment to a local path."""
+
+    async def upload_async(
+        self,
+        *,
+        name: str,
+        content: str | bytes | None = None,
+        source_path: str | None = None,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> UUID:
+        """Upload content or a local file and return its attachment key."""
+
+
+@runtime_checkable
+class JobsProtocol(Protocol):
+    """Subset of the UiPath jobs service used by workspace hydration."""
+
+    async def list_attachments_async(
+        self,
+        *,
+        job_key: UUID,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> list[str]:
+        """List the attachment ids linked to a job."""
+
+    async def link_attachment_async(
+        self,
+        *,
+        job_key: UUID,
+        attachment_key: UUID,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> None:
+        """Link an existing attachment to a job."""

packages/uipath-core/tests/workspace/__init__.py

@@ -0,0 +1,68 @@
+"""Structural-conformance tests for the workspace hydration protocols."""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from uipath.core.workspace import AttachmentsProtocol, JobsProtocol
+
+
+class _FakeAttachments:
+    async def download_async(
+        self,
+        *,
+        key: UUID,
+        destination_path: str,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> str:
+        return destination_path
+
+    async def upload_async(
+        self,
+        *,
+        name: str,
+        content: str | bytes | None = None,
+        source_path: str | None = None,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> UUID:
+        return uuid4()
+
+
+class _FakeJobs:
+    async def list_attachments_async(
+        self,
+        *,
+        job_key: UUID,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> list[str]:
+        return []
+
+    async def link_attachment_async(
+        self,
+        *,
+        job_key: UUID,
+        attachment_key: UUID,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> None:
+        return None
+
+
+class _NotAService:
+    pass
+
+
+def test_attachments_service_satisfies_protocol() -> None:
+    assert isinstance(_FakeAttachments(), AttachmentsProtocol)
+
+
+def test_jobs_service_satisfies_protocol() -> None:
+    assert isinstance(_FakeJobs(), JobsProtocol)
+
+
+def test_unrelated_object_does_not_satisfy_protocols() -> None:
+    assert not isinstance(_NotAService(), AttachmentsProtocol)
+    assert not isinstance(_NotAService(), JobsProtocol)