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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.3
+Version: 0.1.4
 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/client/__init__.py

@@ -0,0 +1,16 @@
+"""Ground Control Python SDK client package."""
+
+from grctl.client.client import Client
+from grctl.logging_config import get_logger, setup_logging
+from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
+from grctl.nats.connection import Connection
+
+__all__ = [
+    "Client",
+    "Connection",
+    "WorkflowAlreadyRunningError",
+    "WorkflowError",
+    "WorkflowNotFoundError",
+    "get_logger",
+    "setup_logging",
+]

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

@@ -6,14 +6,14 @@ Provides a simple interface for interacting with workflows.
 import asyncio
 import logging
 from datetime import UTC, datetime, timedelta
-from typing import Any
+from typing import Any, TypeVar, overload
 
 import msgspec
 from ulid import ULID
 
 from grctl.models import DescribeCmd, GrctlAPIResponse, HistoryEvent, RunInfo
 from grctl.models.command import CmdKind, Command
-from grctl.models.errors import WorkflowError, WorkflowNotFoundError
+from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
 from grctl.nats.connection import Connection
 from grctl.nats.history_fetch import fetch_run_history
 from grctl.worker.codec import CodecRegistry
@@ -21,6 +21,9 @@ from grctl.workflow.handle import WorkflowHandle
 
 logger = logging.getLogger(__name__)
 
+_T = TypeVar("_T")
+
+ErrWorkflowAlreadyRunningCode = 4001
 ErrWorkflowRunNotFoundCode = 4002
 
 
@@ -53,13 +56,34 @@ class Client:
 
         return msgspec.msgpack.decode(response.payload, type=RunInfo)
 
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: type[_T] = ...,
+    ) -> _T: ...
+
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: None = ...,
+    ) -> Any: ...
+
     async def run_workflow(
         self,
         type: str,  # noqa: A002
         id: str,  # noqa: A002
         input: Any | None = None,  # noqa: A002
         timeout: timedelta | None = None,  # noqa: ASYNC109
-    ) -> Any:
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
         """Run a workflow and wait for its result."""
         wf_handle = await self.start_workflow(
             type=type,
@@ -69,7 +93,10 @@ class Client:
         )
         wait_timeout = timeout.total_seconds() if timeout else None
         try:
-            return await asyncio.wait_for(wf_handle.future, timeout=wait_timeout)
+            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()
 
@@ -125,5 +152,14 @@ class Client:
         )
 
         # Start the workflow future (subscribe to events and publish run command)
-        await handle.start()
+        response_bytes = await handle.start()
+        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
+        if not response.success:
+            await handle.future.stop()
+            error_msg = response.error.message if response.error else "unknown error"
+            error_code = response.error.code if response.error else 0
+            if error_code == ErrWorkflowAlreadyRunningCode:
+                raise WorkflowAlreadyRunningError(f"workflow '{id}' already has an active run: {error_msg}")
+            raise WorkflowError(f"start_workflow failed (code={error_code}): {error_msg}")
+
         return handle

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/models/errors.py

@@ -4,3 +4,7 @@ class WorkflowError(Exception):
 
 class WorkflowNotFoundError(WorkflowError):
     """Raised when a workflow ID does not correspond to any active run."""
+
+
+class WorkflowAlreadyRunningError(WorkflowError):
+    """Raised when a workflow ID already has an active run."""

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/nats/history_fetch.py

@@ -1,10 +1,14 @@
+import logging
+
 from nats.js.api import AckPolicy, ConsumerConfig, DeliverPolicy
 from nats.js.client import JetStreamContext
-from nats.js.errors import FetchTimeoutError
+from nats.js.errors import FetchTimeoutError, ServiceUnavailableError
 
 from grctl.models import HistoryEvent, history_decoder
 from grctl.nats.manifest import NatsManifest
 
+logger = logging.getLogger(__name__)
+
 _FETCH_BATCH_SIZE = 256
 _FETCH_TIMEOUT_SECONDS = 0.25
 
