dex-python-sdk 0.8.0__tar.gz → 0.11.0__tar.gz

{dex_python_sdk-0.8.0 → dex_python_sdk-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.8.0
+Version: 0.11.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -560,6 +560,17 @@ The dispatch `version` input is stamped the same way as a release tag.
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo tag conventions.
 
+## 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.
+
+The diagnostic SDK version comes from Python distribution metadata for
+`dex-python-sdk` and falls back to `dev` when the distribution is unavailable.
+It does not affect protocol compatibility.
+
 ## License
 
 [Sustainable Use License 1.0](LICENSE), with legacy portions under their

{dex_python_sdk-0.8.0 → dex_python_sdk-0.11.0}/README.md

@@ -544,6 +544,17 @@ The dispatch `version` input is stamped the same way as a release tag.
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md#releases-monorepo-tags) for monorepo tag conventions.
 
+## 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.
+
+The diagnostic SDK version comes from Python distribution metadata for
+`dex-python-sdk` and falls back to `dev` when the distribution is unavailable.
+It does not affect protocol compatibility.
+
 ## License
 
 [Sustainable Use License 1.0](LICENSE), with legacy portions under their

dex_python_sdk-0.11.0/dex/_server_protocol.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+import grpc
+
+from dex.dexpb import dex_pb2 as pb
+
+MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION = 1
+MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION = 1
+
+
+def sdk_version() -> str:
+    try:
+        return version("dex-python-sdk")
+    except PackageNotFoundError:
+        return "dev"
+
+
+def negotiate_server_protocol(server_info: pb.ServerInfo, artifact_version: str) -> int:
+    server_minimum = server_info.minimum_supported_protocol_version
+    server_current = server_info.current_protocol_version
+    if (
+        MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION == 0
+        or MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION == 0
+        or MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION
+        > MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION
+    ):
+        raise _compatibility_error(
+            artifact_version,
+            server_info.server_version,
+            server_minimum,
+            server_current,
+            "Python SDK protocol interval is invalid",
+        )
+    if server_minimum == 0 or server_current == 0 or server_minimum > server_current:
+        raise _compatibility_error(
+            artifact_version,
+            server_info.server_version,
+            server_minimum,
+            server_current,
+            "Server protocol interval is invalid",
+        )
+    negotiated = min(server_current, MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION)
+    if (
+        negotiated < server_minimum
+        or negotiated < MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION
+    ):
+        raise _compatibility_error(
+            artifact_version,
+            server_info.server_version,
+            server_minimum,
+            server_current,
+            "protocol intervals do not overlap",
+        )
+    return negotiated
+
+
+def server_info_request_error(
+    artifact_version: str, failure: grpc.RpcError
+) -> RuntimeError:
+    return RuntimeError(
+        f'Python SDK version "{artifact_version}" protocol '
+        f"[{MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION},"
+        f"{MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION}] is incompatible "
+        'with Server version "unknown" protocol [unknown,unknown]: '
+        f"GetServerInfo failed: {failure}"
+    )
+
+
+def _compatibility_error(
+    artifact_version: str,
+    server_version: str,
+    server_minimum: int,
+    server_current: int,
+    reason: str,
+) -> RuntimeError:
+    displayed_server_version = server_version or "unknown"
+    return RuntimeError(
+        f'Python SDK version "{artifact_version}" protocol '
+        f"[{MINIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION},"
+        f"{MAXIMUM_SUPPORTED_SERVER_PROTOCOL_VERSION}] is incompatible with "
+        f'Server version "{displayed_server_version}" protocol '
+        f"[{server_minimum},{server_current}]: {reason}"
+    )

{dex_python_sdk-0.8.0 → dex_python_sdk-0.11.0}/dex/async_client.py

@@ -254,13 +254,18 @@ class AsyncClient:
         """Invoke a registered RPC and await its typed result.
 
         Pass the bound method from the registered Flow instance. RPC timeout and
-        Attribute locks come from ``@rpc`` configuration.
+        Attribute locks come from ``@rpc`` configuration. A non-transactional RPC
+        without Attribute locks starts from a backend query. If the handler returns no
+        durable effects, a retained terminal execution can serve that query. Locks,
+        transactional execution, returned effects, or server policy can require an
+        active execution.
 
         Args:
             rpc_method: A bound method decorated with ``@rpc``.
             flow_id: The non-empty target Flow ID.
             input: The annotated input, or ``None`` for an input-free RPC.
-            run_id: Optional exact run; ``""`` targets the active run.
+            run_id: Optional exact run. With ``""``, the server resolves the current
+                execution.
 
         Returns:
             The decoded ``RPCResult.output``, or ``None`` for a no-output RPC.
@@ -270,7 +275,8 @@ class AsyncClient:
             RpcLockConflictError: If Attribute locks cannot be acquired.
             WorkerInvocationError: If the application handler fails.
             ValueMappingError: If input or output mapping fails.
-            DexServiceError: If the Flow is inactive or the service call fails.
+            DexServiceError: If the selected path requires an active execution or the
+                service call otherwise fails.
         """
         _, rpc = self.registry._rpc_for_method(rpc_method)
         encoded_input = (

{dex_python_sdk-0.8.0 → dex_python_sdk-0.11.0}/dex/async_worker.py

@@ -12,7 +12,13 @@ import asyncio
 from types import TracebackType
 
 import grpc
+from google.protobuf import empty_pb2
 
+from dex._server_protocol import (
+    negotiate_server_protocol,
+    sdk_version,
+    server_info_request_error,
+)
 from dex._async_value_hydrator import AsyncValueHydrator
 from dex._async_worker_dispatcher import AsyncWorkerDispatcher
 from dex._async_worker_service import AsyncWorkerService
@@ -64,6 +70,8 @@ class AsyncWorker:
         self._flow_service = dex_pb2_grpc.FlowServiceStub(  # type: ignore[no-untyped-call]
             self._flow_channel
         )
+        self._sdk_version = sdk_version()
+        self._negotiated_protocol_version = 0
         values = ValueMapper(registry.codec_registry)
         dispatcher = AsyncWorkerDispatcher(
             registry,
@@ -116,7 +124,7 @@ class AsyncWorker:
         await self.close()
 
     async def start(self) -> None:
-        """Synchronize Attribute indexes, serve WorkerService, and await shutdown.
+        """Negotiate protocol, synchronize Attribute indexes, and serve.
 
         ``start`` may be awaited exactly once. It contacts FlowService before binding
         and completes only after ``stop`` terminates the server.
@@ -126,6 +134,26 @@ class AsyncWorker:
         """
         if self._state != "created":
             raise RuntimeError(f"AsyncWorker cannot start from state {self._state}")
+        try:
+            server_info = await self._flow_service.GetServerInfo(
+                empty_pb2.Empty(),
+                timeout=self.options.attribute_index_sync_timeout.total_seconds(),
+            )
+        except grpc.RpcError as failure:
+            self._state = "stopped"
+            await self._flow_channel.close(None)
+            self._stopped.set()
+            raise server_info_request_error(self._sdk_version, failure) from failure
+        try:
+            self._negotiated_protocol_version = negotiate_server_protocol(
+                server_info,
+                self._sdk_version,
+            )
+        except RuntimeError:
+            self._state = "stopped"
+            await self._flow_channel.close(None)
+            self._stopped.set()
+            raise
         try:
             await self._flow_service.SyncAttributeIndexes(
                 pb.SyncAttributeIndexRequest(

{dex_python_sdk-0.8.0 → dex_python_sdk-0.11.0}/dex/client.py

@@ -250,17 +250,21 @@ class Client:
         *,
         run_id: str = "",
     ) -> Any:
-        """Synchronously invoke a registered RPC on an active Flow.
+        """Synchronously invoke a registered RPC on a Flow execution.
 
         Pass the bound method from the same registered Flow instance. RPC timeout and
         Attribute locks come from its ``@rpc`` decorator. The call blocks until the
-        handler returns, fails, or times out.
+        handler returns, fails, or times out. A non-transactional RPC without Attribute
+        locks starts from a backend query. If the handler returns no durable effects, a
+        retained terminal execution can serve that query. Locks, transactional execution,
+        returned effects, or server policy can require an active execution.
 
         Args:
             rpc_method: A bound method decorated with ``@rpc``.
             flow_id: The non-empty target Flow ID.
             input: The annotated RPC input, or ``None`` for an input-free RPC.
-            run_id: Optional exact run; ``""`` targets the active run.
+            run_id: Optional exact run. With ``""``, the server resolves the current
+                execution.
 
         Returns:
             The decoded ``RPCResult.output``, or ``None`` for a no-output RPC.
@@ -270,7 +274,8 @@ class Client:
             RpcLockConflictError: If requested Attribute locks cannot be acquired.
             WorkerInvocationError: If the application handler fails.
             ValueMappingError: If input or output mapping fails.
-            DexServiceError: If the Flow is inactive or the service call fails.
+            DexServiceError: If the selected path requires an active execution or the
+                service call otherwise fails.
         """
         _, rpc = self.registry._rpc_for_method(rpc_method)
         encoded_input = (