flo-python 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

flo/__init__.py

@@ -34,6 +34,7 @@ Example:
 from .client import FloClient
 from .exceptions import (
     BadRequestError,
+    BlockTooLongError,
     ConflictError,
     ConnectionFailedError,
     FloError,
@@ -48,20 +49,25 @@ from .exceptions import (
     NonRetryableError,
     NotConnectedError,
     NotFoundError,
+    OutcomePendingError,
     OverloadedError,
     PayloadTooLargeError,
     ProtocolError,
     RateLimitedError,
+    RequestTimeoutError,
     ServerError,
+    StaleNotFoundError,
+    TableMismatchError,
     UnauthorizedError,
+    UnavailableError,
     UnexpectedEofError,
-    UnsupportedVersionError,
     ValidationError,
     ValueTooLargeError,
     is_connection_error,
 )
 from .kv_txn import Transaction, TxnFinishedError, TxnUnsupportedOpError
 from .processing import ProcessingOperations
+from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
 from .types import (
     AckOptions,
     ActionDeleteOptions,
@@ -74,24 +80,27 @@ from .types import (
     ActionRunStatus,
     ActionStatusOptions,
     ActionType,
+    Condition,
     DeleteOptions,
     DequeueOptions,
     DequeueResult,
     DlqListOptions,
     DlqRequeueOptions,
     EnqueueOptions,
+    ExistsResult,
     GetJsonResult,
     GetOptions,
     GetResult,
     HistoryOptions,
+    HistoryResult,
+    IncrResult,
     KVBeginResult,
     KVCommitResult,
-    KVEntry,
     KVExistsOptions,
+    KVExpireOptions,
     KVIncrOptions,
     KVJsonOptions,
     KVMGetOptions,
-    KVTouchOptions,
     Message,
     MGetEntry,
     NackOptions,
@@ -102,17 +111,18 @@ from .types import (
     ProcessingCancelOptions,
     ProcessingListEntry,
     ProcessingListOptions,
-    ProcessingRescaleOptions,
-    ProcessingRestoreOptions,
-    ProcessingSavepointOptions,
     ProcessingStatusOptions,
     ProcessingStatusResult,
     ProcessingStopOptions,
     ProcessingSubmitOptions,
     ProcessingSyncOptions,
     ProcessingSyncResult,
+    ProcessKind,
     PutOptions,
     PutResult,
+    Ran,
+    Reason,
+    RunStatus,
     ScanOptions,
     ScanResult,
     StatusCode,
@@ -131,19 +141,23 @@ from .types import (
     StreamReadResult,
     StreamRecord,
     StreamTrimOptions,
+    StreamTrimResult,
     TaskAssignment,
-    TouchOptions,
     VersionEntry,
+    WaitFor,
     WorkerAwaitOptions,
     WorkerAwaitResult,
     WorkerCompleteOptions,
+    WorkerDetails,
     WorkerFailOptions,
     WorkerInfo,
     WorkerListOptions,
     WorkerListResult,
+    WorkerProcess,
     WorkerRegisterOptions,
-    WorkerTask,
+    WorkerStatus,
     WorkerTouchOptions,
+    WorkerType,
     WorkflowCancelOptions,
     WorkflowCreateOptions,
     WorkflowDisableOptions,
@@ -170,7 +184,7 @@ from .worker import (
 )
 from .workflows import WorkflowOperations
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 
 __all__ = [
     "Transaction",
@@ -182,13 +196,18 @@ __all__ = [
     "KVIncrOptions",
     "KVJsonOptions",
     "KVMGetOptions",
-    "KVTouchOptions",
+    "KVExpireOptions",
     "GetResult",
+    "HistoryResult",
+    "ExistsResult",
     "GetJsonResult",
     "MGetEntry",
     "PutResult",
+    "IncrResult",
     # Client
     "FloClient",
+    "RetryPolicy",
+    "DEFAULT_RETRY_POLICY",
     # High-level Worker API
     "ActionWorker",
     "ActionWorkerOptions",
@@ -207,9 +226,10 @@ __all__ = [
     "ConnectionFailedError",
     "InvalidEndpointError",
     "UnexpectedEofError",
+    "RequestTimeoutError",
     "ProtocolError",
     "InvalidMagicError",
-    "UnsupportedVersionError",
+    "TableMismatchError",
     "InvalidChecksumError",
     "PayloadTooLargeError",
     "IncompleteResponseError",
@@ -217,28 +237,35 @@ __all__ = [
     "NamespaceTooLargeError",
     "KeyTooLargeError",
     "ValueTooLargeError",
+    "BlockTooLongError",
     "ServerError",
     "NotFoundError",
     "BadRequestError",
     "ConflictError",
     "UnauthorizedError",
     "OverloadedError",
+    "OutcomePendingError",
+    "StaleNotFoundError",
+    "UnavailableError",
     "RateLimitedError",
     "InternalServerError",
     "GenericServerError",
     "is_connection_error",
     # Types
     "OpCode",
+    "Ran",
+    "Reason",
     "StatusCode",
     "OptionTag",
     # Result types
-    "KVEntry",
     "ScanResult",
     "VersionEntry",
     "Message",
     "DequeueResult",
     # Options
+    "Condition",
     "GetOptions",
+    "WaitFor",
     "PutOptions",
     "DeleteOptions",
     "ScanOptions",
@@ -250,7 +277,6 @@ __all__ = [
     "DlqListOptions",
     "DlqRequeueOptions",
     "PeekOptions",
-    "TouchOptions",
     # Stream types
     "StreamID",
     "StorageTier",
@@ -264,6 +290,7 @@ __all__ = [
     "StreamAppendOptions",
     "StreamReadOptions",
     "StreamTrimOptions",
+    "StreamTrimResult",
     "StreamInfoOptions",
     "StreamGroupJoinOptions",
     "StreamGroupReadOptions",
@@ -271,6 +298,7 @@ __all__ = [
     "StreamGroupNackOptions",
     # Action types
     "ActionType",
+    "RunStatus",
     "ActionInfo",
     "ActionRunStatus",
     "ActionInvokeResult",
@@ -283,10 +311,14 @@ __all__ = [
     "ActionDeleteOptions",
     # Worker types
     "TaskAssignment",
-    "WorkerTask",
     "WorkerAwaitResult",
+    "ProcessKind",
+    "WorkerDetails",
     "WorkerInfo",
+    "WorkerProcess",
     "WorkerListResult",
+    "WorkerStatus",
+    "WorkerType",
     # Worker options
     "WorkerRegisterOptions",
     "WorkerAwaitOptions",
@@ -316,9 +348,6 @@ __all__ = [
     "ProcessingListOptions",
     "ProcessingStopOptions",
     "ProcessingCancelOptions",
-    "ProcessingSavepointOptions",
-    "ProcessingRestoreOptions",
-    "ProcessingRescaleOptions",
     "ProcessingSyncOptions",
     "ProcessingStatusResult",
     "ProcessingListEntry",

flo/actions.py

@@ -9,6 +9,13 @@ For a higher-level API, see `Worker` in worker.py.
 
 from typing import TYPE_CHECKING
 
+from .kv_body import (
+    decode_action_invoke_answer,
+    decode_action_status_answer,
+    decode_worker_info_answer,
+    decode_worker_list_answer,
+    encode_worker_list_body,
+)
 from .types import (
     ActionDeleteOptions,
     ActionInvokeOptions,
@@ -24,10 +31,12 @@ from .types import (
     WorkerAwaitOptions,
     WorkerAwaitResult,
     WorkerCompleteOptions,
+    WorkerDetails,
     WorkerFailOptions,
     WorkerListOptions,
     WorkerListResult,
     WorkerRegisterOptions,
+    WorkerStatus,
     WorkerTouchOptions,
 )
 from .wire import (
@@ -39,7 +48,6 @@ from .wire import (
     serialize_worker_await_value,
     serialize_worker_complete_value,
     serialize_worker_fail_value,
-    serialize_worker_list_value,
     serialize_worker_register_value,
     serialize_worker_touch_value,
 )
@@ -78,7 +86,7 @@ class ActionOperations:
             action_type=action_type,
             timeout_ms=opts.timeout_ms,
             max_retries=opts.max_retries,
-            description=opts.description,
+            owner=opts.owner,
         )
 
         await self._client._send_and_check(
@@ -109,8 +117,7 @@ class ActionOperations:
 
         value = serialize_action_invoke_value(
             input_data=input_data,
-            priority=opts.priority,
-            idempotency_key=opts.idempotency_key,
+            labels=opts.labels,
         )
 
         response = await self._client._send_and_check(
@@ -120,9 +127,7 @@ class ActionOperations:
             value,
         )
 
-        # Response contains run_id as string
-        run_id = response.data.decode("utf-8") if response.data else ""
-        return ActionInvokeResult(run_id=run_id)
+        return ActionInvokeResult(run_id=decode_action_invoke_answer(response.data))
 
     async def status(
         self,
@@ -148,13 +153,7 @@ class ActionOperations:
             b"",
         )
 
-        # Parse status response - format TBD based on server implementation
-        # For now return basic status
-        return ActionRunStatus(
-            run_id=run_id,
-            status="unknown",
-            result=response.data if response.data else None,
-        )
+        return decode_action_status_answer(run_id, response.data)
 
     async def list(
         self,
@@ -233,6 +232,7 @@ class WorkerOperations:
 
         value = serialize_worker_register_value(
             task_types,
+            worker_type=int(opts.worker_type),
             max_concurrency=opts.concurrency,
             metadata=opts.metadata,
             machine_id=opts.machine_id,
@@ -250,24 +250,57 @@ class WorkerOperations:
         worker_id: str,
         current_load: int = 0,
         namespace: str | None = None,
-    ) -> None:
+    ) -> WorkerStatus:
         """Send a worker heartbeat to keep the registration alive.
 
         Args:
             worker_id: Worker identifier.
             current_load: Current number of active tasks.
             namespace: Optional namespace override.
+
+        Returns:
+            The worker's status on the server: DRAINING once it is drained.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker (it never
+                registered, or was removed after going silent).
         """
         import struct
 
         ns = self._client.get_namespace(namespace)
         value = struct.pack("<I", current_load)
-        await self._client._send_and_check(
+        response = await self._client._send_and_check(
             OpCode.WORKER_HEARTBEAT,
             ns,
             worker_id.encode("utf-8"),
             value,
         )
+        if len(response.data) != 1:
+            raise ValueError(f"heartbeat answer is {len(response.data)} bytes, want 1")
+        return WorkerStatus(response.data[0])
+
+    async def drain(self, worker_id: str, namespace: str | None = None) -> None:
+        """Mark a worker draining: the server gives it no more work, and
+        its heartbeats answer DRAINING until it deregisters.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker.
+        """
+        await self._client._send_and_check(
+            OpCode.WORKER_DRAIN,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
+
+    async def deregister(self, worker_id: str, namespace: str | None = None) -> None:
+        """Remove a worker from the registry."""
+        await self._client._send_and_check(
+            OpCode.WORKER_DEREGISTER,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
 
     async def await_task(
         self,
@@ -280,7 +313,7 @@ class WorkerOperations:
         Args:
             worker_id: Worker identifier.
             task_types: Task types to listen for.
-            options: Optional await options (block_ms, timeout_ms).
+            options: Optional await options (block_ms).
 
         Returns:
             WorkerAwaitResult with task if available.
@@ -290,12 +323,9 @@ class WorkerOperations:
 
         value = serialize_worker_await_value(task_types)
 
-        # Build options for block_ms and timeout_ms
         options_builder = OptionsBuilder()
         if opts.block_ms is not None:
             options_builder.add_u32(OptionTag.BLOCK_MS, opts.block_ms)
-        if opts.timeout_ms is not None:
-            options_builder.add_u32(OptionTag.TIMEOUT_MS, opts.timeout_ms)
 
         response = await self._client._send_and_check(
             OpCode.ACTION_AWAIT,
@@ -402,25 +432,40 @@ class WorkerOperations:
         self,
         options: WorkerListOptions | None = None,
     ) -> WorkerListResult:
-        """List registered workers.
+        """List a page of the namespace's workers, in id order.
 
         Args:
-            options: Optional list options.
+            options: The page's limit and cursor (the last page's ``cursor``;
+                None starts).
 
         Returns:
-            WorkerListResult with list of workers.
+            WorkerListResult with the page's workers and the next page's
+            cursor, None on the last page.
         """
         opts = options or WorkerListOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_list_value(opts.limit)
-
-        await self._client._send_and_check(
+        response = await self._client._send_and_check(
             OpCode.WORKER_LIST,
             namespace,
             b"",
-            value,
+            encode_worker_list_body(opts.limit, opts.cursor, opts.action),
         )
 
-        # Parse list response - format TBD based on server implementation
-        return WorkerListResult(workers=[])
+        workers, cursor = decode_worker_list_answer(response.data)
+        return WorkerListResult(workers=workers, cursor=cursor)
+
+    async def info(self, worker_id: str, namespace: str | None = None) -> WorkerDetails:
+        """A worker's record: its row, as :meth:`list` shows it, the metadata
+        it registered with, and its processes with their run and fail counts.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker.
+        """
+        response = await self._client._send_and_check(
+            OpCode.WORKER_INFO,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
+        return decode_worker_info_answer(response.data)