prefect-client 3.8.1.dev4__tar.gz → 3.8.2__tar.gz

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.8.1.dev4
+Version: 3.8.2
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: <3.15,>=3.10
 Requires-Dist: amplitude-analytics<2.0.0,>=1.2.1
-Requires-Dist: anyio!=4.14.2,<5.0.0,>=4.4.0
+Requires-Dist: anyio<5.0.0,>=4.4.0
 Requires-Dist: asgi-lifespan<3.0,>=1.0
 Requires-Dist: cachetools<8.0,>=5.3
 Requires-Dist: cloudpickle<4.0,>=2.0

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
 dependencies = [
     # Client dependencies
     "amplitude-analytics>=1.2.1,<2.0.0",
-    "anyio>=4.4.0,<5.0.0,!=4.14.2",
+    "anyio>=4.4.0,<5.0.0",
     "asgi-lifespan>=1.0,<3.0",
     "cachetools>=5.3,<8.0",
     "cloudpickle>=2.0,<4.0",

prefect_client-3.8.2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.2"
+__build_date__ = "2026-08-07 21:16:33.823431+00:00"
+__git_commit__ = "b535a27ea1b567bd0363b94617fc2502a56d23c8"
+__dirty__ = False

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/_internal/concurrency/services.py

@@ -408,10 +408,21 @@ class FutureQueueService(
             # If the request to the increment endpoint fails in a non-standard
             # way, we need to set the future's result so it'll be re-raised in
             # the context of the caller.
-            future.set_exception(exc)
+            if future.set_running_or_notify_cancel():
+                future.set_exception(exc)
             raise exc
         else:
-            future.set_result(response)
+            # Transitioning the future to running before setting its result closes
+            # the window where the caller cancels it while `acquire` is in flight:
+            # after this point `cancel()` fails, and if the caller got there first
+            # the acquired resource is nobody's and must be discarded.
+            if future.set_running_or_notify_cancel():
+                future.set_result(response)
+            else:
+                await self._discard(response)
+
+    async def _discard(self, response: R) -> None:
+        """Dispose of a result whose caller is no longer waiting for it."""
 
     @abc.abstractmethod
     async def acquire(self, *args: Unpack[Ts]) -> R:

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/_internal/control_listener.py

@@ -13,7 +13,7 @@ Protocol:
    one-shot env vars without connecting yet.
 3. The outermost `capture_sigterm()` calls `start()`, which connects back to
    the runner and spawns a daemon thread blocked on the socket.
-4. The runner writes a single-byte intent (`b"c"` today).
+4. The runner writes a single-byte intent (`b"c"`, `b"r"` or `b"q"`).
 5. If Prefect still owns the live SIGTERM bridge, the child writes `b"a"`,
    commits the intent for engine dispatch, and on Windows triggers
    `_thread.interrupt_main(SIGTERM)`.
@@ -37,10 +37,12 @@ from typing import Literal
 
 from prefect.utilities.engine import commit_control_intent_and_ack
 
-Intent = Literal["cancel"]
+Intent = Literal["cancel", "reschedule", "relinquish"]
 
 _INTENT_FOR_BYTE: dict[bytes, Intent] = {
     b"c": "cancel",
+    b"r": "reschedule",
+    b"q": "relinquish",
 }
 
 _intent: Intent | None = None

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/_internal/observers.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
 import asyncio
+import logging
+import time
 import uuid
 from contextlib import AsyncExitStack
+from datetime import datetime
 from typing import Any, Protocol
 
 from prefect._flow_run_suspension import is_suspended_flow_run_state
@@ -17,9 +20,16 @@ from prefect.client.schemas.filters import (
 from prefect.client.schemas.objects import State, StateType
 from prefect.events.clients import PrefectEventSubscriber, get_events_subscriber
 from prefect.events.filters import EventFilter, EventNameFilter
+from prefect.exceptions import ObjectNotFound
 from prefect.logging.loggers import get_logger
 from prefect.utilities.services import critical_service_loop
 
+# How long to wait before warning that a suspension state is still unavailable,
+# how often to look initially, and the retry cap after the warning.
+SUSPENSION_CONFIRMATION_WARNING_AFTER = 30.0
+SUSPENSION_CONFIRMATION_INTERVAL = 0.5
+SUSPENSION_CONFIRMATION_MAX_INTERVAL = 10.0
+
 
 class OnCancellingCallback(Protocol):
     def __call__(self, flow_run_id: uuid.UUID) -> None: ...
@@ -33,6 +43,133 @@ class OnFailureCallback(Protocol):
     def __call__(self, flow_run_ids: set[uuid.UUID]) -> None: ...
 
 
+class _SuspensionWatch:
+    """Reconcile suspension events with durable states for one flow run."""
+
+    def __init__(
+        self,
+        flow_run_id: uuid.UUID,
+        client: PrefectClient,
+        on_suspended: OnSuspendedCallback,
+        logger: logging.Logger,
+    ) -> None:
+        self.flow_run_id = flow_run_id
+        self.is_suspended = False
+        self._client = client
+        self._on_suspended = on_suspended
+        self._logger = logger
+        self._initialized = asyncio.Event()
+        self._replay_checkpoint: datetime | None = None
+        self._confirmation_tasks: dict[uuid.UUID, asyncio.Task[None]] = {}
+        self._closed = False
+
+    def initialize(self, state: State | None) -> None:
+        """Set the initial server checkpoint and release waiting events."""
+        if not self._initialized.is_set():
+            self._replay_checkpoint = state.timestamp if state is not None else None
+            self._initialized.set()
+        self.notify_if_suspended(state)
+
+    def notify_if_suspended(self, state: State | None) -> None:
+        if (
+            not self.is_suspended
+            and state is not None
+            and is_suspended_flow_run_state(state)
+        ):
+            self.is_suspended = True
+            self._on_suspended(self.flow_run_id, state)
+
+    def observe(self, state_id: uuid.UUID, occurred: datetime) -> None:
+        """Confirm a new suspension event without blocking event consumption."""
+        if self._closed or self.is_suspended:
+            return
+        if state_id in self._confirmation_tasks:
+            return
+
+        task = asyncio.create_task(self._confirm(state_id, occurred))
+        self._confirmation_tasks[state_id] = task
+        task.add_done_callback(
+            lambda completed, state_id=state_id: self._confirmation_done(
+                state_id, completed
+            )
+        )
+
+    async def _confirm(self, state_id: uuid.UUID, occurred: datetime) -> None:
+        await self._initialized.wait()
+        if self._closed or self.is_suspended:
+            return
+        if self._replay_checkpoint is not None and occurred <= self._replay_checkpoint:
+            self._logger.debug(
+                "Ignoring replayed suspension event for flow run %s that occurred"
+                " at or before the initial server state.",
+                self.flow_run_id,
+            )
+            return
+
+        warning_deadline = time.monotonic() + SUSPENSION_CONFIRMATION_WARNING_AFTER
+        retry_interval = SUSPENSION_CONFIRMATION_INTERVAL
+        warned = False
+        last_error: Exception | None = None
+
+        while not self._closed and not self.is_suspended:
+            try:
+                state = await self._client.read_flow_run_state(state_id)
+            except ObjectNotFound:
+                pass
+            except Exception as exc:
+                last_error = exc
+            else:
+                if state.state_details.flow_run_id not in (None, self.flow_run_id):
+                    self._logger.warning(
+                        "Suspension event for flow run %s referred to state %s owned"
+                        " by flow run %s.",
+                        self.flow_run_id,
+                        state_id,
+                        state.state_details.flow_run_id,
+                    )
+                    return
+                self.notify_if_suspended(state)
+                return
+
+            if not warned and time.monotonic() >= warning_deadline:
+                self._logger.warning(
+                    "Received a suspension event for flow run %s, but state %s has"
+                    " not become readable within %s seconds; continuing to retry.",
+                    self.flow_run_id,
+                    state_id,
+                    SUSPENSION_CONFIRMATION_WARNING_AFTER,
+                    exc_info=last_error,
+                )
+                warned = True
+
+            await asyncio.sleep(retry_interval)
+            if warned:
+                retry_interval = min(
+                    max(retry_interval * 2, SUSPENSION_CONFIRMATION_INTERVAL),
+                    SUSPENSION_CONFIRMATION_MAX_INTERVAL,
+                )
+
+    def _confirmation_done(self, state_id: uuid.UUID, task: asyncio.Task[None]) -> None:
+        self._confirmation_tasks.pop(state_id, None)
+        if task.cancelled():
+            return
+        if error := task.exception():
+            self._logger.error(
+                "Suspension confirmation failed for flow run %s and state %s.",
+                self.flow_run_id,
+                state_id,
+                exc_info=error,
+            )
+
+    def cancel(self) -> tuple[asyncio.Task[None], ...]:
+        self._closed = True
+        tasks = tuple(self._confirmation_tasks.values())
+        self._confirmation_tasks.clear()
+        for task in tasks:
+            task.cancel()
+        return tasks
+
+
 class FlowRunCancellingObserver:
     def __init__(
         self,
@@ -283,35 +420,59 @@ class FlowRunSuspendingObserver:
             self._event_filter = EventFilter(
                 event=EventNameFilter(name=["prefect.flow-run.Suspended"])
             )
-        self._in_flight_flow_run_ids: set[uuid.UUID] = set()
         self._events_subscriber: PrefectEventSubscriber | None
         self._exit_stack = AsyncExitStack()
         self._consumer_task: asyncio.Task[None] | None = None
         self._polling_task: asyncio.Task[None] | None = None
         self._is_shutting_down = False
         self._client: PrefectClient | None = None
-        self._suspended_flow_run_ids: set[uuid.UUID] = set()
+        self._watches: dict[uuid.UUID, _SuspensionWatch] = {}
+
+    @property
+    def _in_flight_flow_run_ids(self) -> set[uuid.UUID]:
+        return set(self._watches)
 
     def add_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
         self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
-        self._in_flight_flow_run_ids.add(flow_run_id)
+        if flow_run_id not in self._watches:
+            watch = self._watches[flow_run_id] = self._create_watch(flow_run_id)
+            watch.initialize(None)
+
+    def _create_watch(self, flow_run_id: uuid.UUID) -> _SuspensionWatch:
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+        return _SuspensionWatch(
+            flow_run_id=flow_run_id,
+            client=self._client,
+            on_suspended=self.on_suspended,
+            logger=self.logger,
+        )
 
     def remove_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
         self.logger.debug("Removing in-flight flow run ID: %s", flow_run_id)
-        self._in_flight_flow_run_ids.discard(flow_run_id)
-        self._suspended_flow_run_ids.discard(flow_run_id)
+        if watch := self._watches.pop(flow_run_id, None):
+            watch.cancel()
 
     async def watch_flow_run_id(self, flow_run_id: uuid.UUID) -> None:
-        self.add_in_flight_flow_run_id(flow_run_id)
         if self._client is None:
             raise RuntimeError(
                 "Client not initialized. Please use `async with` to initialize the observer."
             )
+        self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
+        if flow_run_id not in self._watches:
+            self._watches[flow_run_id] = self._create_watch(flow_run_id)
         retry_interval = max(min(self.polling_interval, 1.0), 0.01)
         attempts = 0
 
         while not self._is_shutting_down:
-            if flow_run_id in self._suspended_flow_run_ids:
+            watch = self._watches.get(flow_run_id)
+            if watch is None or watch.is_suspended:
                 return
 
             try:
@@ -328,26 +489,14 @@ class FlowRunSuspendingObserver:
                 await asyncio.sleep(retry_interval)
                 continue
 
-            self._notify_if_suspended_state(flow_run_id, flow_run.state)
+            watch.initialize(flow_run.state)
             return
 
     def _notify_if_suspended_state(
         self, flow_run_id: uuid.UUID, state: State | None
     ) -> None:
-        if state is not None and is_suspended_flow_run_state(state):
-            self._suspended_flow_run_ids.add(flow_run_id)
-            self.on_suspended(flow_run_id, state)
-
-    async def _notify_if_suspended(self, flow_run_id: uuid.UUID) -> None:
-        if self._client is None:
-            raise RuntimeError(
-                "Client not initialized. Please use `async with` to initialize the observer."
-            )
-        if flow_run_id in self._suspended_flow_run_ids:
-            return
-
-        flow_run = await self._client.read_flow_run(flow_run_id)
-        self._notify_if_suspended_state(flow_run_id, flow_run.state)
+        if watch := self._watches.get(flow_run_id):
+            watch.notify_if_suspended(state)
 
     async def _consume_events(self):
         if self._events_subscriber is None:
@@ -361,9 +510,14 @@ class FlowRunSuspendingObserver:
                         "prefect.flow-run.", ""
                     )
                 )
-                if flow_run_id not in self._in_flight_flow_run_ids:
+                watch = self._watches.get(flow_run_id)
+                if watch is None:
                     continue
-                await self._notify_if_suspended(flow_run_id)
+
+                # State change events carry the ID of the state they report, so the
+                # event identifies the exact transition to confirm. Confirmation is
+                # done in a separate task to keep consuming events while we wait.
+                watch.observe(event.id, event.occurred)
             except ValueError:
                 self.logger.warning(
                     "Received event with invalid flow run ID: %s",
@@ -412,7 +566,11 @@ class FlowRunSuspendingObserver:
                 "Client not initialized. Please use `async with` to initialize the observer."
             )
 
-        flow_run_ids = self._in_flight_flow_run_ids - self._suspended_flow_run_ids
+        flow_run_ids = {
+            flow_run_id
+            for flow_run_id, watch in self._watches.items()
+            if not watch.is_suspended
+        }
         if not flow_run_ids:
             return
 
@@ -434,8 +592,7 @@ class FlowRunSuspendingObserver:
 
         for flow_run in suspended_flow_runs:
             if flow_run.state:
-                self._suspended_flow_run_ids.add(flow_run.id)
-                self.on_suspended(flow_run.id, flow_run.state)
+                self._notify_if_suspended_state(flow_run.id, flow_run.state)
 
     async def __aenter__(self):
         try:
@@ -470,6 +627,10 @@ class FlowRunSuspendingObserver:
     async def __aexit__(self, *exc_info: Any):
         self.logger.debug("Shutting down FlowRunSuspendingObserver")
         self._is_shutting_down = True
+        tasks = [task for watch in self._watches.values() for task in watch.cancel()]
+        self._watches.clear()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
         await self._exit_stack.__aexit__(*exc_info)
         if self._consumer_task is not None:
             self._consumer_task.cancel()

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/_internal/websockets.py

@@ -14,6 +14,8 @@ from urllib.parse import urlparse
 import certifi
 from websockets.asyncio.client import connect
 
+import prefect
+from prefect.client.constants import SERVER_API_VERSION
 from prefect.settings import get_current_settings
 
 
@@ -51,6 +53,13 @@ def websocket_connect(uri: str, **kwargs: Any) -> connect:
     if ssl_context:
         kwargs.setdefault("ssl", ssl_context)
 
+    # Identify ourselves to the server the same way the HTTP client does so that
+    # the client version can be parsed from the handshake
+    kwargs.setdefault(
+        "user_agent_header",
+        f"prefect/{prefect.__version__} (API {SERVER_API_VERSION})",
+    )
+
     # Add custom headers from settings
     custom_headers = get_current_settings().client.custom_headers
     if custom_headers:

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/blocks/core.py

@@ -424,6 +424,14 @@ class Block(BaseModel, ABC):
     def ser_model(
         self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
     ) -> Any:
+        if info.context and info.context.get("serialize_blocks_as_references"):
+            if self._block_document_id is None:
+                raise BlockNotSavedError(
+                    "Block must be saved with `.save()` before it can be used as a "
+                    "deployment parameter."
+                )
+            return {"$ref": {"block_document_id": str(self._block_document_id)}}
+
         jsonable_self = handler(self)
         if (ctx := info.context) and ctx.get("include_secrets") is True:
             # Add serialization mode to context so handle_secret_render knows how to process nested models

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/client/orchestration/_flow_runs/client.py

@@ -416,6 +416,34 @@ class FlowRunClient(BaseClient):
         )
         return result
 
+    def read_flow_run_state(self, flow_run_state_id: "UUID") -> "State":
+        """
+        Read a flow run state by ID.
+
+        Args:
+            flow_run_state_id: The flow run state ID.
+
+        Returns:
+            A State model representation of the flow run state.
+
+        Raises:
+            ObjectNotFound: If the flow run state does not exist.
+        """
+        try:
+            response = self.request(
+                "GET",
+                "/flow_run_states/{id}",
+                path_params={"id": flow_run_state_id},
+            )
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 404:
+                raise ObjectNotFound(http_exc=exc) from exc
+            raise
+
+        from prefect.states import State
+
+        return State.model_validate(response.json())
+
     def read_flow_run_states(self, flow_run_id: "UUID") -> "list[State]":
         """
         Query for the states of a flow run
@@ -916,6 +944,34 @@ class FlowRunAsyncClient(BaseAsyncClient):
         )
         return result
 
+    async def read_flow_run_state(self, flow_run_state_id: "UUID") -> "State":
+        """
+        Read a flow run state by ID.
+
+        Args:
+            flow_run_state_id: The flow run state ID.
+
+        Returns:
+            A State model representation of the flow run state.
+
+        Raises:
+            ObjectNotFound: If the flow run state does not exist.
+        """
+        try:
+            response = await self.request(
+                "GET",
+                "/flow_run_states/{id}",
+                path_params={"id": flow_run_state_id},
+            )
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 404:
+                raise ObjectNotFound(http_exc=exc) from exc
+            raise
+
+        from prefect.states import State
+
+        return State.model_validate(response.json())
+
     async def read_flow_run_states(self, flow_run_id: "UUID") -> "list[State]":
         """
         Query for the states of a flow run

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2}/src/prefect/client/orchestration/_work_pools/client.py

@@ -48,7 +48,7 @@ class WorkPoolClient(BaseClient):
         Args:
             work_pool_name: The name of the work pool to heartbeat against.
             worker_name: The name of the worker sending the heartbeat.
-            return_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `return_id` is `True`.
+            get_worker_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `get_worker_id` is `True`.
             worker_metadata: Metadata about the worker to send to the server.
         """
         from uuid import UUID
@@ -376,7 +376,7 @@ class WorkPoolAsyncClient(BaseAsyncClient):
         Args:
             work_pool_name: The name of the work pool to heartbeat against.
             worker_name: The name of the worker sending the heartbeat.
-            return_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `return_id` is `True`.
+            get_worker_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `get_worker_id` is `True`.
             worker_metadata: Metadata about the worker to send to the server.
         """
         from uuid import UUID