@@ -29,14 +33,14 @@ async def fetch_run_history(
 
     events: list[HistoryEvent] = []
     try:
-        try:
-            while True:
-                messages = await subscription.fetch(batch=_FETCH_BATCH_SIZE, timeout=_FETCH_TIMEOUT_SECONDS)
-                events.extend(history_decoder(msg.data) for msg in messages if msg.data)
-        except (TimeoutError, FetchTimeoutError):
-            return events
+        while True:
+            messages = await subscription.fetch(batch=_FETCH_BATCH_SIZE, timeout=_FETCH_TIMEOUT_SECONDS)
+            events.extend(history_decoder(msg.data) for msg in messages if msg.data)
+    except (TimeoutError, FetchTimeoutError, ServiceUnavailableError):
+        pass
     finally:
         await subscription.unsubscribe()
+    return events
 
 
 async def fetch_step_history(
@@ -64,11 +68,11 @@ async def fetch_step_history(
 
     events: list[HistoryEvent] = []
     try:
-        try:
-            while True:
-                messages = await subscription.fetch(batch=_FETCH_BATCH_SIZE, timeout=_FETCH_TIMEOUT_SECONDS)
-                events.extend(history_decoder(msg.data) for msg in messages if msg.data)
-        except (TimeoutError, FetchTimeoutError):
-            return [event for event in events if event.operation_id]
+        while True:
+            messages = await subscription.fetch(batch=_FETCH_BATCH_SIZE, timeout=_FETCH_TIMEOUT_SECONDS)
+            events.extend(history_decoder(msg.data) for msg in messages if msg.data)
+    except (TimeoutError, FetchTimeoutError):
+        pass
     finally:
         await subscription.unsubscribe()
+    return [event for event in events if event.operation_id]

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/nats/kv_store.py

@@ -37,7 +37,8 @@ class KVStore:
                 return None
 
         except Exception as e:
-            if "key not found" in str(e).lower():
+            msg = str(e).lower()
+            if "key not found" in msg or "no message found" in msg:
                 return None
             raise
         else:

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/nats/publisher.py

@@ -42,5 +42,5 @@ class Publisher:
     ) -> bytes:
         subject = self._manifest.api_subject(wf_id=run.wf_id)
         data = command_encoder(cmd)
-        msg = await self._nc.request(subject, data)
+        msg = await self._nc.request(subject, data, timeout=5.0)
         return msg.data

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/worker/errors.py

@@ -12,13 +12,6 @@ class WorkflowRunnerNotFoundError(Exception):
         super().__init__(f"WorkflowRunner not found for WorkflowRun ID '{run_id}'.")
 
 
-class WorkflowAlreadyRunningError(Exception):
-    """Exception raised when attempting to start a workflow that is already running."""
-
-    def __init__(self, run_id: str) -> None:
-        super().__init__(f"WorkflowRun ID '{run_id}' is already running.")
-
-
 class NextDirectiveMissingError(Exception):
     """Exception raised when a workflow handler does not return a NextDirective."""
 

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

@@ -122,7 +122,7 @@ class WorkflowRunner:
 
         spec = handler_config.spec
         handler = handler_config.handler
-        if not spec.params:
+        if not spec.params or payload is None:
             directive = await handler(ctx)
 
         # Single param: if payload is already keyed by param name use the value,

{grctl_sdk_python-0.1.3 → grctl_sdk_python-0.1.4}/grctl/worker/task.py

@@ -365,7 +365,8 @@ async def _execute_task(
             return raw
         if isinstance(event, TaskFailed):
             raise _reconstruct_error(event.error)
-        # TaskCancelled — task didn't finish; fall through to execute it live
+        if isinstance(event, TaskCancelled):
+            raise asyncio.CancelledError
 
     previous_attempts = sum(
         1

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

@@ -33,7 +33,7 @@ class WorkflowHandle:
         logger.debug("Attaching to existing workflow %s", self.run_info.wf_id)
         await self.future.start()
 
-    async def start(self) -> None:
+    async def start(self) -> bytes:
         """Start the workflow future (subscribe to events and publish run command)."""
         input_value = self._codec.decode(self._codec.encode(self._payload)) if self._payload is not None else None
         cmd = Command(
@@ -48,7 +48,7 @@ class WorkflowHandle:
         logger.debug("Starting workflow history listener")
         await self.future.start()
         logger.debug("Publishing start command for workflow %s ", cmd)
-        await self._connection.publisher.publish_cmd(self.run_info, cmd)
+        return await self._connection.publisher.publish_cmd(self.run_info, cmd)
 
     async def send(self, event_name: str, payload: Any | None = None) -> None:
         normalized = self._codec.decode(self._codec.encode(payload)) if payload is not None else None

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

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

grctl_sdk_python-0.1.3/grctl/client/__init__.py

@@ -1,7 +0,0 @@
-"""Ground Control Python SDK client package."""
-
-from grctl.client.client import Client
-from grctl.logging_config import get_logger, setup_logging
-from grctl.nats.connection import Connection
-
-__all__ = ["Client", "Connection", "get_logger", "setup_logging"]