prefect-client 3.6.26.dev5__tar.gz → 3.6.27.dev1__tar.gz

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.26.dev5
+Version: 3.6.27.dev1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -61,7 +61,7 @@ Requires-Dist: toml>=0.10.0
 Requires-Dist: typing-extensions<5.0.0,>=4.10.0
 Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<17.0,>=15.0.1
-Requires-Dist: whenever<0.10.0,>=0.7.3; python_version >= '3.13'
+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'
 Description-Content-Type: text/markdown

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/pyproject.toml

@@ -65,7 +65,7 @@ dependencies = [
     "typing_extensions>=4.10.0,<5.0.0",
     "uvicorn>=0.14.0,!=0.29.0",
     "websockets>=15.0.1,<17.0",
-    "whenever>=0.7.3,<0.10.0; python_version>='3.13'",
+    "whenever>=0.7.3,<0.11.0; python_version>='3.13'",
 ]
 [project.urls]
 Changelog = "https://github.com/PrefectHQ/prefect/releases"

prefect_client-3.6.27.dev1/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.27.dev1"
+__build_date__ = "2026-04-11 08:17:41.232710+00:00"
+__git_commit__ = "5af4fc87319840e60ce9f6dcc6b10f8e61d78114"
+__dirty__ = False

prefect_client-3.6.27.dev1/src/prefect/_experimental/_launchers.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from prefect._experimental.bundles import (
+        BundleLauncher,
+        BundleLauncherOverride,
+        BundleLauncherSide,
+    )
+
+
+def validate_bundle_step_launcher(
+    launcher: Any, *, field_name: str = "launcher"
+) -> list[str]:
+    if not isinstance(launcher, list) or not launcher:
+        raise ValueError(f"{field_name} must be a non-empty list[str]")
+
+    normalized: list[str] = []
+    for i, item in enumerate(launcher):
+        if not isinstance(item, str) or not item.strip():
+            raise ValueError(f"{field_name}[{i}] must be a non-empty string")
+        normalized.append(item)
+
+    return normalized
+
+
+def normalize_launcher(
+    launcher: BundleLauncher | None,
+) -> BundleLauncherOverride | None:
+    if launcher is None:
+        return None
+
+    if isinstance(launcher, list):
+        normalized_launcher = validate_bundle_step_launcher(
+            launcher, field_name="launcher"
+        )
+        return {
+            "upload": normalized_launcher.copy(),
+            "execution": normalized_launcher.copy(),
+        }
+
+    if not isinstance(launcher, dict):
+        raise TypeError(
+            "launcher must be a list[str] or a mapping with 'upload'/'execution' keys"
+        )
+
+    allowed_keys = {"upload", "execution"}
+    invalid_keys = sorted(set(launcher) - allowed_keys)
+    if invalid_keys:
+        raise ValueError(
+            f"launcher may only specify 'upload' and 'execution'; got {invalid_keys!r}"
+        )
+
+    if not launcher:
+        raise ValueError(
+            "launcher must specify at least one of 'upload' or 'execution'"
+        )
+
+    normalized: BundleLauncherOverride = {}
+    for side in ("upload", "execution"):
+        if side in launcher:
+            normalized[side] = validate_bundle_step_launcher(
+                launcher[side],
+                field_name=f"launcher[{side!r}]",
+            )
+
+    return normalized
+
+
+def get_launcher_for_side(
+    launcher: BundleLauncher | None,
+    side: BundleLauncherSide,
+) -> list[str] | None:
+    normalized = normalize_launcher(launcher)
+    if normalized is None:
+        return None
+
+    launcher = normalized.get(side)
+    return launcher.copy() if launcher is not None else None
+
+
+def resolve_bundle_step_with_launcher(
+    step: dict[str, Any],
+    launcher: BundleLauncher | None,
+    side: BundleLauncherSide,
+) -> dict[str, Any]:
+    resolved_step = deepcopy(step)
+    resolved_launcher = get_launcher_for_side(launcher, side)
+
+    if resolved_launcher is None:
+        return resolved_step
+
+    step_keys = list(resolved_step.keys())
+    if len(step_keys) != 1:
+        return resolved_step
+
+    function_args = resolved_step[step_keys[0]]
+    if not isinstance(function_args, dict):
+        return resolved_step
+
+    function_args["launcher"] = resolved_launcher
+    function_args.pop("requires", None)
+
+    return resolved_step

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/_experimental/bundles/__init__.py

