dex-python-sdk 1.23.0__tar.gz → 1.26.0__tar.gz

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 1.23.0
+Version: 1.26.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -95,14 +95,17 @@ retain up to four idle credential threads. Sync token lookup must return
 promptly. By default, no authorization metadata is sent. Dex uses plaintext
 gRPC, so protect the network path that carries the token.
 
-## Pull mode
+## Workers
 
-Set `WorkerOptions.pull` to run a `Worker` or `AsyncWorker` with outbound task
-streams. The Worker connects to the Dex server through `server_address` and
-does not open a listener. Advertise `worker.worker_target` through
-`ClientOptions.worker_target`. A single Flow can override the Client default
-with `StartFlowOptions(config_override=FlowConfig(worker_target=...))`; a
-SubFlow can use `SubFlowOptions` with the same `FlowConfig` override.
+Workers receive tasks through outbound pull streams. `Worker` and `AsyncWorker`
+need only an outbound connection to the Dex Server at `server_address`. Configure
+capacity and shutdown with `WorkerOptions.pull`; its default is
+`PullWorkerOptions()`. Clients and Flows use pull routing automatically.
+
+StartFlow and SubFlow always select pull Workers. Updating Flow configuration
+preserves its existing Worker target; an empty `FlowConfig()` changes nothing.
+Before upgrading an application with active push Flows, use an SDK version that
+supports Worker targets to migrate those Flows to pull routing.
 
 ```python
 import threading
@@ -118,10 +121,11 @@ worker = Worker(
 )
 worker_thread = threading.Thread(target=worker.start)
 worker_thread.start()
+worker.wait_pull_registered(timeout=30)
 client = Client(
     registry,
     cache,
-    ClientOptions(server_address="dex.example:8801", worker_target=worker.worker_target),
+    ClientOptions(server_address="dex.example:8801"),
 )
 try:
     client.start_flow(flow, flow_id, input_value)
@@ -160,10 +164,7 @@ The generated `app_worker_id` uses the first nonempty `DEX_WORKER_INSTANCE`,
 `POD_NAME`, `HOSTNAME`, or system hostname, plus eight random base32 characters.
 An override must uniquely identify one Worker process and change after restart.
 It must contain 1-63 ASCII letters, digits, dots, underscores, or hyphens and
-must not equal a registered Flow type. Pull mode cannot configure a bind address
-or an advertised address or headless target. Use `WorkerTarget(pull=True)` for
-Client defaults or Flow overrides when the Worker target is not directly in
-scope.
+must not equal a registered Flow type.
 
 Pull streams reconnect after failures. A server-directed reconnect waits for
 an active task to finish, then waits up to `stop_drain_timeout` for the server
@@ -186,7 +187,7 @@ Worker ID queue to register at least once. Timeout raises `TimeoutError`;
 async cancellation cancels only that wait. Startup failures reach waiters.
 A permanent rejection before readiness raises `PullRegistrationError`, whose
 `queue` and `error` identify the rejected queue and original transport error.
-Listening mode and stop before readiness raise `RuntimeError`.
+Stopping before readiness raises `RuntimeError`.
 
 Use `worker.pull_registration_state()` for subsequent readiness probes. Its
 immutable `queues` expose `queue`, `has_registered_stream`, and
@@ -240,7 +241,6 @@ to distinguish reserve pressure from full-capacity rejections. The count exclude
 full-capacity rejections and unknown names. It counts decline events, including
 repeated declines of the same Step dispatch while Dex retries it. Read its rate
 to assess reserve pressure. It never resets and remains available after shutdown.
-Listening Workers return zero.
 
 ## Flow state I/O
 
@@ -398,7 +398,7 @@ explicit codec only for a custom encoding or a type Registry cannot derive.
 partitions them by definition type.
 
 `Worker` and `AsyncWorker` synchronize all registered Indexed Attributes with
-Dex Server before opening their listener. Existing indexes return immediately;
+Dex Server before opening outbound task streams. Existing indexes return immediately;
 failure or the default two-minute deadline aborts startup. An indexed
 `AttributeMap` must provide one fixed `index_key`.
 
@@ -619,9 +619,9 @@ options = dex.StartFlowOptions(
 ```
 
 Register async hooks with `allow_async_handlers=True` and run them with
