prefect-client 3.2.5__tar.gz → 3.2.7__tar.gz

{prefect_client-3.2.5 → prefect_client-3.2.7}/PKG-INFO

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

prefect_client-3.2.7/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.2.7"
+__build_date__ = "2025-02-21 19:38:38.599741+00:00"
+__git_commit__ = "d4d9001e40eb378ec68a97f7e3bab07d89c7557c"
+__dirty__ = False

prefect_client-3.2.7/src/prefect/_experimental/bundles.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import gzip
+import multiprocessing
+import multiprocessing.context
+import os
+from typing import Any, TypedDict
+
+import cloudpickle
+
+from prefect.client.schemas.objects import FlowRun
+from prefect.context import SettingsContext, get_settings_context, serialize_context
+from prefect.engine import handle_engine_signals
+from prefect.flow_engine import run_flow
+from prefect.flows import Flow
+from prefect.settings.context import get_current_settings
+from prefect.settings.models.root import Settings
+
+
+class SerializedBundle(TypedDict):
+    """
+    A serialized bundle is a serialized function, context, and flow run that can be
+    easily transported for later execution.
+    """
+
+    function: str
+    context: str
+    flow_run: dict[str, Any]
+
+
+def _serialize_bundle_object(obj: Any) -> str:
+    """
+    Serializes an object to a string.
+    """
+    return base64.b64encode(gzip.compress(cloudpickle.dumps(obj))).decode()
+
+
+def _deserialize_bundle_object(serialized_obj: str) -> Any:
+    """
+    Deserializes an object from a string.
+    """
+    return cloudpickle.loads(gzip.decompress(base64.b64decode(serialized_obj)))
+
+
+def create_bundle_for_flow_run(
+    flow: Flow[Any, Any],
+    flow_run: FlowRun,
+    context: dict[str, Any] | None = None,
+) -> SerializedBundle:
+    """
+    Creates a bundle for a flow run.
+
+    Args:
+        flow: The flow to bundle.
+        flow_run: The flow run to bundle.
+        context: The context to use when running the flow.
+
+    Returns:
+        A serialized bundle.
+    """
+    context = context or serialize_context()
+
+    return {
+        "function": _serialize_bundle_object(flow),
+        "context": _serialize_bundle_object(context),
+        "flow_run": flow_run.model_dump(mode="json"),
+    }
+
+
+def extract_flow_from_bundle(bundle: SerializedBundle) -> Flow[Any, Any]:
+    """
+    Extracts a flow from a bundle.
+    """
+    return _deserialize_bundle_object(bundle["function"])
+
+
+def _extract_and_run_flow(
+    bundle: SerializedBundle, env: dict[str, Any] | None = None
+) -> None:
+    """
+    Extracts a flow from a bundle and runs it.
+
+    Designed to be run in a subprocess.
+
+    Args:
+        bundle: The bundle to extract and run.
+        env: The environment to use when running the flow.
+    """
+
+    os.environ.update(env or {})
+    # TODO: make this a thing we can pass directly to the engine
+    os.environ["PREFECT__ENABLE_CANCELLATION_AND_CRASHED_HOOKS"] = "false"
+    settings_context = get_settings_context()
+
+    flow = _deserialize_bundle_object(bundle["function"])
+    context = _deserialize_bundle_object(bundle["context"])
+    flow_run = FlowRun.model_validate(bundle["flow_run"])
+
+    with SettingsContext(
+        profile=settings_context.profile,
+        settings=Settings(),
+    ):
+        with handle_engine_signals(flow_run.id):
+            maybe_coro = run_flow(
+                flow=flow,
+                flow_run=flow_run,
+                context=context,
+            )
+            if asyncio.iscoroutine(maybe_coro):
+                # This is running in a brand new process, so there won't be an existing
+                # event loop.
+                asyncio.run(maybe_coro)
+
+
+def execute_bundle_in_subprocess(
+    bundle: SerializedBundle,
+) -> multiprocessing.context.SpawnProcess:
+    """
+    Executes a bundle in a subprocess.
+
+    Args:
+        bundle: The bundle to execute.
+
+    Returns:
+        A multiprocessing.context.SpawnProcess.
+    """
+
+    ctx = multiprocessing.get_context("spawn")
+
+    process = ctx.Process(
+        target=_extract_and_run_flow,
+        kwargs={
+            "bundle": bundle,
+            "env": get_current_settings().to_environment_variables(exclude_unset=True)
+            | os.environ,
+        },
+    )
+
+    process.start()
+
+    return process

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/client/orchestration/__init__.py

