prefect-client 3.8.4.dev7__tar.gz → 3.8.5.dev2__tar.gz

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.8.4.dev7
+Version: 3.8.5.dev2
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -64,7 +64,7 @@ Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<17.0,>=15.0.1
 Requires-Dist: whenever<0.11.0,>=0.7.3; python_version >= '3.13'
 Provides-Extra: notifications
-Requires-Dist: apprise<2.0.0,>=1.1.0; extra == 'notifications'
+Requires-Dist: apprise<2.0.0,>=1.13.0; extra == 'notifications'
 Description-Content-Type: text/markdown
 
 <p align="center"><img src="https://github.com/PrefectHQ/prefect/assets/3407835/c654cbc6-63e8-4ada-a92a-efd2f8f24b85" width=1000></p>

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/pyproject.toml

@@ -74,7 +74,7 @@ Documentation = "https://docs.prefect.io"
 Source = "https://github.com/PrefectHQ/prefect"
 Tracker = "https://github.com/PrefectHQ/prefect/issues"
 [project.optional-dependencies]
-notifications = ["apprise>=1.1.0, <2.0.0"]
+notifications = ["apprise>=1.13.0, <2.0.0"]
 
 
 [tool.hatch.version]

prefect_client-3.8.5.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.5.dev2"
+__build_date__ = "2026-08-28 11:57:42.214978+00:00"
+__git_commit__ = "239f9c68b7cbeb7fa9d6995b62a03ff124b5b16b"
+__dirty__ = False

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/_internal/attempt_control.py

@@ -48,7 +48,7 @@ class EngineOutcomeReceipt:
     state_name: str | None = None
 
     def __post_init__(self) -> None:
-        if not isinstance(self.disposition, EngineDisposition):
+        if not isinstance(self.disposition, EngineDisposition):  # pyright: ignore[reportUnnecessaryIsInstance]
             raise TypeError("Receipt disposition must be an EngineDisposition")
         state_fields = (self.state_id, self.state_type, self.state_name)
         if self.disposition is EngineDisposition.STATE_REPORTED:

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/context.py

@@ -914,6 +914,32 @@ def get_settings_context() -> SettingsContext:
     return settings_ctx
 
 