-`AsyncWorker`. `FAIL` produces `FlowErrorType.FLOW_TIMEOUT` and permits Flow
-retry; `CANCEL` cancels without retry. Continue-as-new preserves the deadline,
-while retry runs receive a fresh budget. A zero or absent timeout
+`AsyncWorker`. `FAIL` produces `FlowErrorType.FLOW_TIMEOUT` and fails the
+Flow; `CANCEL` cancels it. The deadline is preserved across Flow state
+transfers. A zero or absent timeout
 disables the feature.
 
 `Registry` validates every Flow, Step, RPC signature, durable name, lock, and
@@ -651,12 +651,7 @@ Request IDs are optional for both durable waits. When omitted, the server
 derives a stable ID from the Step execution or Attribute condition. Reuse an
 override only for the same wait. `request_timeout` is the total SDK call budget
 across transparent transport reattachments. Zero waits indefinitely.
-Temporal permits 10 in-flight Updates and 2,000 total Updates in History per
-Workflow Execution. A caller timeout or cancellation does not finish an
-accepted durable wait, so an abandoned handler can retain one in-flight slot.
-Set `internal_handler_timeout` only when abandoned waits can approach that
-limit. An active call transparently starts another generation, which counts
-toward the 2,000-Update history limit. Prefer a value comfortably longer than
+A caller timeout or cancellation does not finish an accepted durable wait. Set `internal_handler_timeout` only when abandoned waits can accumulate. An active call transparently registers its wait again. Prefer a value comfortably longer than
 normal request timeouts and reconnect gaps. Zero disables timed rollover.
 Request expiry raises `RequestTimeoutError`.
 
