prefect 3.7.3.dev3__py3-none-any.whl → 3.7.3.dev5__py3-none-any.whl

prefect/AGENTS.md

@@ -32,6 +32,7 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 - **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.
 - **Result storage resolves through three tiers, potentially making an API call.** `get_default_result_storage()` checks: (1) `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting, (2) server-configured default block (API call to the server's Configuration store), (3) local storage path. The API call is silently suppressed on any HTTP error. Engines use `_get_default_persist_result()` — not `should_persist_result()` — at context setup time to auto-enable persistence when a server default block is configured. Do not swap `_get_default_persist_result()` back to `should_persist_result()` in engine initialization paths; `should_persist_result()` does not consult the server default.
 - **`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.
+- **`ResultRecord` must be marked persisted after every storage write.** `ResultStore` calls `mark_persisted()` on every record it writes; `to_state_create` in `states.py` consults `is_persisted` as a fallback when `should_persist_result()` returns `False` (e.g., after run context teardown). Any new sync or async persist path that omits `mark_persisted()` will silently drop state metadata for already-written results.
 - **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
 
 ## Logging

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.7.3.dev3"
-__build_date__ = "2026-05-26 09:20:51.606541+00:00"
-__git_commit__ = "822447055dd0600580c832572eb9bdf8adca2cb9"
+__version__ = "3.7.3.dev5"
+__build_date__ = "2026-05-28 09:25:13.582068+00:00"
+__git_commit__ = "f7d76f21e9731cedf0462e3f9632133e1c23a439"
 __dirty__ = False

prefect/_internal/result_records.py