+@contextmanager
+def _temporary_global_settings_context(
+    settings_context: "SettingsContext",
+) -> Generator[None, None, None]:
+    """
+    Temporarily replace the process-global settings context.
+
+    `SettingsContext.get` returns the process-global settings context when the
+    current `contextvars` context does not contain one. Replacing the global
+    context makes the given settings visible to contexts that were copied before
+    the settings were applied, such as the context that
+    `unittest.IsolatedAsyncioTestCase` copies when it is constructed. Contexts
+    that contain their own settings context are not affected.
+
+    This is an internal utility for `prefect.testing.utilities.prefect_test_harness`.
+    """
+    global GLOBAL_SETTINGS_CONTEXT
+
+    prior_global_settings_context = GLOBAL_SETTINGS_CONTEXT
+    GLOBAL_SETTINGS_CONTEXT = settings_context
+    try:
+        yield
+    finally:
+        GLOBAL_SETTINGS_CONTEXT = prior_global_settings_context
+
+
 @contextmanager
 def tags(*new_tags: str) -> Generator[set[str], None, None]:
     """

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/events/filters.py

@@ -14,6 +14,14 @@ from prefect.utilities.collections import AutoEnum
 from .schemas.events import Event, Resource, ResourceSpecification
 
 
+class AutomationFilterId(PrefectBaseModel):
+    """Filter by `Automation.id`."""
+
+    any_: Optional[list[UUID]] = Field(
+        default=None, description="A list of automation ids to include"
+    )
+
+
 class AutomationFilterCreated(PrefectBaseModel):
     """Filter by `Automation.created`."""
 
@@ -52,6 +60,9 @@ class AutomationFilterTags(PrefectBaseModel):
 
 
 class AutomationFilter(PrefectBaseModel):
+    id: Optional[AutomationFilterId] = Field(
+        default=None, description="Filter criteria for `Automation.id`"
+    )
     name: Optional[AutomationFilterName] = Field(
         default=None, description="Filter criteria for `Automation.name`"
     )

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/events/worker.py

@@ -6,10 +6,12 @@ from uuid import UUID
 from typing_extensions import Self
 
 from prefect._internal.concurrency.services import QueueService
+from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_KEY,
     PREFECT_API_URL,
     PREFECT_CLOUD_API_URL,
+    get_current_settings,
 )
 from prefect.utilities.context import temporary_context
 
@@ -23,8 +25,12 @@ from .related import related_resources_from_run_context
 from .schemas.events import Event
 
 if TYPE_CHECKING:
+    import logging
+
     from prefect.client.orchestration import PrefectClient
 
+logger: "logging.Logger" = get_logger(__name__)
+
 
 class ProcessPoolForwardingEventsClient(EventsClient):
     """An events client that forwards events to a parent process queue."""
@@ -69,8 +75,6 @@ class EventsWorker(QueueService[Event]):
     def __init__(
         self, client_type: Type[EventsClient], client_options: Tuple[Tuple[str, Any]]
     ):
-        from prefect.settings import get_current_settings
-
         self._max_queue_size = get_current_settings().events.worker_max_queue_size
         super().__init__(client_type, client_options)
         self.client_type = client_type
@@ -113,10 +117,29 @@ class EventsWorker(QueueService[Event]):
             return
 
         exclude = {resource.id for resource in event.involved_resources}
-        event.related += await related_resources_from_run_context(
+        related = await related_resources_from_run_context(
             client=self._orchestration_client, exclude=exclude
         )
 
+        # The event was validated when it was created, before these resources were
+        # known, so only attach as many as keep the event within the same maximum that
+        # the Event schema validates.  Otherwise the event is no longer valid to send.
+        maximum = get_current_settings().server.events.maximum_related_resources
+        room = max(maximum - len(event.related), 0)
+        if len(related) > room:
+            logger.warning(
+                "Attaching only %s of the %s related resources from the run context "
+                "to event %s, which already has %s of a maximum %s related resources",
+                room,
+                len(related),
+                event.id,
+                len(event.related),
+                maximum,
+            )
+            related = related[:room]
+
+        event.related += related
+
     @classmethod
     def set_client_override(
         cls, client_type: Optional[Type[EventsClient]], **client_kwargs: Any

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/runner/AGENTS.md

@@ -23,7 +23,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 | FlowRunExecutorContext | _flow_run_executor.py | Async context manager for one-shot execution outside Runner (workers, CLI, bundles) |
 | DirectSubprocessStarter | _starter_direct.py | Runs Flow object via run_flow_in_subprocess |
 | EngineCommandStarter | _starter_engine.py | Spawns `python -m prefect.engine` subprocess |
-| WorkspaceResolvingEngineCommandStarter | _workspace_starter.py | Resolves workspace (pull steps) via `_workspace_resolver` subprocess then delegates to EngineCommandStarter; used by `prefect flow-run execute` |
+| WorkspaceResolvingEngineCommandStarter | _workspace_starter.py | Starts a managed supervisor that prepares the workspace, launches the selected engine command, and records the prepared runtime for hooks |
 | BundleExecutionStarter | _starter_bundle.py | Executes serialized bundle in SpawnProcess |
 
 ## Key Contracts
@@ -45,7 +45,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 - `execute_bundle()` -- deprecated (Mar 2026); use `execute_bundle()` from `prefect.bundles.execute`
 - `reschedule_current_flow_runs()` -- deprecated (Mar 2026); SIGTERM rescheduling is now handled inline by the CLI execute path
 
-These will be removed once internal callers are migrated. Direct ProcessWorker flow runs already use `FlowRunExecutorContext` with `EngineCommandStarter`; only its ad hoc bundle path still calls deprecated `Runner.execute_bundle()`. Keep lifecycle behavior in the extracted classes and do not route direct worker execution back through Runner.
+These will be removed once internal callers are migrated. Direct ProcessWorker flow runs already use `FlowRunExecutorContext`; generated commands use `WorkspaceResolvingEngineCommandStarter`, while explicitly configured commands use `EngineCommandStarter`. Only the ad hoc bundle path still calls deprecated `Runner.execute_bundle()`. Keep lifecycle behavior in the extracted classes and do not route direct worker execution back through Runner.
 
 ## EventEmitter WebSocket Degradation
 
@@ -108,7 +108,7 @@ The cancelling precheck (step 1a) still runs unconditionally even when `propose_
 
 ## ProcessWorker Execution Paths
 
-Direct ProcessWorker runs use `FlowRunExecutorContext` with `EngineCommandStarter` and `propose_submitting=False`. The executor owns process tracking, cancellation, Attempt Control Session evidence, crash inference, and normalized infrastructure status. Ad hoc ProcessWorker submissions still call deprecated `Runner.execute_bundle()` and remain a migration target.
+Direct ProcessWorker runs use `FlowRunExecutorContext` with `propose_submitting=False`. Generated commands use `WorkspaceResolvingEngineCommandStarter` so command selection follows workspace preparation; explicitly configured commands use `EngineCommandStarter` and retain their own pull-step semantics. The executor owns process tracking, cancellation, Attempt Control Session evidence, crash inference, and normalized infrastructure status. Ad hoc ProcessWorker submissions still call deprecated `Runner.execute_bundle()` and remain a migration target.
 
 ## BlockStorageAdapter Pull Behavior
 
@@ -133,19 +133,19 @@ These validations exist to prevent git argument injection. Do not bypass them wh
 
 ## Workspace Resolver Subprocess
 
-`_workspace_resolver.py` prepares a flow run workspace in an isolated subprocess (storage pull, pull steps, CWD/env/sys.path capture). Runs as `python -m prefect.runner._workspace_resolver`.
+`_workspace_resolver.py` prepares a flow run workspace inside the managed workspace supervisor (storage pull, pull steps, and CWD/environment/sys.path capture).
 
 **Stdout is reserved for the JSON `PreparedWorkspaceResult` payload only.** Pull step output (including inherited stdout from child processes) is redirected to stderr. Parse `process.stdout` for the result, `process.stderr` for diagnostics. Violating this breaks callers silently.
 
-**Caller-facing API:** Use `WorkspaceResolvingEngineCommandStarter` (`_workspace_starter.py`) rather than calling the resolver directly. It wraps the subprocess call, memoizes the resolved workspace (one subprocess call per starter instance), and provides `resolve_flow()` that loads the flow inside the resolved workspace context. Pass `starter.resolve_flow` as the `resolve_flow` argument to `FlowRunExecutorContext.create_executor()` — using a separate lambda bypasses the workspace context and will fail to find the flow.
+**Caller-facing API:** Use `WorkspaceResolvingEngineCommandStarter` (`_workspace_starter.py`) rather than calling the resolver directly when the caller owns workspace preparation. Pass `starter.hook_runner` as the `hook_runner` argument to `FlowRunExecutorContext.create_executor()`. The hook runner reads the prepared runtime manifest and loads hooks in a subprocess using the same command prefix, working directory, and environment as the engine. Treat explicitly configured commands as opaque; ProcessWorker launches them with `EngineCommandStarter` so their existing pull behavior is not duplicated.
 
-**Env/sys.path isolation:** `_prepared_workspace_context` mutates `os.environ` and `sys.path` in the caller process but does NOT change `os.getcwd()`. The parent working directory is preserved.
+**Environment isolation:** Workspace preparation, engine execution, and hook loading stay in child processes. Do not install a prepared workspace's environment, CWD, or `sys.path` in the long-lived runner process.
 
 **Local path in-place execution:** When no pull steps are configured and the entrypoint file exists at `deployment.path` but not in the workspace root, `prepare_workspace` sets `working_directory` to the local path — not under `workspace_root`. The workspace directory is still created but is not the execution root. This is the "image-baked" pattern: code lives at a fixed local path (e.g., inside a container), not in object storage.
 
 **Pull-step directory fallback:** When pull steps run but none produces a `directory` output or changes CWD, `_ensure_entrypoint_in_workspace` copies storage into the workspace root as a fallback. This handles setup-only pull steps (e.g., `run_shell_script` for environment prep) that do not control the working directory themselves.
 
-**Automatic dependency installation:** By default, `WorkspaceResolvingEngineCommandStarter` does not install dependencies before starting a flow run. When no explicit command is passed and `PREFECT_RUNNER_AUTO_INSTALL_DEPENDENCIES` is true, it auto-selects `uv run --no-default-groups --project <project_root> -m prefect.flow_engine` — but only when all three conditions hold: `pyproject.toml` exists at `project_root`, the `project.dependencies` list includes `prefect`, and `uv` is found via the workspace's `PATH` env var (not the system PATH). If the setting is false or any condition fails, the command falls back to `None`. Explicit commands always take precedence.
+**Automatic dependency installation:** By default, `WorkspaceResolvingEngineCommandStarter` does not install dependencies before starting a flow run. When no explicit command is passed and `PREFECT_RUNNER_AUTO_INSTALL_DEPENDENCIES` is true, it auto-selects `uv run --no-default-groups --project <project_root>` with the worker-supplied workspace bootstrap — but only when all three conditions hold: `pyproject.toml` exists at `project_root`, the `project.dependencies` list includes `prefect`, and `uv` is found via the workspace's `PATH` env var (not the system PATH). The bootstrap uses the prepared entrypoint with `prefect.flow_engine` when that module exposes its executable `_main`; older selected runtimes fall back to `prefect.engine` with `PREFECT__FLOW_ENTRYPOINT`, preserving the prepared workspace. If the setting is false or any condition fails, the command falls back to `None`. Explicit commands always take precedence.
 
 ## Reference
 

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/runner/_cancellation_manager.py

@@ -19,7 +19,7 @@ if TYPE_CHECKING:
     from prefect.client.schemas.objects import FlowRun
     from prefect.runner._control_channel import ControlChannel
     from prefect.runner._event_emitter import EventEmitter
-    from prefect.runner._hook_runner import HookRunner
+    from prefect.runner._hook_runner import FlowRunHookRunner
     from prefect.runner._process_manager import ProcessManager
     from prefect.runner._state_proposer import StateProposer
 
@@ -42,7 +42,7 @@ class CancellationManager:
         self,
         *,
         process_manager: ProcessManager,
-        hook_runner: HookRunner,
+        hook_runner: FlowRunHookRunner,
         state_proposer: StateProposer,
         event_emitter: EventEmitter,
         client: PrefectClient,

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/runner/_flow_run_executor.py

@@ -18,7 +18,7 @@ from prefect.logging import get_logger
 from prefect.runner._cancellation_manager import CancellationManager
 from prefect.runner._control_channel import ControlChannel
 from prefect.runner._event_emitter import EventEmitter
-from prefect.runner._hook_runner import HookRunner
+from prefect.runner._hook_runner import FlowRunHookRunner, HookRunner
 from prefect.runner._process_manager import ProcessHandle, ProcessManager
 from prefect.runner._state_proposer import StateProposer
 from prefect.settings.context import get_current_settings
@@ -94,7 +94,7 @@ class FlowRunExecutor:
         starter: ProcessStarter,
         process_manager: ProcessManager,
         state_proposer: StateProposer,
-        hook_runner: HookRunner,
+        hook_runner: FlowRunHookRunner,
         get_attempt_conclusion: Callable[[UUID], AttemptConclusion | None],
         propose_submitting: bool = True,
     ) -> None:
@@ -267,6 +267,7 @@ class FlowRunExecutorContext:
     async def __aenter__(self) -> FlowRunExecutorContext:
         self._stack = AsyncExitStack()
         await self._stack.__aenter__()
+        self._after_exit_callbacks: list[Callable[[], object]] = []
         self._logger = get_logger("runner.executor_context")
 
         # Step 1: client
@@ -339,7 +340,15 @@ class FlowRunExecutorContext:
         exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> bool | None:
-        return await self._stack.__aexit__(exc_type, exc_value, traceback)
+        try:
+            return await self._stack.__aexit__(exc_type, exc_value, traceback)
+        finally:
+            for callback in reversed(self._after_exit_callbacks):
+                callback()
+
+    def call_after_exit(self, callback: Callable[[], object]) -> None:
+        """Keep attempt resources alive until cancellation work has drained."""
+        self._after_exit_callbacks.append(callback)
 
     def _handle_cancellation_observer_failure(self, flow_run_ids: set) -> None:
         """Handle failure of both cancellation observer mechanisms.