@@ -701,7 +696,7 @@ SubFlow.
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
 (`describe_flow`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
-waits, config updates, and continue-as-new triggers raise
+waits, config updates, and state-transfer triggers raise
 `FlowNotActiveOrNotFoundError` when no running Flow can accept the operation.
 
 RPCs also use this error when the target Flow cannot be found, including query-only
@@ -794,8 +789,8 @@ environment:
 ./run-integration-tests.sh
 ```
 
-Set `DEX_INTEG_WORKER_MODE=pull` to run the suite with pull Workers instead of
-listening Workers. The default is `push`.
+The suite uses server-zd and pull Workers. `DEX_INTEG_ENGINE=zd` remains accepted.
+Set `DEX_SERVER_ZD_BINARY` to reuse a built `dex-server-zd`.
 
 ### Measure integration coverage
 
@@ -868,9 +863,9 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo ta
 ## Server protocol compatibility
 
 Both `Worker` and `AsyncWorker` call `GetServerInfo`, negotiate the highest
-common protocol, synchronize Attribute indexes, and only then bind
-WorkerService. The initial Python SDK interval is `[1,1]`. Missing information,
-invalid or disjoint intervals, and RPC failures stop startup before binding.
+common protocol, synchronize Attribute indexes, and only then open outbound
+task streams. The initial Python SDK interval is `[1,1]`. Missing information,
+invalid or disjoint intervals, and RPC failures stop startup before polling.
 The current Python SDK interval is `[1,3]`. Protocol 3 adds hard-delete
 Attributes. Workers record the negotiated version at startup and reject each
 handler result that contains a hard-delete Attribute write when it is below 3.
@@ -888,7 +883,7 @@ original terms as described in [LEGACY_NOTICES.md](LEGACY_NOTICES.md).
 
 ## Search run inclusion
 
-Dex Server excludes ContinuedAsNew runs by default. Application queries still
+Searches exclude runs with the ContinuedAsNew status by default. server-zd never reports that status. Application queries still
 need `FlowType` when using shared index slots. An explicit inclusion option
 removes only the default exclusion; it does not override query filters. Keep
 the query, inclusion option, and page size consistent across pages.

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/README.md

@@ -79,14 +79,17 @@ retain up to four idle credential threads. Sync token lookup must return
 promptly. By default, no authorization metadata is sent. Dex uses plaintext
 gRPC, so protect the network path that carries the token.
 
-## Pull mode
+## Workers
 
-Set `WorkerOptions.pull` to run a `Worker` or `AsyncWorker` with outbound task
-streams. The Worker connects to the Dex server through `server_address` and
-does not open a listener. Advertise `worker.worker_target` through
-`ClientOptions.worker_target`. A single Flow can override the Client default
-with `StartFlowOptions(config_override=FlowConfig(worker_target=...))`; a
-SubFlow can use `SubFlowOptions` with the same `FlowConfig` override.
+Workers receive tasks through outbound pull streams. `Worker` and `AsyncWorker`
+need only an outbound connection to the Dex Server at `server_address`. Configure
+capacity and shutdown with `WorkerOptions.pull`; its default is
+`PullWorkerOptions()`. Clients and Flows use pull routing automatically.
+
+StartFlow and SubFlow always select pull Workers. Updating Flow configuration
+preserves its existing Worker target; an empty `FlowConfig()` changes nothing.
+Before upgrading an application with active push Flows, use an SDK version that
+supports Worker targets to migrate those Flows to pull routing.
 
 ```python
 import threading
@@ -102,10 +105,11 @@ worker = Worker(
 )
 worker_thread = threading.Thread(target=worker.start)
 worker_thread.start()
+worker.wait_pull_registered(timeout=30)
 client = Client(
     registry,
     cache,
-    ClientOptions(server_address="dex.example:8801", worker_target=worker.worker_target),
+    ClientOptions(server_address="dex.example:8801"),
 )
 try:
     client.start_flow(flow, flow_id, input_value)
@@ -144,10 +148,7 @@ The generated `app_worker_id` uses the first nonempty `DEX_WORKER_INSTANCE`,
 `POD_NAME`, `HOSTNAME`, or system hostname, plus eight random base32 characters.
 An override must uniquely identify one Worker process and change after restart.
 It must contain 1-63 ASCII letters, digits, dots, underscores, or hyphens and
-must not equal a registered Flow type. Pull mode cannot configure a bind address
-or an advertised address or headless target. Use `WorkerTarget(pull=True)` for
-Client defaults or Flow overrides when the Worker target is not directly in
-scope.
+must not equal a registered Flow type.
 
 Pull streams reconnect after failures. A server-directed reconnect waits for
 an active task to finish, then waits up to `stop_drain_timeout` for the server
@@ -170,7 +171,7 @@ Worker ID queue to register at least once. Timeout raises `TimeoutError`;
 async cancellation cancels only that wait. Startup failures reach waiters.
 A permanent rejection before readiness raises `PullRegistrationError`, whose
 `queue` and `error` identify the rejected queue and original transport error.
-Listening mode and stop before readiness raise `RuntimeError`.
+Stopping before readiness raises `RuntimeError`.
 
 Use `worker.pull_registration_state()` for subsequent readiness probes. Its
 immutable `queues` expose `queue`, `has_registered_stream`, and
@@ -224,7 +225,6 @@ to distinguish reserve pressure from full-capacity rejections. The count exclude
 full-capacity rejections and unknown names. It counts decline events, including
 repeated declines of the same Step dispatch while Dex retries it. Read its rate
 to assess reserve pressure. It never resets and remains available after shutdown.
-Listening Workers return zero.
 
 ## Flow state I/O
 
@@ -382,7 +382,7 @@ explicit codec only for a custom encoding or a type Registry cannot derive.
 partitions them by definition type.
 
 `Worker` and `AsyncWorker` synchronize all registered Indexed Attributes with
-Dex Server before opening their listener. Existing indexes return immediately;
+Dex Server before opening outbound task streams. Existing indexes return immediately;
 failure or the default two-minute deadline aborts startup. An indexed
 `AttributeMap` must provide one fixed `index_key`.
 
@@ -603,9 +603,9 @@ options = dex.StartFlowOptions(
 ```
 
 Register async hooks with `allow_async_handlers=True` and run them with
-`AsyncWorker`. `FAIL` produces `FlowErrorType.FLOW_TIMEOUT` and permits Flow
-retry; `CANCEL` cancels without retry. Continue-as-new preserves the deadline,
-while retry runs receive a fresh budget. A zero or absent timeout
+`AsyncWorker`. `FAIL` produces `FlowErrorType.FLOW_TIMEOUT` and fails the
+Flow; `CANCEL` cancels it. The deadline is preserved across Flow state
+transfers. A zero or absent timeout
 disables the feature.
 
 `Registry` validates every Flow, Step, RPC signature, durable name, lock, and
@@ -635,12 +635,7 @@ Request IDs are optional for both durable waits. When omitted, the server
 derives a stable ID from the Step execution or Attribute condition. Reuse an
 override only for the same wait. `request_timeout` is the total SDK call budget
 across transparent transport reattachments. Zero waits indefinitely.
-Temporal permits 10 in-flight Updates and 2,000 total Updates in History per
-Workflow Execution. A caller timeout or cancellation does not finish an
-accepted durable wait, so an abandoned handler can retain one in-flight slot.
-Set `internal_handler_timeout` only when abandoned waits can approach that
-limit. An active call transparently starts another generation, which counts
-toward the 2,000-Update history limit. Prefer a value comfortably longer than
+A caller timeout or cancellation does not finish an accepted durable wait. Set `internal_handler_timeout` only when abandoned waits can accumulate. An active call transparently registers its wait again. Prefer a value comfortably longer than
 normal request timeouts and reconnect gaps. Zero disables timed rollover.
 Request expiry raises `RequestTimeoutError`.
 
@@ -685,7 +680,7 @@ SubFlow.
 Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
 (`describe_flow`, `wait_for_flow`, and `time_travel`) raise
 `FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
-waits, config updates, and continue-as-new triggers raise
+waits, config updates, and state-transfer triggers raise
 `FlowNotActiveOrNotFoundError` when no running Flow can accept the operation.
 
 RPCs also use this error when the target Flow cannot be found, including query-only
@@ -778,8 +773,8 @@ environment:
 ./run-integration-tests.sh
 ```
 
-Set `DEX_INTEG_WORKER_MODE=pull` to run the suite with pull Workers instead of
-listening Workers. The default is `push`.
+The suite uses server-zd and pull Workers. `DEX_INTEG_ENGINE=zd` remains accepted.
+Set `DEX_SERVER_ZD_BINARY` to reuse a built `dex-server-zd`.
 
 ### Measure integration coverage
 
@@ -852,9 +847,9 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo ta
 ## Server protocol compatibility
 
 Both `Worker` and `AsyncWorker` call `GetServerInfo`, negotiate the highest
-common protocol, synchronize Attribute indexes, and only then bind
-WorkerService. The initial Python SDK interval is `[1,1]`. Missing information,
-invalid or disjoint intervals, and RPC failures stop startup before binding.
+common protocol, synchronize Attribute indexes, and only then open outbound
+task streams. The initial Python SDK interval is `[1,1]`. Missing information,
+invalid or disjoint intervals, and RPC failures stop startup before polling.
 The current Python SDK interval is `[1,3]`. Protocol 3 adds hard-delete
 Attributes. Workers record the negotiated version at startup and reject each
 handler result that contains a hard-delete Attribute write when it is below 3.
@@ -872,7 +867,7 @@ original terms as described in [LEGACY_NOTICES.md](LEGACY_NOTICES.md).
 
 ## Search run inclusion
 
-Dex Server excludes ContinuedAsNew runs by default. Application queries still
+Searches exclude runs with the ContinuedAsNew status by default. server-zd never reports that status. Application queries still
 need `FlowType` when using shared index slots. An explicit inclusion option
 removes only the default exclusion; it does not override query filters. Keep
 the query, inclusion option, and page size consistent across pages.

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/dex/__init__.py

@@ -124,7 +124,7 @@ from dex.timer import Timer
 from dex.wait import Wait
 from dex.wait_options import WaitForAttributeOptions, WaitForStepCompletionOptions
 from dex.worker import Worker
-from dex.worker_options import PullWorkerOptions, WorkerOptions, WorkerTarget
+from dex.worker_options import PullWorkerOptions, WorkerOptions
 
 __all__ = [
     "BOOL",
@@ -226,7 +226,6 @@ __all__ = [
     "Worker",
     "WorkerInvocationError",
     "WorkerOptions",
-    "WorkerTarget",
     "PullWorkerOptions",
     "PullRegistrationError",
     "PullRegistrationState",

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/dex/_grpc_errors.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import traceback
 from dataclasses import dataclass
-from typing import Any, Literal, cast
+from typing import Literal, cast
 
 import grpc
 from google.protobuf import any_pb2
@@ -165,23 +165,6 @@ def _worker_code(details: pb.ServiceErrorResponse | None) -> grpc.StatusCode | N
     )
 
 
-def abort_worker_error(
-    context: grpc.ServicerContext,
-    error: BaseException,
-) -> None:
-    context.abort_with_status(rpc_status.to_status(_worker_error_status(error)))
-
-
-async def async_abort_worker_error(
-    context: grpc.aio.ServicerContext[Any, Any],
-    error: BaseException,
-) -> None:
-    # types-grpcio on 3.11 omits aio abort_with_status; runtime provides it.
-    await cast(Any, context).abort_with_status(
-        rpc_status.to_status(_worker_error_status(error))
-    )
-
-
 def _worker_error_status(error: BaseException) -> status_pb2.Status:
     retry_after_error: RetryAfterError | None = None
     reported = error

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/dex/_pull_worker.py

@@ -805,6 +805,21 @@ class PullStream:
         async with self._send_lock:
             if request.HasField("task_frame"):
                 frame = request.task_frame
+                is_progress_frame = (
+                    frame.HasField("wait_for")
+                    and frame.wait_for.WhichOneof("output")
+                    in ("heartbeat", "stream_write")
+                    or frame.HasField("execute")
+                    and frame.execute.WhichOneof("output")
+                    in ("heartbeat", "stream_write")
+                )
+                if (
+                    frame.task_id != self.task_id
+                    or self._is_final_frame_sent
+                    or not self._active.is_set()
+                    and is_progress_frame
+                ):
+                    return
                 if (
                     frame.HasField("rpc")
                     or frame.HasField("worker_error")

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/dex/_worker_dispatcher.py

@@ -711,6 +711,9 @@ class WorkerDispatcher:
             mapped.flow_config_override.CopyFrom(
                 self._map_sub_flow_config(options.config_override)
             )
+        mapped.flow_config_override.worker_target.CopyFrom(
+            pb.WorkerTarget(is_pull_mode=True)
+        )
         return mapped
 
     def _result_attribute_writes(
@@ -761,14 +764,7 @@ class WorkerDispatcher:
                 StepDurability.SYNC: pb.STEP_DURABILITY_SYNC,
                 StepDurability.ASYNC: pb.STEP_DURABILITY_ASYNC,
             }[config.step_durability]
-        if config.worker_target is not None:
-            mapped.worker_target.CopyFrom(
-                pb.WorkerTarget(
-                    address=config.worker_target.address,
-                    is_headless_address=config.worker_target.headless,
-                    is_pull_mode=config.worker_target.pull,
-                )
-            )
+        mapped.worker_target.CopyFrom(pb.WorkerTarget(is_pull_mode=True))
         if config.attribute_store_names is not None:
             mapped.attribute_store_names.CopyFrom(
                 pb.AttributeStoreNames(names=config.attribute_store_names)

{dex_python_sdk-1.23.0 → dex_python_sdk-1.26.0}/dex/async_client.py

@@ -107,7 +107,7 @@ class AsyncClient:
         Args:
             registry: The Flow Registry used for validation and codecs.
             blob_cache: An open cache used for asynchronous hydration.
-            options: Service address, default Worker target, and bearer credential;
+            options: Service address and bearer credential;
                 ``None`` uses defaults and sends no authorization metadata.
         """
         self.registry = registry
@@ -1038,7 +1038,11 @@ class AsyncClient:
                 raise
 
     async def update_flow_config(self, flow_id: str, config: FlowConfig) -> None:
-        """Replace mutable configuration for an active Flow.
+        """Update specified mutable configuration fields for an active Flow.
+
+        The update affects later decisions and does not recall work already
+        dispatched. Unspecified fields and the existing Worker target remain
+        unchanged. An empty ``FlowConfig()`` leaves all configuration unchanged.
 
         Args:
             flow_id: The non-empty active Flow ID.
@@ -1193,13 +1197,12 @@ class AsyncClient:
             _apply_attribute_store_sync(write, definition)
             _apply_hard_delete_on_null(write, definition)
             mapped.attributes.append(write)
-        if (
-            options.config_override is not None
-            or self.options.worker_target is not None
-        ):
-            mapped.flow_config_override.CopyFrom(
-                self._map_flow_config(options.config_override)
-            )
+        mapped.flow_config_override.CopyFrom(
+            self._map_flow_config(options.config_override)
+        )
+        mapped.flow_config_override.worker_target.CopyFrom(
+            pb.WorkerTarget(is_pull_mode=True)
+        )
         return mapped
 
     def _map_flow_config(self, config: FlowConfig | None) -> pb.FlowConfig:
@@ -1236,19 +1239,6 @@ class AsyncClient:
                 mapped.attribute_store_names.CopyFrom(
                     pb.AttributeStoreNames(names=config.attribute_store_names)
                 )
-        target = (
-            config.worker_target
-            if config is not None and config.worker_target is not None
-            else self.options.worker_target
-        )
-        if target is not None:
-            mapped.worker_target.CopyFrom(
-                pb.WorkerTarget(
-                    address=target.address,
-                    is_headless_address=target.headless,
-                    is_pull_mode=target.pull,
-                )
-            )
         return mapped
 
     @staticmethod