prefect-client 3.6.30.dev2__tar.gz → 3.6.30.dev4__tar.gz

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/.gitignore

@@ -54,6 +54,8 @@ src/mkdocs-material
 # UI artifacts
 src/prefect/server/ui/*
 src/prefect/server/ui_build/*
+src/prefect/server/ui-v2/*
+src/prefect/server/ui_v2_build/*
 **/node_modules
 
 # Databases

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.30.dev2
+Version: 3.6.30.dev4
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

prefect_client-3.6.30.dev4/hatch_build.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+try:
+    from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+except ModuleNotFoundError:  # pragma: no cover - only used when testing helpers
+
+    class BuildHookInterface:  # type: ignore[no-redef]
+        root: str
+        target_name: str
+
+
+PACKAGED_UI_INDEX_FILES = (
+    Path("src/prefect/server/ui/index.html"),
+    Path("src/prefect/server/ui-v2/index.html"),
+)
+REQUIRE_PACKAGED_UI_ENV_VAR = "PREFECT_REQUIRE_PACKAGED_UI_BUNDLES"
+
+
+def _truthy_env_var(name: str) -> bool:
+    return os.environ.get(name, "").lower() not in {"", "0", "false", "no", "off"}
+
+
+def should_validate_packaged_ui_index_files(root: str | Path) -> bool:
+    if _truthy_env_var(REQUIRE_PACKAGED_UI_ENV_VAR):
+        return True
+
+    root_path = Path(root)
+    return any(
+        (root_path / index_file.parent).exists()
+        for index_file in PACKAGED_UI_INDEX_FILES
+    )
+
+
+def validate_packaged_ui_index_files(root: str | Path) -> None:
+    root_path = Path(root)
+    missing_index_files = [
+        str(index_file)
+        for index_file in PACKAGED_UI_INDEX_FILES
+        if not (root_path / index_file).is_file()
+    ]
+
+    if missing_index_files:
+        raise RuntimeError(
+            "Prefect package builds require both UI bundles to be built. "
+            "Missing index.html files: "
+            f"{', '.join(missing_index_files)}"
+        )
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if (
+            version != "editable"
+            and self.target_name in {"sdist", "wheel"}
+            and should_validate_packaged_ui_index_files(self.root)
+        ):
+            validate_packaged_ui_index_files(self.root)

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/AGENTS.md

@@ -10,6 +10,7 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 
 - `flows.py` / `tasks.py` — `@flow` and `@task` decorator definitions. The primary user-facing API.
 - `flow_engine.py` / `task_engine.py` — Async execution engines that orchestrate runs. **Critical invariant:** both sync and async engine paths must be kept in lockstep. Changes to one must be mirrored in the other.
+- `flow_engine.py` is also a subprocess entrypoint: `python -m prefect.flow_engine <entrypoint>`. Reads `PREFECT__FLOW_RUN_ID` from the environment; accepts exactly one argument (the flow entrypoint path or module ref). Workers and infrastructure use this to launch flow runs as isolated subprocesses. Plain functions not decorated with `@flow` are auto-converted to flows at this entry point.
 - `states.py` — State objects and transition logic
 - `results.py` — Result persistence and retrieval
 - `futures.py` — `PrefectFuture` for async task results
@@ -20,12 +21,15 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 ## Key Contracts
 
 - **Engine ordering matters.** The engines apply features (retries, caching, result persistence, transactions) in a specific order. Changing the order or forgetting a feature in one engine path is the most common source of breakage.