@@ -81,6 +81,7 @@ from prefect.client.orchestration._blocks_types.client import (
 
 import prefect
 import prefect.exceptions
+from prefect.logging.loggers import get_run_logger
 import prefect.settings
 import prefect.states
 from prefect.client.constants import SERVER_API_VERSION
@@ -1182,8 +1183,17 @@ class PrefectClient(
         if api_version.major != client_version.major:
             raise RuntimeError(
                 f"Found incompatible versions: client: {client_version}, server: {api_version}. "
-                f"Major versions must match."
+                "Major versions must match."
             )
+        if api_version < client_version:
+            warning_message = (
+                "Your Prefect server is running an older version of Prefect than your client which may result in unexpected behavior. "
+                f"Please upgrade your Prefect server from version {api_version} to version {client_version} or higher."
+            )
+            try:
+                get_run_logger().warning(warning_message)
+            except prefect.context.MissingContextError:
+                self.logger.warning(warning_message)
 
     async def __aenter__(self) -> Self:
         """
@@ -1523,8 +1533,17 @@ class SyncPrefectClient(
         if api_version.major != client_version.major:
             raise RuntimeError(
                 f"Found incompatible versions: client: {client_version}, server: {api_version}. "
-                f"Major versions must match."
+                "Major versions must match."
             )
+        if api_version < client_version:
+            warning_message = (
+                "Your Prefect server is running an older version of Prefect than your client which may result in unexpected behavior. "
+                f"Please upgrade your Prefect server from version {api_version} to version {client_version} or higher."
+            )
+            try:
+                get_run_logger().warning(warning_message)
+            except prefect.context.MissingContextError:
+                self.logger.warning(warning_message)
 
     def set_task_run_name(self, task_run_id: UUID, name: str) -> httpx.Response:
         task_run_data = TaskRunUpdate(name=name)

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/engine.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import os
 import sys
+from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, Callable
 from uuid import UUID
 
@@ -18,13 +21,71 @@ from prefect.utilities.asyncutils import (
 if TYPE_CHECKING:
     import logging
 
-    from prefect.flow_engine import FlowRun
+    from prefect.client.schemas.objects import FlowRun
     from prefect.flows import Flow
     from prefect.logging.loggers import LoggingAdapter
 
 engine_logger: "logging.Logger" = get_logger("engine")
 
 
+@contextmanager
+def handle_engine_signals(flow_run_id: UUID | None = None):
+    """
+    Handle signals from the orchestrator to abort or pause the flow run or otherwise
+    handle unexpected exceptions.
+
+    This context manager will handle exiting the process depending on the signal received.
+
+    Args:
+        flow_run_id: The ID of the flow run to handle signals for.
+
+    Example:
+        ```python
+        from prefect import flow
+        from prefect.engine import handle_engine_signals
+        from prefect.flow_engine import run_flow
+
+        @flow
+        def my_flow():
+            print("Hello, world!")
+
+        with handle_engine_signals():
+            run_flow(my_flow)
+        ```
+    """
+    try:
+        yield
+    except Abort:
+        if flow_run_id:
+            msg = f"Execution of flow run '{flow_run_id}' aborted by orchestrator."
+        else:
+            msg = "Execution aborted by orchestrator."
+        engine_logger.info(msg)
+        exit(0)
+    except Pause:
+        if flow_run_id:
+            msg = f"Execution of flow run '{flow_run_id}' is paused."
+        else:
+            msg = "Execution is paused."
+        engine_logger.info(msg)
+        exit(0)
+    except Exception:
+        if flow_run_id:
+            msg = f"Execution of flow run '{flow_run_id}' exited with unexpected exception"
+        else:
+            msg = "Execution exited with unexpected exception"
+        engine_logger.error(msg, exc_info=True)
+        exit(1)
+    except BaseException:
+        if flow_run_id:
+            msg = f"Execution of flow run '{flow_run_id}' interrupted by base exception"
+        else:
+            msg = "Execution interrupted by base exception"
+        engine_logger.error(msg, exc_info=True)
+        # Let the exit code be determined by the base exception type
+        raise
+
+
 if __name__ == "__main__":
     try:
         flow_run_id: UUID = UUID(
@@ -36,7 +97,7 @@ if __name__ == "__main__":
         )
         exit(1)
 
-    try:
+    with handle_engine_signals(flow_run_id):
         from prefect.flow_engine import (
             flow_run_logger,
             load_flow,
@@ -62,32 +123,5 @@ if __name__ == "__main__":
         else:
             run_flow(flow, flow_run=flow_run, error_logger=run_logger)
 
-    except Abort:
-        engine_logger.info(
-            f"Engine execution of flow run '{flow_run_id}' aborted by orchestrator."
-        )
-        exit(0)
-    except Pause:
-        engine_logger.info(f"Engine execution of flow run '{flow_run_id}' is paused.")
-        exit(0)
-    except Exception:
-        engine_logger.error(
-            (
-                f"Engine execution of flow run '{flow_run_id}' exited with unexpected "
-                "exception"
-            ),
-            exc_info=True,
-        )
-        exit(1)
-    except BaseException:
-        engine_logger.error(
-            (
-                f"Engine execution of flow run '{flow_run_id}' interrupted by base "
-                "exception"
-            ),
-            exc_info=True,
-        )
-        # Let the exit code be determined by the base exception type
-        raise
 
 __getattr__: Callable[[str], Any] = getattr_migration(__name__)

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/events/schemas/automations.py

@@ -84,7 +84,7 @@ class Trigger(PrefectBaseModel, abc.ABC, extra="ignore"):  # type: ignore[call-a
                 getattr(self, "name", None)
                 or f"Automation for deployment {self._deployment_id}"
             ),
-            description="",
+            description=getattr(self, "description", ""),
             enabled=getattr(self, "enabled", True),
             trigger=trigger,
             actions=self.actions(),

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/flow_engine.py

@@ -47,6 +47,7 @@ from prefect.context import (
     hydrated_context,
     serialize_context,
 )
+from prefect.engine import handle_engine_signals
 from prefect.exceptions import (
     Abort,
     MissingFlowError,
@@ -1592,8 +1593,6 @@ def run_flow_in_subprocess(
         """
         Wrapper function to update environment variables and settings before running the flow.
         """
-        engine_logger = logging.getLogger("prefect.engine")
-
         os.environ.update(env or {})
         settings_context = get_settings_context()
         # Create a new settings context with a new settings object to pick up the updated
@@ -1602,41 +1601,12 @@ def run_flow_in_subprocess(
             profile=settings_context.profile,
             settings=Settings(),
         ):
-            try:
+            with handle_engine_signals(getattr(flow_run, "id", None)):
                 maybe_coro = run_flow(*args, **kwargs)
                 if asyncio.iscoroutine(maybe_coro):
                     # This is running in a brand new process, so there won't be an existing
                     # event loop.
                     asyncio.run(maybe_coro)
-            except Abort:
-                if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' aborted by orchestrator."
-                else:
-                    msg = "Execution aborted by orchestrator."
-                engine_logger.info(msg)
-                exit(0)
-            except Pause:
-                if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' is paused."
-                else:
-                    msg = "Execution is paused."
-                engine_logger.info(msg)
-                exit(0)
-            except Exception:
-                if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' exited with unexpected exception"
-                else:
-                    msg = "Execution exited with unexpected exception"
-                engine_logger.error(msg, exc_info=True)
-                exit(1)
-            except BaseException:
-                if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' interrupted by base exception"
-                else:
-                    msg = "Execution interrupted by base exception"
-                engine_logger.error(msg, exc_info=True)
-                # Let the exit code be determined by the base exception type
-                raise
 
     ctx = multiprocessing.get_context("spawn")
 

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/flows.py

@@ -2350,9 +2350,15 @@ async def load_flow_from_flow_run(
             f"Running {len(deployment.pull_steps)} deployment pull step(s)"
         )
 
-        from prefect.deployments.steps.core import run_steps
+        from prefect.deployments.steps.core import StepExecutionError, run_steps
+
+        try:
+            output = await run_steps(deployment.pull_steps)
+        except StepExecutionError as e:
+            e = e.__cause__ or e
+            run_logger.error(str(e))
+            raise
 
-        output = await run_steps(deployment.pull_steps)
         if output.get("directory"):
             run_logger.debug(f"Changing working directory to {output['directory']!r}")
             os.chdir(output["directory"])

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/logging/configuration.py

@@ -38,7 +38,9 @@ def load_logging_config(path: Path) -> dict[str, Any]:
         warnings.filterwarnings("ignore", category=DeprecationWarning)
         config = yaml.safe_load(
             # Substitute settings into the template in format $SETTING / ${SETTING}
-            template.substitute(current_settings.to_environment_variables())
+            template.substitute(
+                current_settings.to_environment_variables(include_aliases=True)
+            )
         )
 
     # Load overrides from the environment

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/runner/runner.py

@@ -64,9 +64,15 @@ from uuid import UUID, uuid4
 
 import anyio
 import anyio.abc
+import anyio.to_thread
 from cachetools import LRUCache
 from typing_extensions import Self
 
+from prefect._experimental.bundles import (
+    SerializedBundle,
+    execute_bundle_in_subprocess,
+    extract_flow_from_bundle,
+)
 from prefect._internal.concurrency.api import (
     create_call,
     from_async,
@@ -135,7 +141,7 @@ __all__ = ["Runner"]
 
 
 class ProcessMapEntry(TypedDict):
-    flow_run: FlowRun
+    flow_run: "FlowRun"
     pid: int
 
 
@@ -221,6 +227,7 @@ class Runner:
         self._scheduled_task_scopes: set[anyio.abc.CancelScope] = set()
         self._deployment_ids: set[UUID] = set()
         self._flow_run_process_map: dict[UUID, ProcessMapEntry] = dict()
+        self._flow_run_bundle_map: dict[UUID, SerializedBundle] = dict()
 
         self._tmp_dir: Path = (
             Path(tempfile.gettempdir()) / "runner_storage" / str(uuid4())
@@ -508,7 +515,7 @@ class Runner:
         return asyncio.run_coroutine_threadsafe(func(*args, **kwargs), self._loop)
 
     async def cancel_all(self) -> None:
-        runs_to_cancel: list[FlowRun] = []
+        runs_to_cancel: list["FlowRun"] = []
 
         # done to avoid dictionary size changing during iteration
         for info in self._flow_run_process_map.values():
@@ -602,7 +609,120 @@ class Runner:
                             )
                         )
 
-    def _get_flow_run_logger(self, flow_run: "FlowRun | FlowRun") -> PrefectLogAdapter:
+    async def execute_bundle(self, bundle: SerializedBundle) -> None:
+        """
+        Executes a bundle in a subprocess.
+        """
+        from prefect.client.schemas.objects import FlowRun
+
+        self.pause_on_shutdown = False
+        context = self if not self.started else asyncnullcontext()
+
+        flow_run = FlowRun.model_validate(bundle["flow_run"])
+
+        async with context:
+            if not self._acquire_limit_slot(flow_run.id):
+                return
+
+            process = execute_bundle_in_subprocess(bundle)
+
+            if process.pid is None:
+                # This shouldn't happen because `execute_bundle_in_subprocess` starts the process
+                # but we'll handle it gracefully anyway
+                msg = "Failed to start process for flow execution. No PID returned."
+                await self._propose_crashed_state(flow_run, msg)
+                raise RuntimeError(msg)
+
+            self._flow_run_process_map[flow_run.id] = ProcessMapEntry(
+                pid=process.pid, flow_run=flow_run
+            )
+            self._flow_run_bundle_map[flow_run.id] = bundle
+
+            tasks: list[asyncio.Task[None]] = []
+            tasks.append(
+                asyncio.create_task(
+                    critical_service_loop(
+                        workload=self._check_for_cancelled_flow_runs,
+                        interval=self.query_seconds,
+                        jitter_range=0.3,
+                    )
+                )
+            )
+            if self.heartbeat_seconds is not None:
+                tasks.append(
+                    asyncio.create_task(
+                        critical_service_loop(
+                            workload=self._emit_flow_run_heartbeats,
+                            interval=self.heartbeat_seconds,
+                            jitter_range=0.1,
+                        )
+                    )
+                )
+
+            await anyio.to_thread.run_sync(process.join)
+
+            for task in tasks:
+                task.cancel()
+
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+            self._flow_run_process_map.pop(flow_run.id)
+
+            flow_run_logger = self._get_flow_run_logger(flow_run)
+            if process.exitcode is None:
+                raise RuntimeError("Process has no exit code")
+
+            if process.exitcode:
+                help_message = None
+                level = logging.ERROR
+                if process.exitcode == -9:
+                    level = logging.INFO
+                    help_message = (
+                        "This indicates that the process exited due to a SIGKILL signal. "
+                        "Typically, this is either caused by manual cancellation or "
+                        "high memory usage causing the operating system to "
+                        "terminate the process."
+                    )
+                if process.exitcode == -15:
+                    level = logging.INFO
+                    help_message = (
+                        "This indicates that the process exited due to a SIGTERM signal. "
+                        "Typically, this is caused by manual cancellation."
+                    )
+                elif process.exitcode == 247:
+                    help_message = (
+                        "This indicates that the process was terminated due to high "
+                        "memory usage."
+                    )
+                elif (
+                    sys.platform == "win32"
+                    and process.returncode == STATUS_CONTROL_C_EXIT
+                ):
+                    level = logging.INFO
+                    help_message = (
+                        "Process was terminated due to a Ctrl+C or Ctrl+Break signal. "
+                        "Typically, this is caused by manual cancellation."
+                    )
+
+                flow_run_logger.log(
+                    level,
+                    f"Process for flow run {flow_run.name!r} exited with status code:"
+                    f" {process.exitcode}"
+                    + (f"; {help_message}" if help_message else ""),
+                )
+                terminal_state = await self._propose_crashed_state(
+                    flow_run, help_message or "Process exited with non-zero exit code"
+                )
+                if terminal_state:
+                    await self._run_on_crashed_hooks(
+                        flow_run=flow_run, state=terminal_state
+                    )
+            else:
+                flow_run_logger.info(
+                    f"Process for flow run {flow_run.name!r} exited cleanly."
+                )
+
+    def _get_flow_run_logger(self, flow_run: "FlowRun") -> PrefectLogAdapter:
         return flow_run_logger(flow_run=flow_run).getChild(
             "runner",
             extra={
@@ -1308,8 +1428,11 @@ class Runner:
                 exc_info=True,
             )
 
-    async def _propose_crashed_state(self, flow_run: "FlowRun", message: str) -> None:
+    async def _propose_crashed_state(
+        self, flow_run: "FlowRun", message: str
+    ) -> State[Any] | None:
         run_logger = self._get_flow_run_logger(flow_run)
+        state = None
         try:
             state = await propose_state(
                 self._client,
@@ -1326,6 +1449,7 @@ class Runner:
                 run_logger.info(
                     f"Reported flow run '{flow_run.id}' as crashed: {message}"
                 )
+        return state
 
     async def _mark_flow_run_as_cancelled(
         self, flow_run: "FlowRun", state_updates: Optional[dict[str, Any]] = None
@@ -1391,9 +1515,14 @@ class Runner:
         """
         if state.is_cancelling():
             try:
-                flow = await load_flow_from_flow_run(
-                    flow_run, storage_base_path=str(self._tmp_dir)
-                )
+                if flow_run.id in self._flow_run_bundle_map:
+                    flow = extract_flow_from_bundle(
+                        self._flow_run_bundle_map[flow_run.id]
+                    )
+                else:
+                    flow = await load_flow_from_flow_run(
+                        flow_run, storage_base_path=str(self._tmp_dir)
+                    )
                 hooks = flow.on_cancellation_hooks or []
 
                 await _run_hooks(hooks, flow_run, flow, state)
@@ -1412,9 +1541,12 @@ class Runner:
         Run the hooks for a flow.
         """
         if state.is_crashed():
-            flow = await load_flow_from_flow_run(
-                flow_run, storage_base_path=str(self._tmp_dir)
-            )
+            if flow_run.id in self._flow_run_bundle_map:
+                flow = extract_flow_from_bundle(self._flow_run_bundle_map[flow_run.id])
+            else:
+                flow = await load_flow_from_flow_run(
+                    flow_run, storage_base_path=str(self._tmp_dir)
+                )
             hooks = flow.on_crashed_hooks or []
 
             await _run_hooks(hooks, flow_run, flow, state)

{prefect_client-3.2.5 → prefect_client-3.2.7}/src/prefect/server/api/server.py

@@ -55,6 +55,7 @@ from prefect.settings import (
     PREFECT_DEBUG_MODE,
     PREFECT_MEMO_STORE_PATH,
     PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION,
+    PREFECT_SERVER_API_BASE_PATH,
     PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS,
     PREFECT_UI_SERVE_BASE,
     get_current_settings,
@@ -356,7 +357,10 @@ def create_api_app(
             header_token = request.headers.get("Authorization")
 
             # used for probes in k8s and such
-            if request.url.path in ["/api/health", "/api/ready"]:
+            if (
+                request.url.path.endswith(("health", "ready"))
+                and request.method.upper() == "GET"
+            ):
                 return await call_next(request)
             try:
                 if header_token is None:
@@ -691,7 +695,10 @@ def create_app(
         name="static",
     )
     app.api_app = api_app
-    app.mount("/api", app=api_app, name="api")
+    if PREFECT_SERVER_API_BASE_PATH:
+        app.mount(PREFECT_SERVER_API_BASE_PATH.value(), app=api_app, name="api")
+    else:
+        app.mount("/api", app=api_app, name="api")
     app.mount("/", app=ui_app, name="ui")
 
     def openapi():