@@ -369,10 +378,15 @@ class FlowRunExecutorContext:
         self,
         flow_run: FlowRun,
         starter: ProcessStarter,
-        resolve_flow: Callable[[FlowRun], Awaitable[Flow[Any, Any]]],
+        resolve_flow: Callable[[FlowRun], Awaitable[Flow[Any, Any]]] | None = None,
         propose_submitting: bool = True,
+        hook_runner: FlowRunHookRunner | None = None,
     ) -> FlowRunExecutor:
-        hook_runner = HookRunner(resolve_flow=resolve_flow)
+        if (resolve_flow is None) == (hook_runner is None):
+            raise ValueError("Provide exactly one of resolve_flow or hook_runner.")
+        if hook_runner is None:
+            assert resolve_flow is not None
+            hook_runner = HookRunner(resolve_flow=resolve_flow)
         # Wire the real resolver into CancellationManager for on_cancellation hooks
         self._cancellation_manager._hook_runner = hook_runner
         return FlowRunExecutor(

{prefect_client-3.8.4.dev7 → prefect_client-3.8.5.dev2}/src/prefect/runner/_hook_runner.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Protocol
 
 from prefect._internal.concurrency.api import create_call, from_async
 from prefect._internal.engine import get_hook_name
@@ -13,6 +13,12 @@ if TYPE_CHECKING:
     from prefect.states import State
 
 
+class FlowRunHookRunner(Protocol):
+    async def run_cancellation_hooks(self, flow_run: FlowRun, state: State) -> None: ...
+
+    async def run_crashed_hooks(self, flow_run: FlowRun, state: State) -> None: ...
+
+
 async def _run_hooks(
     hooks: list[Any],
     flow_run: FlowRun,