prefect-client 3.8.1.dev5__tar.gz → 3.8.2.dev2__tar.gz

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.8.1.dev5
+Version: 3.8.2.dev2
 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.dev5 → prefect_client-3.8.2.dev2}/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.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.2.dev2"
+__build_date__ = "2026-08-03 09:15:43.484194+00:00"
+__git_commit__ = "05c045c68360e723560d61d5231824b55b811db1"
+__dirty__ = False

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/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.dev5 → prefect_client-3.8.2.dev2}/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.dev5 → prefect_client-3.8.2.dev2}/src/prefect/deployments/runner.py

@@ -53,6 +53,8 @@ from pydantic import (
     ConfigDict,
     Field,
     PrivateAttr,
+    TypeAdapter,
+    field_serializer,
     field_validator,
     model_validator,
 )
@@ -69,6 +71,7 @@ from prefect._internal.schemas.validators import (
     reconcile_schedules_runner,
 )
 from prefect._internal.versioning import VersionType, get_inferred_version_info
+from prefect.blocks.core import Block, BlockNotSavedError
 from prefect.client.base import ServerType
 from prefect.client.orchestration import PrefectClient, SyncPrefectClient, get_client
 from prefect.client.schemas.actions import (
@@ -106,7 +109,12 @@ from prefect.types.entrypoint import EntrypointType
 from prefect.utilities.annotations import freeze
 from prefect.utilities.asyncutils import run_coro_as_sync
 from prefect.utilities.callables import ParameterSchema, parameter_schema
-from prefect.utilities.collections import get_from_dict, isiterable
+from prefect.utilities.collections import (
+    StopVisiting,
+    get_from_dict,
+    isiterable,
+    visit_collection,
+)
 from prefect.utilities.dockerutils import (
     parse_image_tag,
 )
@@ -117,6 +125,11 @@ if TYPE_CHECKING:
 
 __all__ = ["RunnerDeployment"]
 
+_DEPLOYMENT_PARAMETER_SERIALIZER = TypeAdapter(
+    dict[str, Any],
+    config=ConfigDict(ser_json_timedelta="float"),
+)
+
 
 def _extract_concurrency_options(
     concurrency_limit: Union[int, ConcurrencyLimitConfig, None],
@@ -296,6 +309,47 @@ class RunnerDeployment(BaseModel):
     def full_name(self) -> str:
         return f"{self.flow_name}/{self.name}"
 
+    @field_validator("parameters", "schedules", mode="before")
+    @classmethod
+    def validate_block_parameters(cls, value: Any) -> Any:
+        def ensure_block_is_saved(value: Any) -> Any:
+            if isinstance(value, Block):
+                if value._block_document_id is None:
+                    raise BlockNotSavedError(
+                        "Block must be saved with `.save()` before it can be used as a "
+                        "deployment parameter."
+                    )
+                raise StopVisiting()
+            return value
+
+        visit_collection(value, ensure_block_is_saved)
+        return value
+
+    @field_serializer("parameters", when_used="json")
+    def serialize_block_parameters(self, parameters: dict[str, Any]) -> dict[str, Any]:
+        return _DEPLOYMENT_PARAMETER_SERIALIZER.dump_python(
+            parameters,
+            mode="json",
+            context={"serialize_blocks_as_references": True},
+        )
+
+    def _schedules_with_serialized_block_parameters(
+        self,
+    ) -> Optional[List[Union[DeploymentScheduleCreate, DeploymentScheduleUpdate]]]:
+        if self.schedules is None:
+            return None
+
+        return [
+            schedule.model_copy(
+                update={
+                    "parameters": self.serialize_block_parameters(schedule.parameters)
+                }
+            )
+            if schedule.parameters
+            else schedule
+            for schedule in self.schedules
+        ]
+
     def _get_deployment_version_info(
         self, version_type: Optional[VersionType] = None
     ) -> VersionInfo:
@@ -378,6 +432,9 @@ class RunnerDeployment(BaseModel):
                 " with a work pool."
             )
 
+        parameters = self.model_dump(mode="json", include={"parameters"})["parameters"]
+        schedules = self._schedules_with_serialized_block_parameters()
+
         async with get_client() as client:
             flow_id = await client.create_flow_from_name(self.flow_name)
 
@@ -389,10 +446,10 @@ class RunnerDeployment(BaseModel):
                 version=self.version,
                 version_info=version_info,
                 paused=self.paused,
-                schedules=self.schedules,
+                schedules=schedules,
                 concurrency_limit=self.concurrency_limit,
                 concurrency_options=self.concurrency_options,
-                parameters=self.parameters,
+                parameters=parameters,
                 description=self.description,
                 tags=self.tags,
                 path=self._path,
@@ -481,6 +538,9 @@ class RunnerDeployment(BaseModel):
                 " with a work pool."
             )
 