@@ -16,6 +16,7 @@ from uuid import UUID
 from pydantic import (
     BaseModel,
     Field,
+    PrivateAttr,
     ValidationError,
     field_validator,
     model_validator,
@@ -105,6 +106,14 @@ class ResultRecord(BaseModel, Generic[R]):
 
     metadata: ResultRecordMetadata
     result: R
+    _persisted: bool = PrivateAttr(default=False)
+
+    @property
+    def is_persisted(self) -> bool:
+        return self._persisted
+
+    def mark_persisted(self) -> None:
+        self._persisted = True
 
     @property
     def expiration(self) -> DateTime | None:

prefect/cli/_server_utils.py

@@ -274,6 +274,9 @@ def _run_in_background(
     keep_alive_timeout: int,
     no_services: bool,
     workers: int,
+    *,
+    ws_ping_interval: float = 20.0,
+    ws_ping_timeout: float = 20.0,
 ) -> None:
     command = [
         sys.executable,
@@ -292,6 +295,8 @@ def _run_in_background(
         "--workers",
         str(workers),
     ]
+    command.extend(["--ws-ping-interval", str(ws_ping_interval)])
+    command.extend(["--ws-ping-timeout", str(ws_ping_timeout)])
     logger.debug("Opening server process with command: %s", shlex.join(command))
 
     env = {**os.environ, **server_settings, "PREFECT__SERVER_FINAL": "1"}
@@ -322,6 +327,9 @@ def _run_in_foreground(
     keep_alive_timeout: int,
     no_services: bool,
     workers: int,
+    *,
+    ws_ping_interval: float = 20.0,
+    ws_ping_timeout: float = 20.0,
 ) -> None:
     from prefect.server.api.server import create_app
 
@@ -336,6 +344,8 @@ def _run_in_foreground(
                     host=host,
                     port=port,
                     timeout_keep_alive=keep_alive_timeout,
+                    ws_ping_interval=ws_ping_interval,
+                    ws_ping_timeout=ws_ping_timeout,
                     log_level=server_settings.get(
                         "PREFECT_SERVER_LOGGING_LEVEL", "info"
                     ).lower(),
@@ -351,6 +361,8 @@ def _run_in_foreground(
                     host=host,
                     port=port,
                     timeout_keep_alive=keep_alive_timeout,
+                    ws_ping_interval=ws_ping_interval,
+                    ws_ping_timeout=ws_ping_timeout,
                     log_level=server_settings.get(
                         "PREFECT_SERVER_LOGGING_LEVEL", "info"
                     ).lower(),

prefect/cli/server.py

@@ -133,6 +133,8 @@ def start(
         PREFECT_SERVER_API_HOST,
         PREFECT_SERVER_API_KEEPALIVE_TIMEOUT,
         PREFECT_SERVER_API_PORT,
+        PREFECT_SERVER_API_WEBSOCKET_PING_INTERVAL,
+        PREFECT_SERVER_API_WEBSOCKET_PING_TIMEOUT,
         PREFECT_SERVER_LOGGING_LEVEL,
         PREFECT_UI_ENABLED,
     )
@@ -146,6 +148,9 @@ def start(
         keep_alive_timeout = PREFECT_SERVER_API_KEEPALIVE_TIMEOUT.value()
     if log_level is None:
         log_level = PREFECT_SERVER_LOGGING_LEVEL.value()
+
+    ws_ping_interval = PREFECT_SERVER_API_WEBSOCKET_PING_INTERVAL.value()
+    ws_ping_timeout = PREFECT_SERVER_API_WEBSOCKET_PING_TIMEOUT.value()
     if analytics is None:
         analytics = PREFECT_SERVER_ANALYTICS_ENABLED.value()
     if scheduler is None:
@@ -229,6 +234,8 @@ def start(
             keep_alive_timeout,
             no_services,
             workers,
+            ws_ping_interval=ws_ping_interval,
+            ws_ping_timeout=ws_ping_timeout,
         )
     else:
         _run_in_foreground(
@@ -239,6 +246,8 @@ def start(
             keep_alive_timeout,
             no_services,
             workers,
+            ws_ping_interval=ws_ping_interval,
+            ws_ping_timeout=ws_ping_timeout,
         )
 
 

prefect/client/orchestration/__init__.py

@@ -137,6 +137,7 @@ from prefect.settings import (
 )
 from prefect.types._datetime import now
 
+from prefect._internal.urls import strip_auth_from_url
 from prefect._internal.version_checking import (
     _api_version_check_key,
     _cache_api_version_check,
@@ -1132,7 +1133,9 @@ class PrefectClient(
         except Exception as e:
             if "Unauthorized" in str(e):
                 raise e
-            raise RuntimeError(f"Failed to reach API at {self.api_url}") from e
+            raise RuntimeError(
+                f"Failed to reach API at {strip_auth_from_url(str(self.api_url))}"
+            ) from e
 
         api_version = version.parse(api_version)
         client_version = version.parse(self.client_version())
@@ -1190,7 +1193,9 @@ class PrefectClient(
                 f"{PREFECT_API_DATABASE_CONNECTION_URL.value()}"
             )
         else:
-            self.logger.debug(f"Connecting to API at {self.api_url}")
+            self.logger.debug(
+                f"Connecting to API at {strip_auth_from_url(str(self.api_url))}"
+            )
 
         # Enter the httpx client's context
         await self._exit_stack.enter_async_context(self._client)
@@ -1519,7 +1524,9 @@ class SyncPrefectClient(
         except Exception as e:
             if "Unauthorized" in str(e):
                 raise e
-            raise RuntimeError(f"Failed to reach API at {self.api_url}") from e
+            raise RuntimeError(
+                f"Failed to reach API at {strip_auth_from_url(str(self.api_url))}"
+            ) from e
 
         api_version = version.parse(api_version)
         client_version = version.parse(self.client_version())

prefect/results.py

@@ -867,6 +867,7 @@ class ResultStore(BaseModel):
 
         if self.cache_result_in_memory:
             self.cache[resolved_key_path] = result_record
+        result_record.mark_persisted()
         return result_record
 
     def _read(self, key: str, holder: str) -> "ResultRecord[Any]":
@@ -936,6 +937,7 @@ class ResultStore(BaseModel):
 
         if self.cache_result_in_memory:
             self.cache[resolved_key_path] = result_record
+        result_record.mark_persisted()
         return result_record
 
     def read(
@@ -1122,6 +1124,7 @@ class ResultStore(BaseModel):
                 (result_record.metadata.storage_key,),
                 {"content": result_record.serialize()},
             )
+        result_record.mark_persisted()
         if self.cache_result_in_memory:
             self.cache[key] = result_record
 
@@ -1185,6 +1188,7 @@ class ResultStore(BaseModel):
                 (result_record.metadata.storage_key,),
                 {"content": result_record.serialize()},
             )
+        result_record.mark_persisted()
         if self.cache_result_in_memory:
             self.cache[key] = result_record
 

prefect/runner/AGENTS.md

@@ -138,7 +138,11 @@ These validations exist to prevent git argument injection. Do not bypass them wh
 
 **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.
 
-**Automatic `uv` command selection:** When no explicit command is passed, `WorkspaceResolvingEngineCommandStarter` auto-selects `uv run --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 any condition fails, the command falls back to `None`. Explicit commands always take precedence.
+**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.
 
 ## Reference
 

prefect/runner/_workspace_resolver.py

@@ -174,6 +174,61 @@ def _workspace_destination_for_deployment_path(
     return (workspace_root / relative_destination).resolve()
 
 
+def _resolve_local_runtime_directory(
+    path: str | None, source_cwd: Path, storage_base_path: Path | None
+) -> Path:
+    resolved_path = _resolve_local_deployment_path(path, source_cwd, storage_base_path)
+    return Path(resolved_path).resolve() if resolved_path is not None else source_cwd
+
+
+def _entrypoint_file_path(entrypoint: str, working_directory: Path) -> Path | None:
+    entrypoint = _resolve_runtime_entrypoint(entrypoint)
+    if ":" not in entrypoint:
+        return None
+
+    path, _object_name = entrypoint.rsplit(":", 1)
+    if not path.endswith(".py"):
+        return None
+
+    entrypoint_path = Path(path).expanduser()
+    if not entrypoint_path.is_absolute():
+        entrypoint_path = working_directory / entrypoint_path
+    return entrypoint_path.resolve()
+
+
+def _has_entrypoint_file(entrypoint: str, working_directory: Path) -> bool:
+    entrypoint_path = _entrypoint_file_path(entrypoint, working_directory)
+    return entrypoint_path is not None and entrypoint_path.is_file()
+
+
+async def _ensure_entrypoint_in_workspace(
+    client: "PrefectClient",
+    deployment: "DeploymentResponse",
+    workspace_root: Path,
+    source_cwd: Path,
+    storage_base_path: Path | None,
+) -> Path:
+    if _has_entrypoint_file(deployment.entrypoint, workspace_root):
+        return workspace_root
+
+    local_runtime_directory = _resolve_local_runtime_directory(
+        deployment.path, source_cwd, storage_base_path
+    )
+    if not deployment.storage_document_id and not _has_entrypoint_file(
+        deployment.entrypoint, local_runtime_directory
+    ):
+        return workspace_root
+
+    await _pull_storage_into_workspace(
+        client,
+        deployment,
+        workspace_root,
+        source_cwd,
+        storage_base_path,
+    )
+    return workspace_root
+
+
 @contextlib.contextmanager
 def _redirect_stdout_to_stderr() -> Any:
     stdout = sys.stdout
@@ -218,9 +273,12 @@ async def _pull_storage_into_workspace(
             else None
         )
     else:
-        from_path = _resolve_local_deployment_path(
+        resolved_local_path = _resolve_local_deployment_path(
             deployment.path, source_cwd, storage_base_path
         )
+        from_path = (
+            resolved_local_path if resolved_local_path is not None else str(source_cwd)
+        )
         storage_block = LocalFileSystem(basepath=from_path)
 
     LOGGER.info("Downloading flow code from storage at %r", from_path)
@@ -253,11 +311,17 @@ async def prepare_workspace(
             source_cwd,
             storage_base_path,
         )
-        os.chdir(working_directory)
-        working_directory = Path.cwd().resolve()
+        local_runtime_directory = _resolve_local_runtime_directory(
+            deployment.path, source_cwd, storage_base_path
+        )
+        if not _has_entrypoint_file(
+            deployment.entrypoint, working_directory
+        ) and _has_entrypoint_file(deployment.entrypoint, local_runtime_directory):
+            working_directory = local_runtime_directory
     else:
+        working_directory = resolved_workspace_root
+        step_selected_working_directory = False
         os.chdir(resolved_workspace_root)
-        working_directory = Path.cwd().resolve()
         LOGGER.info("Running %s deployment pull step(s)", len(deployment.pull_steps))
 
         def _track_step_workspace(
@@ -266,17 +330,19 @@ async def prepare_workspace(
             step_start_cwd: Path | None,
             step_end_cwd: Path | None,
         ) -> None:
-            nonlocal working_directory
+            nonlocal step_selected_working_directory, working_directory
 
             if isinstance(step_output, dict) and step_output.get("directory"):
                 resolved_directory = _resolve_directory_output(
                     step_output, step_end_cwd
                 )
                 if resolved_directory is not None:
+                    step_selected_working_directory = True
                     working_directory = resolved_directory
                 return
 
             if step_end_cwd is not None and step_end_cwd != step_start_cwd:
+                step_selected_working_directory = True
                 working_directory = step_end_cwd
 
         with _observe_step_completion(_track_step_workspace):
@@ -288,6 +354,18 @@ async def prepare_workspace(
                 logger=LOGGER,
             )
 
+        if not step_selected_working_directory:
+            working_directory = await _ensure_entrypoint_in_workspace(
+                client,
+                deployment,
+                resolved_workspace_root,
+                source_cwd,
+                storage_base_path,
+            )
+
+    os.chdir(working_directory)
+    working_directory = Path.cwd().resolve()
+
     project_root = _find_project_root(working_directory, resolved_workspace_root)
     return PreparedWorkspace(
         workspace_root=resolved_workspace_root,

prefect/runner/_workspace_starter.py

@@ -167,6 +167,9 @@ def _pyproject_declares_prefect_dependency(pyproject: Path) -> bool:
 
 
 def _uv_run_command(workspace: PreparedWorkspace) -> str | None:
+    if not get_current_settings().runner.auto_install_dependencies:
+        return None
+
     project_root = workspace.project_root
     if project_root is None:
         return None
@@ -188,6 +191,7 @@ def _uv_run_command(workspace: PreparedWorkspace) -> str | None:
         [
             uv_executable,
             "run",
+            "--no-default-groups",
             "--project",
             str(project_root),
             "-m",

prefect/server/AGENTS.md

@@ -66,6 +66,7 @@ Both V1 and V2 UI bundles are served simultaneously when available: V1 at `PREFE
 - `events/` — Server-side event processing: trigger evaluation, action execution, messaging, streaming (see also `../events/` for client-side schemas)
 - `concurrency/` — Server-side concurrency management
 - `logs/` — Log storage and retrieval
+- `worker_communication/` — Pluggable server-side messaging to workers: cleanup delivery queue for expired/cancelled flow run teardown. The abstract interface is in `cleanup_queue/__init__.py`; the default in-memory backend (`cleanup_queue/memory.py`) is a process-level singleton and is not restart-safe. Configure `PREFECT_SERVER_WORKER_CHANNEL_CLEANUP_QUEUE_STORAGE` to point to a module exposing a concrete `WorkerCleanupQueue` subclass for HA or Redis-backed deployments.
 
 ## Related
 

prefect/server/__init__.py

@@ -1,3 +1,22 @@
-from . import models, orchestration, schemas, services
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prefect.server import models, orchestration, schemas, services
 
 __all__ = ["models", "orchestration", "schemas", "services"]
+
+
+def __getattr__(name: str) -> object:
+    module_name = f"{__name__}.{name}"
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != module_name:
+            raise
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+    globals()[name] = module
+    return module

prefect/server/api/__init__.py

@@ -1,33 +1,86 @@
-from . import (
-    artifacts,
-    admin,
-    automations,
-    block_capabilities,
-    block_documents,
-    block_schemas,
-    block_types,
-    collections,
-    concurrency_limits,
-    concurrency_limits_v2,
-    csrf_token,
-    dependencies,
-    deployments,
-    events,
-    flow_run_states,
-    flow_runs,
-    flows,
-    logs,
-    middleware,
-    root,
-    run_history,
-    saved_searches,
-    task_run_states,
-    task_runs,
-    task_workers,
-    templates,
-    ui,
-    variables,
-    work_queues,
-    workers,
-)
-from . import server  # Server relies on all of the above routes
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prefect.server.api import (
+        admin,
+        artifacts,
+        automations,
+        block_capabilities,
+        block_documents,
+        block_schemas,
+        block_types,
+        collections,
+        concurrency_limits,
+        concurrency_limits_v2,
+        csrf_token,
+        dependencies,
+        deployments,
+        events,
+        flow_run_states,
+        flow_runs,
+        flows,
+        logs,
+        middleware,
+        root,
+        run_history,
+        saved_searches,
+        server,
+        task_run_states,
+        task_runs,
+        task_workers,
+        templates,
+        ui,
+        variables,
+        work_queues,
+        workers,
+    )
+
+__all__ = [
+    "admin",
+    "artifacts",
+    "automations",
+    "block_capabilities",
+    "block_documents",
+    "block_schemas",
+    "block_types",
+    "collections",
+    "concurrency_limits",
+    "concurrency_limits_v2",
+    "csrf_token",
+    "dependencies",
+    "deployments",
+    "events",
+    "flow_run_states",
+    "flow_runs",
+    "flows",
+    "logs",
+    "middleware",
+    "root",
+    "run_history",
+    "saved_searches",
+    "server",
+    "task_run_states",
+    "task_runs",
+    "task_workers",
+    "templates",
+    "ui",
+    "variables",
+    "work_queues",
+    "workers",
+]
+
+
+def __getattr__(name: str) -> object:
+    module_name = f"{__name__}.{name}"
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != module_name:
+            raise
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+    globals()[name] = module
+    return module

prefect/server/orchestration/core_policy.py

@@ -1159,8 +1159,9 @@ class RetryFailedTasks(TaskRunOrchestrationRule):
         else:
             base_delay = delay or 0
 
-        # guard against negative relative jitter inputs
-        if run_settings.retry_jitter_factor:
+        # guard against negative relative jitter inputs; also guard against
+        # base_delay == 0: clamped_poisson_interval(0, ...) divides by zero.
+        if run_settings.retry_jitter_factor and base_delay > 0:
             delay = clamped_poisson_interval(
                 base_delay, clamping_factor=run_settings.retry_jitter_factor
             )

prefect/server/schemas/__init__.py

@@ -1,25 +1,44 @@
-from . import (
-    states,
-    statuses,
-    schedules,
-    core,
-    sorting,
-    filters,
-    responses,
-    actions,
-    internal,
-    ui,
-)  # noqa
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prefect.server.schemas import (
+        actions,
+        core,
+        filters,
+        internal,
+        responses,
+        schedules,
+        sorting,
+        states,
+        statuses,
+        ui,
+    )
 
 __all__ = [
     "actions",
     "core",
     "filters",
+    "internal",
     "responses",
     "schedules",
     "sorting",
     "states",
     "statuses",
-    "internal",
     "ui",
 ]
+
+
+def __getattr__(name: str) -> object:
+    module_name = f"{__name__}.{name}"
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != module_name:
+            raise
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+    globals()[name] = module
+    return module

prefect/server/services/scheduler.py

@@ -74,7 +74,12 @@ def _get_select_deployments_to_schedule_query(
             db.FlowRun.deployment_id == db.DeploymentSchedule.deployment_id,
             db.FlowRun.state_type == StateType.SCHEDULED,
             db.FlowRun.next_scheduled_start_time >= right_now,
-            db.FlowRun.auto_scheduled.is_(True),
+            # `== true` (not `.is_(True)`) so the predicate matches the
+            # `auto_scheduled = true` clause of the partial index
+            # `ix_flow_run__schedule_id_scheduler`.  PostgreSQL's predicate
+            # implication prover does not treat `IS true` as implying
+            # `= true`, so `.is_(True)` silently disqualifies the index.
+            db.FlowRun.auto_scheduled == sa.true(),
             schedule_id_match,
         )
         .correlate(db.DeploymentSchedule)
@@ -88,7 +93,7 @@ def _get_select_deployments_to_schedule_query(
             db.FlowRun.deployment_id == db.DeploymentSchedule.deployment_id,
             db.FlowRun.state_type == StateType.SCHEDULED,
             db.FlowRun.next_scheduled_start_time >= right_now,
-            db.FlowRun.auto_scheduled.is_(True),
+            db.FlowRun.auto_scheduled == sa.true(),
             schedule_id_match,
         )
         .correlate(db.DeploymentSchedule)