@@ -19,7 +19,7 @@ from pathlib import Path
 from types import ModuleType
 from typing import Any, TypedDict
 
-from typing_extensions import NotRequired
+from typing_extensions import Literal, NotRequired, TypeAlias
 
 import anyio
 import cloudpickle  # pyright: ignore[reportMissingTypeStubs]
@@ -34,11 +34,23 @@ from prefect.settings.context import get_current_settings
 from prefect.settings.models.root import Settings
 from prefect.utilities.slugify import slugify
 
+from prefect._experimental._launchers import validate_bundle_step_launcher
+
 from .execute import execute_bundle_from_file
 from ._file_collector import FileCollector
 from ._ignore_filter import IgnoreFilter, check_sensitive_files
 from ._zip_builder import ZipBuilder
 
+BundleLauncherSide = Literal["upload", "execution"]
+
+
+class BundleLauncherOverride(TypedDict, total=False):
+    upload: list[str]
+    execution: list[str]
+
+
+BundleLauncher: TypeAlias = list[str] | BundleLauncherOverride
+
 logger: logging.Logger = get_logger(__name__)
 
 
@@ -57,6 +69,21 @@ def _get_uv_path() -> str:
         return "uv"
 
 
+def _called_process_error_message(exc: subprocess.CalledProcessError) -> str:
+    for stream in (exc.stderr, exc.output):
+        if isinstance(stream, bytes):
+            message = stream.decode("utf-8", errors="replace").strip()
+        elif isinstance(stream, str):
+            message = stream.strip()
+        else:
+            continue
+
+        if message:
+            return message
+
+    return str(exc)
+
+
 class SerializedBundle(TypedDict):
     """
     A serialized bundle is a serialized function, context, and flow run that can be
@@ -579,12 +606,6 @@ def convert_step_to_command(
     Returns:
         A list of strings representing the command to run the step.
     """
-    # Start with uv run
-    command = ["uv", "run"]
-
-    if quiet:
-        command.append("--quiet")
-
     step_keys = list(step.keys())
 
     if len(step_keys) != 1:
@@ -592,24 +613,38 @@ def convert_step_to_command(
 
     function_fqn = step_keys[0]
     function_args = step[function_fqn]
-
-    # Add the `--with` argument to handle dependencies for running the step
     requires: list[str] | str = function_args.get("requires", [])
+    launcher = function_args.get("launcher")
+
     if isinstance(requires, str):
         requires = [requires]
-    if requires:
-        command.extend(["--with", ",".join(requires)])
 
-    # Add the `--python` argument to handle the Python version for running the step
-    python_version = sys.version_info
-    command.extend(["--python", f"{python_version.major}.{python_version.minor}"])
+    if launcher is not None:
+        command = validate_bundle_step_launcher(launcher)
+        if requires:
+            raise ValueError(
+                "Bundle step launcher cannot be combined with step requirements"
+            )
+    else:
+        command = ["uv", "run"]
+
+        if quiet:
+            command.append("--quiet")
+
+        # Add the `--with` argument to handle dependencies for running the step
+        if requires:
+            command.extend(["--with", ",".join(requires)])
+
+        # Add the `--python` argument to handle the Python version for running the step
+        python_version = sys.version_info
+        command.extend(["--python", f"{python_version.major}.{python_version.minor}"])
 
     # Add the `-m` argument to defined the function to run
     command.extend(["-m", function_fqn])
 
     # Add any arguments with values defined in the step
     for arg_name, arg_value in function_args.items():
-        if arg_name == "requires":
+        if arg_name in {"launcher", "requires"}:
             continue
 
         command.extend([f"--{slugify(arg_name)}", arg_value])
@@ -681,7 +716,7 @@ def upload_bundle_to_storage(
                 )
 
         except subprocess.CalledProcessError as e:
-            raise RuntimeError(e.stderr.decode("utf-8")) from e
+            raise RuntimeError(_called_process_error_message(e)) from e
 
 
 async def aupload_bundle_to_storage(
@@ -749,7 +784,7 @@ async def aupload_bundle_to_storage(
                 )
 
         except subprocess.CalledProcessError as e:
-            raise RuntimeError(e.stderr.decode("utf-8")) from e
+            raise RuntimeError(_called_process_error_message(e)) from e
 
 
 __all__ = [

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/flows.py

@@ -47,6 +47,10 @@ from exceptiongroup import BaseExceptionGroup, ExceptionGroup
 from rich.console import Console
 from typing_extensions import Literal, ParamSpec
 
+from prefect._experimental._launchers import (
+    normalize_launcher,
+    resolve_bundle_step_with_launcher,
+)
 from prefect._experimental.sla.objects import SlaTypes
 from prefect._internal.concurrency.api import create_call, from_async, from_sync
 from prefect._versioning import VersionType
@@ -96,12 +100,14 @@ from prefect.utilities.collections import listrepr, visit_collection
 from prefect.utilities.filesystem import relative_path_to_current_platform
 from prefect.utilities.hashing import file_hash
 from prefect.utilities.importtools import import_object, safe_load_namespace
+from prefect.utilities.processutils import command_to_string
 
 from ._internal.compatibility.async_dispatch import async_dispatch, is_in_async_context
 from ._internal.pydantic.v2_schema import is_v2_type
 from ._internal.pydantic.validated_func import ValidatedFunction
 
 if TYPE_CHECKING:
+    from prefect._experimental.bundles import BundleLauncher, BundleLauncherOverride
     from prefect.docker.docker_image import DockerImage
     from prefect.workers.base import BaseWorker
 
@@ -2276,6 +2282,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
             infrastructure the flow will run on.
         job_variables: Infrastructure configuration that will override the base job
             configuration of the work pool.
+        launcher: Optional upload and execution launcher overrides.
         worker_cls: The class of the worker to use to spin up infrastructure and submit
             the flow to it.
     """
@@ -2286,6 +2293,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         work_pool: str,
         job_variables: dict[str, Any],
         worker_cls: type["BaseWorker[Any, Any, Any]"],
+        launcher: BundleLauncher | None = None,
         include_files: Sequence[str] | None = None,
         **kwargs: Any,
     ):
@@ -2293,6 +2301,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         self.work_pool = work_pool
         self.job_variables = job_variables
         self.worker_cls = worker_cls
+        self.launcher: BundleLauncherOverride | None = normalize_launcher(launcher)
         self.include_files: list[str] | None = (
             list(include_files) if include_files is not None else None
         )
@@ -2579,18 +2588,28 @@ class InfrastructureBoundFlow(Flow[P, R]):
             else:
                 flow = self
 
+            upload_step = work_pool.storage_configuration.bundle_upload_step
+            execute_step = work_pool.storage_configuration.bundle_execution_step
+            assert upload_step is not None
+            assert execute_step is not None
+
+            upload_step = resolve_bundle_step_with_launcher(
+                upload_step, self.launcher, "upload"
+            )
+            execute_step = resolve_bundle_step_with_launcher(
+                execute_step, self.launcher, "execution"
+            )
+
             bundle_key = str(uuid.uuid4())
             upload_command = convert_step_to_command(
-                work_pool.storage_configuration.bundle_upload_step,
+                upload_step,
                 bundle_key,
                 quiet=True,
             )
-            execute_command = convert_step_to_command(
-                work_pool.storage_configuration.bundle_execution_step, bundle_key
-            )
+            execute_command = convert_step_to_command(execute_step, bundle_key)
 
             job_variables = (self.job_variables or {}) | {
-                "command": " ".join(execute_command)
+                "command": command_to_string(execute_command)
             }
 
             # Create a parent task run if this is a child flow run to ensure it shows up as a child flow in the UI
@@ -2625,7 +2644,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
                 bundle_key,
                 upload_command,
                 zip_path=result["zip_path"],
-                upload_step=work_pool.storage_configuration.bundle_upload_step,
+                upload_step=upload_step,
             )
 
             # Set flow run to scheduled now that the bundle is uploaded and ready to be executed
@@ -2659,6 +2678,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         on_crashed: Optional[list[FlowStateHook[P, R]]] = None,
         on_running: Optional[list[FlowStateHook[P, R]]] = None,
         job_variables: Optional[dict[str, Any]] = None,
+        launcher: BundleLauncher | None = NotSet,  # type: ignore
         include_files: Optional[list[str]] = NotSet,  # type: ignore
     ) -> "InfrastructureBoundFlow[P, R]":
         new_flow = super().with_options(
@@ -2689,6 +2709,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
             job_variables=job_variables
             if job_variables is not None
             else self.job_variables,
+            launcher=launcher if launcher is not NotSet else self.launcher,
             include_files=include_files
             if include_files is not NotSet
             else self.include_files,
@@ -2701,6 +2722,7 @@ def bind_flow_to_infrastructure(
     work_pool: str,
     worker_cls: type["BaseWorker[Any, Any, Any]"],
     job_variables: dict[str, Any] | None = None,
+    launcher: BundleLauncher | None = None,
     include_files: Sequence[str] | None = None,
 ) -> InfrastructureBoundFlow[P, R]:
     new = InfrastructureBoundFlow[P, R](
@@ -2708,11 +2730,17 @@ def bind_flow_to_infrastructure(
         work_pool=work_pool,
         job_variables=job_variables or {},
         worker_cls=worker_cls,
+        launcher=launcher,
         include_files=include_files,
     )
     # Copy all attributes from the original flow
     for attr, value in flow.__dict__.items():
         setattr(new, attr, value)
+    new.work_pool = work_pool
+    new.job_variables = job_variables or {}
+    new.worker_cls = worker_cls
+    new.launcher = normalize_launcher(launcher)
+    new.include_files = list(include_files) if include_files is not None else None
     return new
 
 

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/runner/_starter_engine.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import os
-import shlex
 import subprocess
 import sys
 from pathlib import Path
@@ -12,7 +11,11 @@ import anyio.abc
 
 from prefect.runner._process_manager import ProcessHandle
 from prefect.settings import get_current_settings
-from prefect.utilities.processutils import get_sys_executable, run_process
+from prefect.utilities.processutils import (
+    command_from_string,
+    get_sys_executable,
+    run_process,
+)
 
 if TYPE_CHECKING:
     from prefect.client.schemas.objects import FlowRun
@@ -59,7 +62,7 @@ class EngineCommandStarter:
         if self._command is None:
             runner_command = [get_sys_executable(), "-m", "prefect.engine"]
         else:
-            runner_command = shlex.split(self._command, posix=(os.name != "nt"))
+            runner_command = command_from_string(self._command)
 
         # We must add creationflags to a dict so it is only passed as a
         # function parameter on Windows, because the presence of

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/runner/runner.py

@@ -39,7 +39,6 @@ import datetime
 import logging
 import multiprocessing.context
 import os
-import shlex
 import shutil
 import signal
 import subprocess
@@ -135,6 +134,7 @@ from prefect.utilities.engine import (  # noqa: F401 (patch target)
     propose_state_sync,
 )
 from prefect.utilities.processutils import (
+    command_from_string,
     get_sys_executable,
     run_process,
 )
@@ -900,7 +900,7 @@ class Runner:
         if command is None:
             runner_command = [get_sys_executable(), "-m", "prefect.engine"]
         else:
-            runner_command = shlex.split(command, posix=(os.name != "nt"))
+            runner_command = command_from_string(command)
 
         flow_run_logger = self._get_flow_run_logger(flow_run)
 

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/types/_datetime.py

@@ -124,7 +124,14 @@ def now(
         if isinstance(getattr(tz, "name", None), str):
             tz = tz.name
 
-        return ZonedDateTime.now(tz).py_datetime()
+        zoned_datetime = ZonedDateTime.now(tz)
+
+        # `whenever` is deprecating `py_datetime()` in favor of `to_stdlib()`,
+        # but older releases in our supported range do not expose `to_stdlib()`.
+        if callable(to_stdlib := getattr(zoned_datetime, "to_stdlib", None)):
+            return to_stdlib()
+
+        return zoned_datetime.py_datetime()
     else:
         return pendulum.now(tz)
 

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/utilities/AGENTS.md

@@ -15,7 +15,7 @@ Does NOT include: server-specific utilities (`server/utilities/`), concurrency s
 - `callables.py` — Function signature introspection and parameter coercion
 - `collections.py` — Extended collection helpers (visit, flatten, remove nested keys)
 - `annotations.py` — Custom Prefect type annotations used in flow/task signatures
-- `processutils.py` — Subprocess execution and output streaming helpers (`run_process`, `consume_process_output`, `stream_text`)
+- `processutils.py` — Subprocess execution, output streaming, and command serialization helpers (`run_process`, `consume_process_output`, `stream_text`, `command_to_string`, `command_from_string`)
 - `pydantic.py` — Pydantic v1/v2 compatibility shims
 - `templating.py` — Jinja template utilities and `maybe_template()` detection
 - `filesystem.py` — File filtering (`filter_files`), path normalization, and `tmpchdir` context manager
@@ -77,3 +77,5 @@ Handlers return `Placeholder` subclasses (e.g. `RemoveValue`, `InvalidJSON`, `In
 - **Passing the same key in both an explicit parameter and a `**kwargs` dict raises `TypeError`.** `parameters_to_args_kwargs` detects when a VAR_KEYWORD (`**kwargs`) dict contains a key that also appears as an explicit parameter and raises rather than silently letting the variadic entry win. Exception: POSITIONAL_ONLY parameters are exempt because `fn(1, **{'a': 2})` is legal when `a` is positional-only.
 - **`filter_files` with `include_dirs=True` (the default) always includes all ancestor directories of matched files**, even if those directories weren't directly matched by the ignore patterns. This ensures `shutil.copytree`'s `ignore_func` doesn't skip directories containing files that should be copied. Side effect: callers expecting only pathspec-matched entries will receive additional directory paths. The parent-dir expansion does NOT run when `include_dirs=False`.
 - **Never access `EngineContext.run_results` directly via `id(obj)`.** Always call `get_state_for_result(obj)`.
+- **`command_to_string` always uses POSIX quoting (`shlex.join`), even on Windows.** This is intentional for platform-neutral storage — bundle commands are serialized by one platform and may be deserialized by another. `command_from_string` uses a dual-path approach: if the string was POSIX-serialized by Prefect (round-trips cleanly through `shlex.split`/`shlex.join`), it uses POSIX parsing; otherwise it falls back to native Windows command-line parsing (`CommandLineToArgvW`). Do not use `" ".join(command)` or `shlex.split(command)` directly when working with stored Prefect commands — use these helpers instead.
+- **`get_sys_executable()` no longer quotes the Python path on Windows.** It previously returned `'"path/to/python"'` (with embedded quotes) on Windows; now it returns the raw path. Code relying on the old quoted form (e.g., joining into a shell string) will break — use `subprocess.list2cmdline` or `command_to_string` for shell-safe serialization instead.

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/utilities/processutils.py

@@ -1,5 +1,6 @@
 import asyncio
 import os
+import shlex
 import signal
 import subprocess
 import sys
@@ -35,9 +36,24 @@ PrintFn: TypeAlias = Callable[[str], object]
 T = TypeVar("T", infer_variance=True)
 
 if sys.platform == "win32":
-    from ctypes import WINFUNCTYPE, c_int, c_uint, windll
+    from ctypes import (
+        POINTER,
+        WINFUNCTYPE,
+        byref,
+        c_int,
+        c_uint,
+        c_void_p,
+        c_wchar_p,
+        windll,
+    )
 
     _windows_process_group_pids = set()
+    _command_line_to_argv = windll.shell32.CommandLineToArgvW
+    _command_line_to_argv.argtypes = [c_wchar_p, POINTER(c_int)]
+    _command_line_to_argv.restype = POINTER(c_wchar_p)
+    _local_free = windll.kernel32.LocalFree
+    _local_free.argtypes = [c_void_p]
+    _local_free.restype = c_void_p
 
     @WINFUNCTYPE(c_int, c_uint)
     def _win32_ctrl_handler(dwCtrlType: object) -> int:
@@ -185,6 +201,65 @@ if sys.platform == "win32":
         )
 
 
+def _parse_prefect_serialized_command(command: str) -> list[str] | None:
+    """Return argv for strings produced by `command_to_string`, if any."""
+    try:
+        parts = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+
+    if shlex.join(parts) != command:
+        return None
+
+    return parts
+
+
+if sys.platform == "win32":
+
+    def _split_windows_command_string(command: str) -> list[str]:
+        argc = c_int(0)
+        argv = _command_line_to_argv(c_wchar_p(command), byref(argc))
+        if not argv:
+            raise OSError("CommandLineToArgvW failed to parse command string.")
+        try:
+            return [argv[index] for index in range(argc.value)]
+        finally:
+            _local_free(argv)
+
+else:
+
+    def _split_windows_command_string(command: str) -> list[str]:
+        # Preserve pre-existing behavior for local tests on non-Windows hosts.
+        return shlex.split(command, posix=False)
+
+
+def command_to_string(command: list[str]) -> str:
+    """
+    Serialize a command list to a platform-neutral string.
+
+    We use POSIX shell quoting so stored commands round-trip across platforms
+    when paired with `command_from_string`.
+    """
+    return shlex.join(command)
+
+
+def command_from_string(command: str) -> list[str]:
+    """
+    Parse a command string back into argv tokens.
+
+    Prefect-owned command strings use POSIX shell quoting. Other command
+    strings keep native parsing so existing Windows configuration still works.
+    """
+    serialized_command = _parse_prefect_serialized_command(command)
+    if serialized_command is not None:
+        return serialized_command
+
+    if sys.platform == "win32":
+        return _split_windows_command_string(command)
+
+    return shlex.split(command, posix=True)
+
+
 @asynccontextmanager
 async def open_process(
     command: list[str], **kwargs: Any
@@ -206,7 +281,7 @@ async def open_process(
             )
 
     if sys.platform == "win32":
-        command = " ".join(command)
+        command = subprocess.list2cmdline(command)
         process = await _open_anyio_process(command, **kwargs)
     else:
         process = await anyio.open_process(command, **kwargs)
@@ -473,10 +548,4 @@ def setup_signal_handlers_worker(
 
 
 def get_sys_executable() -> str:
-    # python executable needs to be quotable on windows
-    if os.name == "nt":
-        executable_path = f'"{sys.executable}"'
-    else:
-        executable_path = sys.executable
-
-    return executable_path
+    return sys.executable

{prefect_client-3.6.26.dev5 → prefect_client-3.6.27.dev1}/src/prefect/workers/AGENTS.md

@@ -26,6 +26,14 @@ Workers stamp two env vars into `os.environ` for their own process, so all API r
 
 These are separate from the per-flow-run attribution vars injected into the child process environment by `prepare_for_flow_run(worker_name=..., worker_id=...)`.
 
+## Bundle Launcher Override
+
+When a flow is decorated with an infrastructure decorator (`@docker`, `@ecs`, `@kubernetes`, etc.) and a `launcher` argument is supplied, `InfrastructureBoundFlow` stores a normalized `BundleLauncherOverride` on `flow.launcher`. `BaseWorker.submit()` extracts this via `getattr(flow, "launcher", None)` and calls `resolve_bundle_step_with_launcher(step, launcher, side)` before converting steps to commands.
+
+**Non-obvious:** the launcher replaces the `uv run ...` prefix entirely. With a launcher, the resulting command is `[*launcher, "-m", "<module>", "--key", "<path>"]` rather than `["uv", "run", "--with", "...", "--python", "X.Y", "-m", "<module>", "--key", "<path>"]`. Launchers and `requires` are mutually exclusive — `convert_step_to_command` raises `ValueError` if a step has both.
+
+Work-pool-level launchers are configured via `prefect work-pool storage configure s3|gcs|azure --launcher <executable>` and are stored in the step dict itself. Flow-level launchers (via the decorator) are resolved at submit time and win over the work-pool step configuration.
+
 ## Anti-Patterns
 
 - Do not set `PREFECT__WORKER_NAME` / `PREFECT__WORKER_ID` in `os.environ` from outside `BaseWorker` — setup/teardown own this lifecycle.