+        parameters = self.model_dump(mode="json", include={"parameters"})["parameters"]
+        schedules = self._schedules_with_serialized_block_parameters()
+
         with get_client(sync_client=True) as client:
             flow_id = client.create_flow_from_name(self.flow_name)
 
@@ -492,10 +552,10 @@ class RunnerDeployment(BaseModel):
                 version=self.version,
                 version_info=version_info,
                 paused=self.paused,
-                schedules=self.schedules,
+                schedules=schedules,
                 concurrency_limit=self.concurrency_limit,
                 concurrency_options=self.concurrency_options,
-                parameters=self.parameters,
+                parameters=parameters,
                 description=self.description,
                 tags=self.tags,
                 path=self._path,
@@ -579,7 +639,7 @@ class RunnerDeployment(BaseModel):
         if self.schedules:
             update_payload["schedules"] = [
                 schedule.model_dump(mode="json", exclude_unset=True)
-                for schedule in self.schedules
+                for schedule in self._schedules_with_serialized_block_parameters() or []
             ]
 
         await client.update_deployment(
@@ -631,7 +691,7 @@ class RunnerDeployment(BaseModel):
         if self.schedules:
             update_payload["schedules"] = [
                 schedule.model_dump(mode="json", exclude_unset=True)
-                for schedule in self.schedules
+                for schedule in self._schedules_with_serialized_block_parameters() or []
             ]
 
         client.update_deployment(

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/engine.py

@@ -100,16 +100,14 @@ def handle_engine_signals(flow_run_id: UUID | None = None):
         engine_logger.info(msg)
         exit(0)
     except TerminationSignal:
-        # A TerminationSignal can mean either:
-        # - an expected runner-driven control action (today: cancel intent),
-        # - or a raw external termination with no runner intent attached.
-        #
-        # Only the first case should translate to a clean process exit.
-        if get_intent() == "cancel":
+        # An intent means the runner or the `prefect flow-run execute` supervisor
+        # drove this termination and owns the flow run's next state, so exit cleanly.
+        # A raw external termination has no intent and must keep propagating.
+        if get_intent() is not None:
             if flow_run_id:
-                msg = f"Execution of flow run '{flow_run_id}' was cancelled."
+                msg = f"Execution of flow run '{flow_run_id}' was terminated."
             else:
-                msg = "Execution was cancelled."
+                msg = "Execution was terminated."
             engine_logger.info(msg)
             clear_intent()
             exit(0)

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/flow_engine.py

@@ -195,26 +195,17 @@ def _termination_intent() -> Intent | None:
     for the outermost flow run as well as nested subflows running in the
     same process.
 
-    Today the only non-None value returned is `"cancel"`. A follow-up PR
-    will add `"suspend"` by extending
-    `Intent` in `prefect._internal.control_listener`; the engine's
-    `except TerminationSignal` dispatch below will gain a matching branch.
+    Adding an intent means extending `Intent` in
+    `prefect._internal.control_listener` and the `except TerminationSignal`
+    dispatch below with a matching branch.
     """
     return get_intent()
 
 
-def _should_bubble_raw_sigterm_for_reschedule() -> bool:
-    """Return whether raw SIGTERM should bypass crash handling.
-
-    `prefect flow-run execute` supports a reschedule mode where the parent
-    process proposes `AwaitingRetry` and then sends a plain SIGTERM to the
-    child. That path does not use the control channel, so the child must not
-    reinterpret the resulting `TerminationSignal` as a crash.
-    """
-    return (
-        os.environ.get("PREFECT_FLOW_RUN_EXECUTE_SIGTERM_BEHAVIOR", "").lower()
-        == "reschedule"
-    )
+# Intents where the `prefect flow-run execute` supervisor owns the run's next state
+# (`reschedule` proposes it; `relinquish` leaves it to retrying infrastructure), so
+# the engine must exit without proposing one.
+_SUPERVISOR_OWNED_INTENTS: frozenset[Intent] = frozenset({"reschedule", "relinquish"})
 
 
 def _is_async_runtime_cancellation(exc: BaseException) -> bool:
@@ -1198,10 +1189,8 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                     if intent == "cancel":
                         self.handle_cancellation(exc)
                     elif intent is None:
-                        if _should_bubble_raw_sigterm_for_reschedule():
-                            raise
                         self.handle_crash(exc)
-                    else:
+                    elif intent not in _SUPERVISOR_OWNED_INTENTS:
                         # Defensive: an unknown intent means the control
                         # listener was extended (e.g. "suspend" in a
                         # follow-up PR) without extending this dispatch.
@@ -1896,10 +1885,8 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                     if intent == "cancel":
                         await self.handle_cancellation(exc)
                     elif intent is None:
-                        if _should_bubble_raw_sigterm_for_reschedule():
-                            raise
                         await self.handle_crash(exc)
-                    else:
+                    elif intent not in _SUPERVISOR_OWNED_INTENTS:
                         # Defensive: see sync engine's dispatch for why.
                         self.logger.error(
                             "Unhandled termination intent %r; treating as"
@@ -1936,6 +1923,13 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                                 exc_info=exc,
                             )
                             raise
+                    if (
+                        _is_async_runtime_cancellation(exc)
+                        and _termination_intent() in _SUPERVISOR_OWNED_INTENTS
+                    ):
+                        # A supervisor-driven SIGTERM can surface here as a cancellation
+                        # rather than a TerminationSignal.
+                        raise TerminationSignal(signal.SIGTERM) from exc
                     # We don't want to crash a flow run if the user code finished executing
                     if self.flow_run.state and not self.flow_run.state.is_final():
                         # BaseExceptions are caught and handled as crashes

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/runner/AGENTS.md

@@ -77,9 +77,9 @@ This ordering is a hard constraint. Getting it wrong causes ClosedResourceError
 - POSIX: ack only means "SIGTERM bridge is armed and intent is seeded." The runner's real `SIGTERM` is still the only trigger that interrupts blocking code. Kill happens immediately after ack.
 - Windows: ack means the child has queued `_thread.interrupt_main(SIGTERM)`. The runner gives the child a 30 s grace window to self-exit before falling back to an external kill.
 
-**Failure modes:** If the child never connects or never acks within 1 s, `signal()` returns `False` and the runner falls through to the normal kill path — the engine treats the termination as a crash, same as today.
+**Failure modes:** If the child never connects or never acks within 1 s, `signal()` returns `False`. `CancellationManager` falls through to the normal graceful kill and the engine treats the termination as a crash. The `prefect flow-run execute` supervisor instead calls `ProcessManager.kill(force=True)` (SIGKILL, no grace), because an unacked engine would propose `Crashed` and undo a `reschedule`/`relinquish`.
 
-**Extending intents:** The only intent today is `"cancel"`. The byte map (`_BYTE_FOR_INTENT` in `_control_channel.py` and `_INTENT_FOR_BYTE` in `_internal/control_listener.py`) must stay in sync when adding new intents.
+**Extending intents:** The intents today are `"cancel"`, `"reschedule"` and `"relinquish"`. The byte map (`_BYTE_FOR_INTENT` in `_control_channel.py` and `_INTENT_FOR_BYTE` in `_internal/control_listener.py`) must stay in sync when adding new intents.
 
 ## ProcessStarter Strategy Pattern
 

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/runner/_control_channel.py

@@ -29,13 +29,13 @@ period. What the channel adds is a pre-seeded intent on the child side: by
 the time the child's `SIGTERM` handler runs, `control_listener.get_intent()`
 already returns the pre-seeded intent, so the engine's
 `except TerminationSignal` block can dispatch on it (`on_cancellation` vs
-`on_crashed` today, with room for a third `"suspend"` branch in a follow-up).
+`on_crashed`, or leaving the state alone for `"reschedule"`/`"relinquish"`).
 
 The channel is loopback-only, per-token authenticated, and best-effort: if
-the child never connects or never acks, `signal` returns `False` and the
-runner falls through to the kill path anyway, where the engine will treat
-the resulting termination as a crash — the same behavior as today for
-unresponsive children.
+the child never connects or never acks, `signal` returns `False`. Callers
+decide what that means: cancellation falls through to a graceful kill and lets
+the engine crash the run, while `prefect flow-run execute` kills without a
+grace period so an unacked engine cannot crash a run it is about to retry.
 
 This module is deliberately generic. The set of valid intents lives in
 `prefect._internal.control_listener` as `Intent`; the wire
@@ -68,6 +68,8 @@ _DEFAULT_ACK_TIMEOUT = 1.0
 # intent is a matched one-line change on each side.
 _BYTE_FOR_INTENT: dict[Intent, bytes] = {
     "cancel": b"c",
+    "reschedule": b"r",
+    "relinquish": b"q",
 }
 
 
@@ -92,9 +94,8 @@ class ControlChannel:
     Use as an async context manager. Inside the context, `port` is the
     listener's bound port (suitable for injecting into child env vars).
 
-    The only intent exposed today is `"cancel"`. A future PR will add
-    `"suspend"` by extending the `Intent` literal, the byte map, and
-    the engine's `except TerminationSignal` dispatch.
+    Adding an intent means extending the `Intent` literal, the byte map, and the
+    engine's `except TerminationSignal` dispatch.
     """
 
     def __init__(

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/runner/_process_manager.py

@@ -69,6 +69,18 @@ def _pid_is_alive(pid: int) -> bool:
         kernel32.CloseHandle(handle)
 
 
+def _hard_kill(pid: int) -> None:
+    """Stop `pid` immediately, taking its process group when it leads one so a
+    wrapper command cannot leave the real process running orphaned."""
+    if sys.platform == "win32":
+        # Any signal other than the CTRL_* events is a TerminateProcess here.
+        os.kill(pid, signal.SIGTERM)
+    elif os.getpgid(pid) == pid:
+        os.killpg(pid, signal.SIGKILL)
+    else:
+        os.kill(pid, signal.SIGKILL)
+
+
 @dataclass
 class ProcessHandle:
     _process: anyio.abc.Process | multiprocessing.context.SpawnProcess
@@ -197,7 +209,14 @@ class ProcessManager:
 
             await anyio.sleep(min(check_interval, remaining))
 
-    async def kill(self, flow_run_id: UUID, grace_seconds: float = 30) -> None:
+    async def kill(
+        self, flow_run_id: UUID, grace_seconds: float = 30, *, force: bool = False
+    ) -> None:
+        """Stop the process for `flow_run_id`.
+
+        `force` skips the graceful signal, for callers that must not let the process
+        run any more code; `grace_seconds` is unused in that case.
+        """
         handle = self._process_map.get(flow_run_id)
         if handle is None:
             self._logger.warning(
@@ -214,10 +233,22 @@ class ProcessManager:
             )
             return
 
+        if force:
+            try:
+                _hard_kill(pid)
+            except ProcessLookupError:
+                pass
+            return
+
         if sys.platform == "win32":
             os.kill(pid, signal.CTRL_BREAK_EVENT)
         else:
-            os.kill(pid, signal.SIGTERM)
+            try:
+                os.kill(pid, signal.SIGTERM)
+            except ProcessLookupError:
+                # Already reaped, e.g. re-killed from `__aexit__` after a cancelled
+                # executor skipped its cleanup.
+                return
 
             check_interval = max(grace_seconds / 10, 1)
             with anyio.move_on_after(grace_seconds):

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/runner/_starter_engine.py

@@ -47,6 +47,7 @@ class EngineCommandStarter:
         stream_output: bool = True,
         heartbeat_seconds: int | None = None,
         control_channel: ControlChannel | None = None,
+        isolate_process_group: bool = False,
     ) -> None:
         self._tmp_dir = tmp_dir
         self._storage = storage
@@ -58,6 +59,7 @@ class EngineCommandStarter:
         self._stream_output = stream_output
         self._heartbeat_seconds = heartbeat_seconds
         self._control_channel = control_channel
+        self._isolate_process_group = isolate_process_group
 
     async def start(
         self,
@@ -76,6 +78,9 @@ class EngineCommandStarter:
         kwargs: dict[str, object] = {}
         if sys.platform == "win32":
             kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        elif self._isolate_process_group:
+            # So a group-wide SIGTERM cannot beat the caller's intent to the child.
+            kwargs["start_new_session"] = True
 
         # Register the flow run with the control channel before spawning so
         # the child can connect back as soon as it starts. Returned port +

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/runner/_workspace_starter.py

@@ -333,6 +333,7 @@ class WorkspaceResolvingEngineCommandStarter:
         heartbeat_seconds: int | None = None,
         deployment_name: str | None = None,
         control_channel: ControlChannel | None = None,
+        isolate_process_group: bool = False,
     ) -> None:
         self._workspace_root = workspace_root
         self._command = command
@@ -340,6 +341,7 @@ class WorkspaceResolvingEngineCommandStarter:
         self._heartbeat_seconds = heartbeat_seconds
         self._deployment_name = deployment_name
         self._control_channel = control_channel
+        self._isolate_process_group = isolate_process_group
         self._workspace: PreparedWorkspace | None = None
 
     @property
@@ -368,6 +370,7 @@ class WorkspaceResolvingEngineCommandStarter:
             heartbeat_seconds=self._heartbeat_seconds,
             deployment_name=self._deployment_name,
             control_channel=self._control_channel,
+            isolate_process_group=self._isolate_process_group,
         )
         await starter.start(flow_run, task_status=task_status)
 

{prefect_client-3.8.1.dev5 → prefect_client-3.8.2.dev2}/src/prefect/utilities/processutils/__init__.py

@@ -423,15 +423,36 @@ async def run_process(
             task_status.started(value)
 
         if stream_output:
-            await consume_process_output(
-                process, stdout_sink=stream_output[0], stderr_sink=stream_output[1]
-            )
+            try:
+                await consume_process_output(
+                    process, stdout_sink=stream_output[0], stderr_sink=stream_output[1]
+                )
+            except Exception:
+                # Keep draining both pipes after an output sink fails so the process
+                # can finish without blocking on a full stdout or stderr buffer.
+                await _drain_process_output(process)
+                await process.wait()
+                raise
 
         await process.wait()
 
     return process
 
 
+async def _drain_process_output(process: anyio.abc.Process) -> None:
+    async with anyio.create_task_group() as tg:
+        if process.stdout is not None:
+            tg.start_soon(
+                stream_text,
+                TextReceiveStream(process.stdout, errors="replace"),
+            )
+        if process.stderr is not None:
+            tg.start_soon(
+                stream_text,
+                TextReceiveStream(process.stderr, errors="replace"),
+            )
+
+
 async def consume_process_output(
     process: anyio.abc.Process,
     stdout_sink: Optional[TextSink[str]] = None,

prefect_client-3.8.1.dev5/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.8.1.dev5"
-__build_date__ = "2026-07-30 08:59:46.957198+00:00"
-__git_commit__ = "5343882dac86146bccebbd38ce41794cef134a7c"
-__dirty__ = False