+- **Set run metadata before state transitions.** Any run attribute that event subscribers observe at the moment of a state transition (e.g., custom `flow_run_name`) must be persisted to the server *before* `set_state()` is called for that transition. Metadata set after the call appears stale to subscribers of that state event.
 - **Sync and async must stay in sync.** Both `flow_engine.py` and `task_engine.py` have sync and async paths. Any behavior change must be applied to both.
 - **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences between whenever 0.7.x–0.9.x and ≥ 0.10.0. The `_WHENEVER_NEW_API` flag (True when whenever ≥ 0.10.0) guards version-specific code. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Violations will silently break on whichever whenever version the helpers weren't written for.
 - **Flow and task engines advance state differently.** The flow engine makes blocking API calls to the server to propose and advance states. The task engine emits `prefect.task_run.*` events (delivered via WebSockets) but advances state locally through `set_state` calls with polling/backoff — do not assume the two engines work the same way.
 - **Flow state transitions go through the server.** The flow engine proposes states to the server, which accepts or rejects them via orchestration rules. The task engine, by contrast, manages state transitions locally via `set_state` and emits `prefect.task_run.*` events — it does not propose states to the server.
 - **`ProcessPoolTaskRunner` requires picklable data across subprocess boundaries.** `PrefectFuture` objects are not picklable and cannot be passed to worker subprocesses. Any `wait_for` futures must be waited on in the parent process and converted to `State` objects before submission. The subprocess task engine handles `State` objects via `resolve_to_final_result`, which raises `UpstreamTaskError` for non-completed upstreams.
 - **`ProcessPoolTaskRunner` instances may be deserialized without `__init__` running.** When a runner is pickled and restored in a subprocess, `__init__` is not called, so instance attributes set there may be absent. Access any such attribute via `getattr(self, "_attr", default)` rather than `self._attr` directly — both in the property getter and in `duplicate()`. The `subprocess_message_processor_factories` property demonstrates the required pattern.
+- **`ThreadPoolTaskRunner` is cloudpickled when a flow run is dispatched to a subprocess.** `threading.Lock` and other non-picklable thread primitives must be dropped in `__getstate__` and rebuilt in `__setstate__`. Any new instance state added to this class must be evaluated for picklability.
+- **Nested task submissions on a bounded `ThreadPoolTaskRunner` can deadlock.** When a worker task submits children and blocks on `.result()` while all `max_workers` threads are busy, the pool starves. `_warn_if_nested_submit_would_deadlock` detects this and emits a one-time warning — preserve this detection when changing pool management.
 - **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
 
 ## Logging

prefect_client-3.6.30.dev4/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.30.dev4"
+__build_date__ = "2026-05-06 08:56:13.081322+00:00"
+__git_commit__ = "2b9d462118706889dfeee26df45a1b6108491070"
+__dirty__ = False

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/client/orchestration/__init__.py

