grctl-sdk-python 0.1.4__tar.gz → 0.2.1__tar.gz

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.4
+Version: 0.2.1
 Summary: The Python SDK for the Ground Control
 Author: Cem Evren Ates
 Author-email: Cem Evren Ates <cemevre@gmail.com>

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/client/client.py

@@ -3,7 +3,6 @@
 Provides a simple interface for interacting with workflows.
 """
 
-import asyncio
 import logging
 from datetime import UTC, datetime, timedelta
 from typing import Any, TypeVar, overload
@@ -90,15 +89,10 @@ class Client:
             id=id,
             input=input,
             timeout=timeout,
+            return_type=return_type,
         )
         wait_timeout = timeout.total_seconds() if timeout else None
-        try:
-            result = await asyncio.wait_for(wf_handle.future, timeout=wait_timeout)
-            if return_type is not None:
-                return self._codec.from_primitive(result, return_type)
-            return result
-        finally:
-            await wf_handle.future.stop()
+        return await wf_handle.result(timeout=wait_timeout)
 
     async def get_workflow_handle(self, wfid: str) -> WorkflowHandle:
         """Get a handle for an already-running workflow."""
@@ -132,6 +126,7 @@ class Client:
         id: str,  # noqa: A002
         input: Any | None = None,  # noqa: A002
         timeout: timedelta | None = None,  # noqa: ASYNC109
+        return_type: type | None = None,
     ) -> WorkflowHandle:
         """Start a workflow and return a handle to track and interact with it."""
         workflow_run_id = str(ULID())
@@ -149,6 +144,7 @@ class Client:
             payload=input,
             connection=self._connection,
             codec=self._codec,
+            return_type=return_type,
         )
 
         # Start the workflow future (subscribe to events and publish run command)

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/models/__init__.py

@@ -23,12 +23,11 @@ from grctl.models.directive import (
     DirectiveMessage,
     Event,
     Fail,
-    Sleep,
-    SleepUntil,
+    FailStep,
     Start,
     Step,
     StepResult,
-    WaitEvent,
+    Wait,
     directive_decoder,
     directive_encoder,
 )
@@ -62,6 +61,8 @@ from grctl.models.history import (
     TaskStarted,
     TimestampRecorded,
     UuidRecorded,
+    WaitStarted,
+    WaitTimedOut,
     history_decoder,
     history_encoder,
 )
@@ -90,11 +91,10 @@ __all__ = [  # noqa: RUF022
     "Event",
     "Complete",
     "Fail",
+    "FailStep",
     "Step",
     "StepResult",
-    "WaitEvent",
-    "Sleep",
-    "SleepUntil",
+    "Wait",
     "directive_decoder",
     "directive_encoder",
     # History event types
@@ -124,6 +124,8 @@ __all__ = [  # noqa: RUF022
     "RandomRecorded",
     "UuidRecorded",
     "SleepRecorded",
+    "WaitStarted",
+    "WaitTimedOut",
     "ChildWorkflowStarted",
     "ParentEventSent",
     "history_decoder",

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/models/directive.py

@@ -54,25 +54,11 @@ class Step(msgspec.Struct):
     timeout_ms: int | None = 3_000  # 3 seconds in nanoseconds (Go time.Duration)
 
 
-class WaitEvent(msgspec.Struct):
-    """Worker directive to wait for events."""
+class Wait(msgspec.Struct):
+    """Worker directive to park the run; optionally times out to a named step."""
 
-    timeout_ms: int = 3000
-    timeout_step_name: str | None = None
-
-
-class Sleep(msgspec.Struct):
-    """Worker directive to sleep for duration."""
-
-    next_step_name: str
-    duration_ms: int = 3000
-
-
-class SleepUntil(msgspec.Struct):
-    """Worker directive to sleep until timestamp."""
-
-    until: datetime
-    next_step_name: str
+    timeout_ms: int = 0
+    timeout_step_name: str = ""
 
 
 class Complete(msgspec.Struct):
@@ -87,6 +73,13 @@ class Fail(msgspec.Struct):
     error: ErrorDetails
 
 
+class FailStep(msgspec.Struct):
+    """Worker directive to mark a step as failed and fail the run."""
+
+    step_name: str
+    error: ErrorDetails
+
+
 class DirectiveKind(StrEnum):
     start = "start"
     cancel = "cancel"
@@ -95,10 +88,10 @@ class DirectiveKind(StrEnum):
     fail = "fail"
     step = "step"
     event = "event"
-    wait_event = "wait_event"
-    sleep = "sleep"
-    sleep_until = "sleep_until"
+    wait = "wait"
+    wait_timeout = "wait_timeout"
     step_result = "step_result"
+    fail_step = "fail_step"
 
 
 class StepResult(msgspec.Struct):
@@ -115,7 +108,7 @@ class StepResult(msgspec.Struct):
     duration_ms: int = 0
 
 
-DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | WaitEvent | Sleep | SleepUntil | StepResult
+DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | Wait | StepResult
 
 
 # Factory map for kind-based deserialization
@@ -126,9 +119,7 @@ directive_factories: dict[str, type[DirectiveMessage]] = {
     "complete": Complete,
     "fail": Fail,
     "step": Step,
-    "wait_event": WaitEvent,
-    "sleep": Sleep,
-    "sleep_until": SleepUntil,
+    "wait": Wait,
     "step_result": StepResult,
 }
 

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/models/history.py

@@ -15,7 +15,8 @@ class HistoryKind(StrEnum):
     run_cancel_scheduled = "run.cancel_scheduled"
     run_cancelled = "run.cancelled"
     run_timeout = "run.timeout"
-    wait_event_started = "wait_event.started"
+    wait_started = "wait.started"
+    wait_timed_out = "wait.timed_out"
     event_received = "event.received"
     step_started = "step.started"
     step_completed = "step.completed"
@@ -110,8 +111,19 @@ class StepTimeout(msgspec.Struct):
     duration_ms: int
 
 
-class WaitEventStarted(msgspec.Struct):
-    """Wait for event started."""
+class WaitStarted(msgspec.Struct):
+    """Run entered Wait state."""
+
+    directive_id: str = ""
+    timeout_ms: int = 0
+    timeout_step_name: str = ""
+
+
+class WaitTimedOut(msgspec.Struct):
+    """Wait timer expired; timeout step dispatched."""
+
+    original_directive_id: str = ""
+    timeout_step_name: str = ""
 
 
 class EventReceived(msgspec.Struct):
@@ -215,7 +227,7 @@ class ParentEventSent(msgspec.Struct):
 
 
 RunEvents = RunCancelScheduled | RunCancelled | RunCompleted | RunFailed | RunScheduled | RunStarted | RunTimeout
-WaitEvents = WaitEventStarted | EventReceived
+WaitEvents = WaitStarted | WaitTimedOut | EventReceived
 StepEvents = StepStarted | StepCompleted | StepFailed | StepCancelled | StepTimeout
 TaskEvents = TaskStarted | TaskCompleted | TaskFailed | TaskAttemptFailed | TaskCancelled
 DeterministicEvents = TimestampRecorded | RandomRecorded | UuidRecorded | SleepRecorded
@@ -232,7 +244,8 @@ HistoryEvents = (
     | StepFailed
     | StepCancelled
     | StepTimeout
-    | WaitEventStarted
+    | WaitStarted
+    | WaitTimedOut
     | EventReceived
     | TaskStarted
     | TaskCompleted
@@ -269,7 +282,8 @@ history_factories: dict[str, type] = {
     "run.cancel_scheduled": RunCancelScheduled,
     "run.cancelled": RunCancelled,
     "run.timeout": RunTimeout,
-    "wait_event.started": WaitEventStarted,
+    "wait.started": WaitStarted,
+    "wait.timed_out": WaitTimedOut,
     "event.received": EventReceived,
     "step.started": StepStarted,
     "step.completed": StepCompleted,

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/models/run_info.py

@@ -19,9 +19,7 @@ class RunStatus(StrEnum):
 class RunStateKind(StrEnum):
     start = "start"
     step = "step"
-    sleep = "sleep"
-    sleep_until = "sleep_until"
-    wait_event = "wait_event"
+    wait = "wait"
     complete = "complete"
     fail = "fail"
     cancel = "cancel"

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/worker/context.py

@@ -18,6 +18,7 @@ from grctl.models import (
     ErrorDetails,
     EventCmd,
     Fail,
+    FailStep,
     HistoryKind,
     ParentEventSent,
     RandomRecorded,
@@ -27,7 +28,7 @@ from grctl.models import (
     StepResult,
     TimestampRecorded,
     UuidRecorded,
-    WaitEvent,
+    Wait,
 )
 from grctl.worker.logger import ReplayAwareLogger
 from grctl.worker.runtime import get_step_runtime
@@ -82,14 +83,18 @@ class NextBuilder:
             id=str(ULID()), kind=DirectiveKind.step_result, run_info=self._run, timestamp=datetime.now(UTC), msg=res
         )
 
-    def wait_for_event(self, timeout: timedelta | None = None, timeout_step_name: str | None = None) -> Directive:
+    def wait(self, timeout: timedelta | None = None, on_timeout: StepHandler | None = None) -> Directive:
+        if (timeout is None) != (on_timeout is None):
+            raise ValueError("timeout and on_timeout must both be provided or both omitted")
+
+        timeout_step_name = getattr(on_timeout, "__name__", "") if on_timeout is not None else ""
         res = StepResult(
             processed_msg_kind=self._current_directive.kind,
             processed_msg=self._current_directive.msg,
             worker_id=self._worker_id,
             kv_updates=self._store.get_pending_updates() or {},
-            next_msg_kind=DirectiveKind.wait_event,
-            next_msg=WaitEvent(
+            next_msg_kind=DirectiveKind.wait,
+            next_msg=Wait(
                 timeout_ms=int(timeout.total_seconds() * 1000) if timeout else 0,
                 timeout_step_name=timeout_step_name,
             ),
@@ -115,6 +120,27 @@ class NextBuilder:
             id=str(ULID()), kind=DirectiveKind.step_result, run_info=self._run, timestamp=datetime.now(UTC), msg=res
         )
 
+    def fail_step(self, step_name: str, error: ErrorDetails) -> Directive:
+        res = StepResult(
+            processed_msg_kind=self._current_directive.kind,
+            processed_msg=self._current_directive.msg,
+            worker_id=self._worker_id,
+            kv_updates=self._store.get_pending_updates() or {},
+            next_msg_kind=DirectiveKind.fail_step,
+            next_msg=FailStep(
+                step_name=step_name,
+                error=error,
+            ),
+        )
+
+        return Directive(
+            id=str(ULID()),
+            kind=DirectiveKind.step_result,
+            run_info=self._run,
+            timestamp=datetime.now(UTC),
+            msg=res,
+        )
+
     def fail(self, error: ErrorDetails) -> Directive:
         res = StepResult(
             processed_msg_kind=self._current_directive.kind,

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/worker/runner.py

@@ -34,8 +34,9 @@ def workflow_error_handler(func):  # noqa: ANN001, ANN201
             logger.exception(f"Workflow execution failed in {func.__name__}")
 
             ctx = self.runtime.get_step_context()
-            fail_directive = ctx.next.fail(
-                ErrorDetails(
+            fail_directive = ctx.next.fail_step(
+                step_name=self.runtime.step_name,
+                error=ErrorDetails(
                     type=type(e).__name__,
                     message=str(e),
                     stack_trace=stack_trace,

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/workflow/handle.py

@@ -1,10 +1,11 @@
+import asyncio
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar, overload
 
 from ulid import ULID
 
 from grctl.logging_config import get_logger
-from grctl.models import CmdKind, Command, EventCmd, RunInfo, StartCmd
+from grctl.models import CancelCmd, CmdKind, Command, EventCmd, RunInfo, StartCmd
 from grctl.worker.codec import CodecRegistry
 from grctl.workflow.future import WorkflowFuture
 
@@ -13,6 +14,8 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+_T = TypeVar("_T")
+
 
 class WorkflowHandle:
     def __init__(
@@ -21,11 +24,13 @@ class WorkflowHandle:
         payload: Any | None,
         connection: "Connection",
         codec: CodecRegistry | None = None,
+        return_type: type | None = None,
     ) -> None:
         self.run_info = run_info
         self._payload = payload
         self._connection = connection
         self._codec = codec or CodecRegistry()
+        self._return_type = return_type
         self.future = WorkflowFuture(run_info, connection.nc, payload)
 
     async def attach(self) -> None:
@@ -65,6 +70,43 @@ class WorkflowHandle:
         logger.debug("Publishing event command for workflow %s", cmd)
         await self._connection.publisher.publish_cmd(self.run_info, cmd)
 
+    @overload
+    async def result(self, timeout: float | None = ..., return_type: type[_T] = ...) -> _T: ...  # noqa: ASYNC109
+
+    @overload
+    async def result(self, timeout: float | None = ..., return_type: None = ...) -> Any: ...  # noqa: ASYNC109
+
+    async def result(
+        self,
+        timeout: float | None = None,  # noqa: ASYNC109
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
+        """Wait for workflow completion and return its result.
+
+        timeout: client-side wait in seconds, independent of any server-side execution timeout.
+        return_type: overrides the type bound at start time; falls back to handle's bound type.
+        """
+        resolved_type = return_type or self._return_type
+        try:
+            raw = await asyncio.wait_for(self.future, timeout=timeout)
+            if resolved_type is not None:
+                return self._codec.from_primitive(raw, resolved_type)
+            return raw
+        finally:
+            await self.future.stop()
+
+    async def cancel(self, reason: str | None = None) -> None:
+        cmd = Command(
+            id=str(ULID()),
+            kind=CmdKind.run_cancel,
+            timestamp=datetime.now(UTC),
+            msg=CancelCmd(
+                wf_id=self.run_info.wf_id,
+                reason=reason,
+            ),
+        )
+        await self._connection.publisher.publish_cmd(self.run_info, cmd)
+
     async def query(self, query_name: str) -> Any:
         raise NotImplementedError("query() not yet implemented")
 

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/grctl/workflow/workflow.py

@@ -6,13 +6,20 @@ import logging
 import typing
 from collections.abc import Awaitable, Callable
 from datetime import timedelta
-from typing import Any, TypeVar
+from typing import Any, Protocol, TypeVar
 
 from grctl.models.directive import Directive
 
 logger = logging.getLogger(__name__)
 
-_HandlerF = TypeVar("_HandlerF", bound=Callable[..., Awaitable[Directive]])
+
+class _Handler(Protocol):
+    __name__: str
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Awaitable[Directive]: ...
+
+
+_HandlerF = TypeVar("_HandlerF", bound=_Handler)
 
 
 @dataclasses.dataclass

{grctl_sdk_python-0.1.4 → grctl_sdk_python-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grctl-sdk-python"
-version = "0.1.4"
+version = "0.2.1"
 description = "The Python SDK for the Ground Control"
 readme = "README.md"
 requires-python = ">=3.13"