@@ -110,6 +110,8 @@ from prefect.client.schemas.objects import (
     FlowRunResult,
     Parameter,
     Constant,
+    ServerDefaultResultStorage,
+    ServerDefaultResultStorageUpdate,
     TaskRunPolicy,
     WorkQueue,
     WorkQueueStatusDetail,
@@ -1079,6 +1081,27 @@ class PrefectClient(
         res = await self._client.get("/admin/version")
         return res.json()
 
+    async def read_server_default_result_storage(
+        self,
+    ) -> ServerDefaultResultStorage:
+        response = await self._client.get("/admin/storage")
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    async def update_server_default_result_storage(
+        self,
+        default_result_storage_block_id: UUID,
+    ) -> ServerDefaultResultStorage:
+        response = await self._client.put(
+            "/admin/storage",
+            json=ServerDefaultResultStorageUpdate(
+                default_result_storage_block_id=default_result_storage_block_id
+            ).model_dump(mode="json"),
+        )
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    async def clear_server_default_result_storage(self) -> None:
+        await self._client.delete("/admin/storage")
+
     def client_version(self) -> str:
         return prefect.__version__
 
@@ -1451,6 +1474,25 @@ class SyncPrefectClient(
         res = self._client.get("/admin/version")
         return res.json()
 
+    def read_server_default_result_storage(self) -> ServerDefaultResultStorage:
+        response = self._client.get("/admin/storage")
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    def update_server_default_result_storage(
+        self,
+        default_result_storage_block_id: UUID,
+    ) -> ServerDefaultResultStorage:
+        response = self._client.put(
+            "/admin/storage",
+            json=ServerDefaultResultStorageUpdate(
+                default_result_storage_block_id=default_result_storage_block_id
+            ).model_dump(mode="json"),
+        )
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    def clear_server_default_result_storage(self) -> None:
+        self._client.delete("/admin/storage")
+
     def client_version(self) -> str:
         return prefect.__version__
 

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/client/orchestration/routes.py

@@ -1,6 +1,7 @@
 from typing import Literal
 
 ServerRoutes = Literal[
+    "/admin/storage",
     "/admin/settings",
     "/admin/version",
     "/artifacts/",

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/client/schemas/objects.py

@@ -1550,6 +1550,24 @@ class WorkPoolStorageConfiguration(PrefectBaseModel):
     )
 
 
+class ServerDefaultResultStorage(PrefectBaseModel):
+    """Server-side default result storage configuration."""
+
+    default_result_storage_block_id: Optional[UUID] = Field(
+        default=None,
+        description="The block document ID of the server default result storage block.",
+    )
+
+
+class ServerDefaultResultStorageUpdate(PrefectBaseModel):
+    """Request payload for setting the server default result storage block."""
+
+    default_result_storage_block_id: UUID = Field(
+        default=...,
+        description="The block document ID of the server default result storage block.",
+    )
+
+
 class WorkPool(ObjectBaseModel):
     """An ORM representation of a work pool"""
 

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/deployments/AGENTS.md

@@ -23,6 +23,8 @@ Built-in steps:
 - `steps/pull.py` — `git_clone`, `set_working_directory`, `pull_from_remote_storage`
 - `steps/utility.py` — `run_shell_script`, `pip_install_requirements`
 
+**Step observer**: `run_steps` does not accept a step completion callback as a parameter by design — inject one via `_observe_step_completion(callback)` context manager from `steps/core.py`. The callback receives `(step, output, cwd_before, cwd_after)` after each step; either CWD arg is `None` when the directory becomes inaccessible (e.g., the step deleted its working directory).
+
 ## Entrypoint Formats
 
 `runner.py`'s `from_storage` / `afrom_storage` (and `Flow.from_source`) support two entrypoint formats:

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/deployments/steps/core.py

@@ -17,8 +17,12 @@ import os
 import re
 import subprocess
 import warnings
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from copy import deepcopy
 from importlib import import_module
+from pathlib import Path
 from typing import Any
 from uuid import UUID
 
@@ -39,6 +43,15 @@ from prefect.utilities.templating import (
 
 RESERVED_KEYWORDS = {"id", "requires"}
 
+_StepCompletionObserver = Callable[
+    [dict[str, Any], Any, Path | None, Path | None],
+    None,
+]
+_STEP_COMPLETION_OBSERVER: ContextVar[_StepCompletionObserver | None] = ContextVar(
+    "step_completion_observer",
+    default=None,
+)
+
 
 class StepExecutionError(Exception):
     """
@@ -46,6 +59,22 @@ class StepExecutionError(Exception):
     """
 
 
+def _safe_current_working_directory() -> Path | None:
+    try:
+        return Path.cwd().resolve()
+    except OSError:
+        return None
+
+
+@contextmanager
+def _observe_step_completion(callback: _StepCompletionObserver) -> Iterator[None]:
+    token = _STEP_COMPLETION_OBSERVER.set(callback)
+    try:
+        yield
+    finally:
+        _STEP_COMPLETION_OBSERVER.reset(token)
+
+
 def _strip_version(requirement: str) -> str:
     """
     Strips the version from a requirement string.
@@ -152,6 +181,7 @@ async def run_steps(
     logger: Any | None = None,
 ) -> dict[str, Any]:
     upstream_outputs = deepcopy(upstream_outputs) if upstream_outputs else {}
+    step_completion_observer = _STEP_COMPLETION_OBSERVER.get()
     for step_index, step in enumerate(steps):
         if not step:
             continue
@@ -177,6 +207,11 @@ async def run_steps(
 
         try:
             # catch warnings to ensure deprecation warnings are printed
+            step_start_cwd = (
+                _safe_current_working_directory()
+                if step_completion_observer is not None
+                else None
+            )
             with warnings.catch_warnings(record=True) as w:
                 warnings.simplefilter(
                     "always",
@@ -201,6 +236,14 @@ async def run_steps(
                             print_function(message)
                         printed_messages.append(message)
 
+            if step_completion_observer is not None:
+                step_completion_observer(
+                    step,
+                    step_output,
+                    step_start_cwd,
+                    _safe_current_working_directory(),
+                )
+
             if not isinstance(step_output, dict):
                 if PREFECT_DEBUG_MODE:
                     get_logger().warning(

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev4}/src/prefect/flow_engine.py

@@ -8,6 +8,7 @@ import multiprocessing
 import multiprocessing.context
 import os
 import signal
+import sys
 import threading
 import time
 from contextlib import (
@@ -66,7 +67,7 @@ from prefect.context import (
     hydrated_context,
     serialize_context,
 )
-from prefect.engine import handle_engine_signals
+from prefect.engine import _drive_run_flow_result, handle_engine_signals
 from prefect.events.related import RelatedResource, tags_as_related_resources
 from prefect.events.utilities import emit_event
 from prefect.exceptions import (
@@ -92,6 +93,8 @@ from prefect.logging.loggers import (
 )
 from prefect.results import (
     ResultStore,
+    _aget_default_persist_result,
+    _get_default_persist_result,
     get_result_store,
     should_persist_result,
 )
@@ -109,6 +112,7 @@ from prefect.states import (
     exception_to_failed_state,
     return_value_to_state,
 )
+from prefect.telemetry._metrics import RunMetrics
 from prefect.telemetry.run_telemetry import (
     LABELS_TRACEPARENT_KEY,
     TRACEPARENT_KEY,
@@ -142,6 +146,7 @@ P = ParamSpec("P")
 R = TypeVar("R")
 
 MINIMUM_HEARTBEAT_INTERVAL = 30
+_engine_logger = get_logger("engine")
 _CONTROL_CHANNEL_ENV_KEYS = frozenset(
     {"PREFECT__CONTROL_PORT", "PREFECT__CONTROL_TOKEN"}
 )
@@ -220,15 +225,18 @@ def load_flow_run(flow_run_id: UUID) -> FlowRun:
     return flow_run
 
 
+def _load_flow_from_runtime_entrypoint(entrypoint: str) -> Flow[..., Any]:
+    try:
+        return load_flow_from_entrypoint(entrypoint, use_placeholder_flow=False)
+    except MissingFlowError:
+        return load_function_and_convert_to_flow(entrypoint)
+
+
 def load_flow(flow_run: FlowRun) -> Flow[..., Any]:
     entrypoint = os.environ.get("PREFECT__FLOW_ENTRYPOINT")
 
     if entrypoint:
-        # we should not accept a placeholder flow at runtime
-        try:
-            flow = load_flow_from_entrypoint(entrypoint, use_placeholder_flow=False)
-        except MissingFlowError:
-            flow = load_function_and_convert_to_flow(entrypoint)
+        flow = _load_flow_from_runtime_entrypoint(entrypoint)
     else:
         flow = run_coro_as_sync(
             load_flow_from_flow_run(flow_run, use_placeholder_flow=False)
@@ -242,6 +250,51 @@ def load_flow_and_flow_run(flow_run_id: UUID) -> tuple[FlowRun, Flow[..., Any]]:
     return flow_run, flow
 
 
+def _run_flow_from_runtime_entrypoint(flow_run_id: UUID, entrypoint: str) -> None:
+    configure_from_env()
+
+    with handle_engine_signals(flow_run_id):
+        flow_run = load_flow_run(flow_run_id=flow_run_id)
+        run_logger = flow_run_logger(flow_run=flow_run)
+
+        try:
+            flow = _load_flow_from_runtime_entrypoint(entrypoint)
+        except Exception:
+            run_logger.error(
+                "Unexpected exception encountered when trying to load flow",
+                exc_info=True,
+            )
+            raise
+
+        with RunMetrics(flow_run, flow):
+            run_result = run_flow(flow, flow_run=flow_run, error_logger=run_logger)
+            _drive_run_flow_result(flow, run_result)
+
+
+def _main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        _engine_logger.error(
+            "Invalid flow entrypoint. Expected one argument; received: %s", args
+        )
+        return 1
+
+    flow_run_id_value = os.environ.get("PREFECT__FLOW_RUN_ID")
+    try:
+        flow_run_id = UUID(flow_run_id_value) if flow_run_id_value else None
+    except ValueError:
+        flow_run_id = None
+
+    if flow_run_id is None:
+        _engine_logger.error(
+            "Invalid flow run id. Expected PREFECT__FLOW_RUN_ID to contain a UUID."
+        )
+        return 1
+
+    _run_flow_from_runtime_entrypoint(flow_run_id, args[0])
+    return 0
+
+
 @contextmanager
 def _send_heartbeats(
     engine: "BaseFlowRunEngine[Any, Any]",
@@ -602,6 +655,32 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                 )
                 self.short_circuit = True
 
+        if (
+            not self.short_circuit
+            and not self._flow_run_name_set
+            and self.flow.flow_run_name
+        ):
+            if self.flow_run is None:
+                raise ValueError("Flow run not set")
+
+            with FlowRunContext(
+                flow=self.flow,
+                flow_run=self.flow_run,
+                parameters=self.parameters,
+                client=self.client,
+                task_runner=self.flow.task_runner,
+                result_store=get_result_store().update_for_flow(self.flow, _sync=True),
+            ):
+                flow_run_name = resolve_custom_flow_run_name(
+                    flow=self.flow, parameters=self.parameters or {}
+                )
+            self.client.set_flow_run_name(
+                flow_run_id=self.flow_run.id, name=flow_run_name
+            )
+            self.flow_run.name = flow_run_name
+            self._flow_run_name_set = True
+            self._telemetry.update_run_name(name=flow_run_name)
+
         new_state = Running()
         state = self.set_state(new_state)
         while state.is_pending():
@@ -927,6 +1006,12 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             if log_prints:
                 stack.enter_context(patch_print())
             task_runner = stack.enter_context(self.flow.task_runner.duplicate())
+            result_store = get_result_store().update_for_flow(self.flow, _sync=True)
+            persist_result = (
+                self.flow.persist_result
+                if self.flow.persist_result is not None
+                else _get_default_persist_result()
+            )
             stack.enter_context(
                 FlowRunContext(
                     flow=self.flow,
@@ -934,13 +1019,9 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                     flow_run=self.flow_run,
                     parameters=self.parameters,
                     client=client,
-                    result_store=get_result_store().update_for_flow(
-                        self.flow, _sync=True
-                    ),
+                    result_store=result_store,
                     task_runner=task_runner,
-                    persist_result=self.flow.persist_result
-                    if self.flow.persist_result is not None
-                    else should_persist_result(),
+                    persist_result=persist_result,
                 )
             )
             # Set deployment context vars only if this is the top-level deployment run
@@ -1248,6 +1329,32 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                 )
                 self.short_circuit = True
 
+        if (
+            not self.short_circuit
+            and not self._flow_run_name_set
+            and self.flow.flow_run_name
+        ):
+            if self.flow_run is None:
+                raise ValueError("Flow run not set")
+
+            with FlowRunContext(
+                flow=self.flow,
+                flow_run=self.flow_run,
+                parameters=self.parameters,
+                client=self.client,
+                task_runner=self.flow.task_runner,
+                result_store=get_result_store().update_for_flow(self.flow, _sync=True),
+            ):
+                flow_run_name = resolve_custom_flow_run_name(
+                    flow=self.flow, parameters=self.parameters or {}
+                )
+            await self.client.set_flow_run_name(
+                flow_run_id=self.flow_run.id, name=flow_run_name
+            )
+            self.flow_run.name = flow_run_name
+            self._flow_run_name_set = True
+            self._telemetry.update_run_name(name=flow_run_name)
+
         new_state = Running()
         state = await self.set_state(new_state)
         while state.is_pending():
@@ -1566,6 +1673,12 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             if log_prints:
                 stack.enter_context(patch_print())
             task_runner = stack.enter_context(self.flow.task_runner.duplicate())
+            result_store = get_result_store().update_for_flow(self.flow, _sync=True)
+            persist_result = (
+                self.flow.persist_result
+                if self.flow.persist_result is not None
+                else await _aget_default_persist_result()
+            )
             stack.enter_context(
                 FlowRunContext(
                     flow=self.flow,
@@ -1573,13 +1686,9 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                     flow_run=self.flow_run,
                     parameters=self.parameters,
                     client=client,
-                    result_store=get_result_store().update_for_flow(
-                        self.flow, _sync=True
-                    ),
+                    result_store=result_store,
                     task_runner=task_runner,
-                    persist_result=self.flow.persist_result
-                    if self.flow.persist_result is not None
-                    else should_persist_result(),
+                    persist_result=persist_result,
                 )
             )
             # Set deployment context vars only if this is the top-level deployment run
@@ -2119,3 +2228,7 @@ def run_flow_in_subprocess(
     process.start()
 
     return process
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())