prefect 3.6.13.dev2__py3-none-any.whl → 3.6.14.dev1__py3-none-any.whl

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.6.13.dev2"
-__build_date__ = "2026-01-22 08:12:37.989944+00:00"
-__git_commit__ = "3216a18c97baecb25fe70d3d46a93eb56ebd2adc"
+__version__ = "3.6.14.dev1"
+__build_date__ = "2026-01-23 08:12:06.479550+00:00"
+__git_commit__ = "61276aac1e484a94f570b66a73d5dd6b3eeee5ea"
 __dirty__ = False

prefect/_internal/compatibility/blocks.py

@@ -4,6 +4,24 @@ from typing import Any, Union
 from prefect.filesystems import NullFileSystem, WritableFileSystem
 
 
+def call_explicitly_sync_block_method(
+    block: Union[WritableFileSystem, NullFileSystem],
+    method: str,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> Any:
+    """
+    Call a block method synchronously.
+
+    TODO: remove this once we have explicit sync/async methods on all storage blocks
+
+    see https://github.com/PrefectHQ/prefect/issues/15008
+    """
+    # Pass _sync=True to ensure we get synchronous execution even when called
+    # from an async context (e.g., within a sync flow running in an async test)
+    return getattr(block, method)(*args, _sync=True, **kwargs)
+
+
 async def call_explicitly_async_block_method(
     block: Union[WritableFileSystem, NullFileSystem],
     method: str,

prefect/client/schemas/filters.py

@@ -281,6 +281,27 @@ class FlowRunFilterIdempotencyKey(PrefectBaseModel):
     )
 
 
+class FlowRunFilterCreatedBy(PrefectBaseModel, OperatorMixin):
+    """Filter by `FlowRun.created_by`."""
+
+    id_: Optional[List[UUID]] = Field(
+        default=None,
+        description="A list of creator IDs to include",
+    )
+    type_: Optional[List[str]] = Field(
+        default=None,
+        description=(
+            "A list of creator types to include. For example, 'DEPLOYMENT' for "
+            "scheduled runs or 'AUTOMATION' for runs triggered by automations."
+        ),
+        examples=[["DEPLOYMENT", "AUTOMATION"]],
+    )
+    is_null_: Optional[bool] = Field(
+        default=None,
+        description="If true, only include flow runs without a creator",
+    )
+
+
 class FlowRunFilter(PrefectBaseModel, OperatorMixin):
     """Filter flow runs. Only flow runs matching all criteria will be returned"""
 
@@ -324,6 +345,9 @@ class FlowRunFilter(PrefectBaseModel, OperatorMixin):
     idempotency_key: Optional[FlowRunFilterIdempotencyKey] = Field(
         default=None, description="Filter criteria for `FlowRun.idempotency_key`"
     )
+    created_by: Optional[FlowRunFilterCreatedBy] = Field(
+        default=None, description="Filter criteria for `FlowRun.created_by`"
+    )
 
 
 class TaskRunFilterFlowRunId(PrefectBaseModel):

prefect/flow_engine.py

@@ -5,6 +5,7 @@ import logging
 import multiprocessing
 import multiprocessing.context
 import os
+import threading
 import time
 from contextlib import (
     AsyncExitStack,
@@ -36,7 +37,7 @@ from anyio import CancelScope
 from opentelemetry import propagate, trace
 from typing_extensions import ParamSpec
 
-from prefect import Task
+from prefect import Task, __version__
 from prefect.client.orchestration import PrefectClient, SyncPrefectClient, get_client
 from prefect.client.schemas import FlowRun, TaskRun
 from prefect.client.schemas.filters import FlowRunFilter
@@ -60,6 +61,8 @@ from prefect.context import (
     serialize_context,
 )
 from prefect.engine import handle_engine_signals
+from prefect.events.related import RelatedResource, tags_as_related_resources
+from prefect.events.utilities import emit_event
 from prefect.exceptions import (
     Abort,
     MissingFlowError,
@@ -161,6 +164,129 @@ def load_flow_and_flow_run(flow_run_id: UUID) -> tuple[FlowRun, Flow[..., Any]]:
     return flow_run, flow
 
 
+@contextmanager
+def send_heartbeats_sync(
+    engine: "FlowRunEngine[Any, Any]",
+) -> Generator[None, None, None]:
+    """Context manager that maintains heartbeats for a sync flow run.
+
+    Heartbeats are emitted at regular intervals while the flow is running.
+    The loop checks the flow run state before each heartbeat and stops
+    if the run reaches a terminal state.
+
+    Args:
+        engine: The FlowRunEngine instance to emit heartbeats for.
+
+    Yields:
+        None
+    """
+    heartbeat_seconds = engine.heartbeat_seconds
+    if heartbeat_seconds is None:
+        yield
+        return
+
+    stop_event = threading.Event()
+
+    def heartbeat_loop() -> None:
+        while not stop_event.is_set():
+            # Check state before emitting - don't emit if final
+            if (
+                engine.flow_run
+                and engine.flow_run.state
+                and engine.flow_run.state.is_final()
+            ):
+                engine.logger.debug("Flow run in terminal state, stopping heartbeat")
+                return
+
+            try:
+                engine._emit_flow_run_heartbeat()
+            except Exception:
+                engine.logger.debug("Failed to emit heartbeat", exc_info=True)
+
+            # Sleep in increments to allow quick shutdown
+            for _ in range(heartbeat_seconds):
+                if stop_event.is_set():
+                    return
+                time.sleep(1)
+
+    thread = threading.Thread(target=heartbeat_loop, daemon=True)
+    thread.start()
+    engine.logger.debug("Started flow run heartbeat context")
+
+    try:
+        yield
+    finally:
+        stop_event.set()
+        thread.join(timeout=2)
+        engine.logger.debug("Stopped flow run heartbeat context")
+
+
+@asynccontextmanager
+async def send_heartbeats_async(
+    engine: "AsyncFlowRunEngine[Any, Any]",
+) -> AsyncGenerator[None, None]:
+    """Async context manager that maintains heartbeats for an async flow run.
+
+    Heartbeats are emitted at regular intervals while the flow is running.
+    The loop checks the flow run state before each heartbeat and stops
+    if the run reaches a terminal state.
+
+    Args:
+        engine: The AsyncFlowRunEngine instance to emit heartbeats for.
+
+    Yields:
+        None
+    """
+    heartbeat_seconds = engine.heartbeat_seconds
+    if heartbeat_seconds is None:
+        yield
+        return
+
+    stop_flag = False
+
+    async def heartbeat_loop() -> None:
+        nonlocal stop_flag
+        try:
+            while not stop_flag:
+                # Check state before emitting - don't emit if final
+                if (
+                    engine.flow_run
+                    and engine.flow_run.state
+                    and engine.flow_run.state.is_final()
+                ):
+                    engine.logger.debug(
+                        "Flow run in terminal state, stopping heartbeat"
+                    )
+                    return
+
+                try:
+                    engine._emit_flow_run_heartbeat()
+                except Exception:
+                    engine.logger.debug("Failed to emit heartbeat", exc_info=True)
+
+                # Sleep in increments to allow quick shutdown (parity with sync version)
+                for _ in range(heartbeat_seconds):
+                    if stop_flag:
+                        return
+                    await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            engine.logger.debug("Heartbeat loop cancelled")
+
+    task = asyncio.create_task(heartbeat_loop())
+    engine.logger.debug("Started flow run heartbeat context")
+
+    try:
+        yield
+    finally:
+        stop_flag = True
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+        engine.logger.debug("Stopped flow run heartbeat context")
+
+
 @dataclass
 class BaseFlowRunEngine(Generic[P, R]):
     flow: Union[Flow[P, R], Flow[P, Coroutine[Any, Any, R]]]
@@ -200,10 +326,59 @@ class BaseFlowRunEngine(Generic[P, R]):
             return False  # TODO: handle this differently?
         return getattr(self, "flow_run").state.is_pending()
 
+    @property
+    def heartbeat_seconds(self) -> Optional[int]:
+        """Get the heartbeat interval from settings."""
+        return get_current_settings().flows.heartbeat_frequency
+
     def cancel_all_tasks(self) -> None:
         if hasattr(self.flow.task_runner, "cancel_all"):
             self.flow.task_runner.cancel_all()  # type: ignore
 
+    def _emit_flow_run_heartbeat(self) -> None:
+        """Emit a heartbeat event for the current flow run."""
+        if not self.flow_run:
+            return
+
+        related: list[RelatedResource] = []
+        tags: list[str] = list(self.flow_run.tags or [])
+
+        # Add flow as related resource using flow_id for consistency with other events
+        if self.flow_run.flow_id:
+            related.append(
+                RelatedResource.model_validate(
+                    {
+                        "prefect.resource.id": f"prefect.flow.{self.flow_run.flow_id}",
+                        "prefect.resource.role": "flow",
+                        "prefect.resource.name": self.flow.name if self.flow else "",
+                    }
+                )
+            )
+
+        # Add deployment as related resource if available
+        # Note: deployment name is not available on flow_run without an API call
+        if self.flow_run.deployment_id:
+            related.append(
+                RelatedResource.model_validate(
+                    {
+                        "prefect.resource.id": f"prefect.deployment.{self.flow_run.deployment_id}",
+                        "prefect.resource.role": "deployment",
+                    }
+                )
+            )
+
+        related += tags_as_related_resources(set(tags))
+
+        emit_event(
+            event="prefect.flow-run.heartbeat",
+            resource={
+                "prefect.resource.id": f"prefect.flow-run.{self.flow_run.id}",
+                "prefect.resource.name": self.flow_run.name or "",
+                "prefect.version": __version__,
+            },
+            related=related,
+        )
+
     def _update_otel_labels(
         self, span: trace.Span, client: Union[SyncPrefectClient, PrefectClient]
     ):
@@ -343,6 +518,7 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
 
         self._telemetry.update_state(state)
         self.call_hooks(state)
+
         return state
 
     def result(self, raise_on_failure: bool = True) -> "Union[R, State, None]":
@@ -791,10 +967,11 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                     seconds=self.flow.timeout_seconds,
                     timeout_exc_type=FlowRunTimeoutError,
                 ):
-                    self.logger.debug(
-                        f"Executing flow {self.flow.name!r} for flow run {self.flow_run.name!r}..."
-                    )
-                    yield self
+                    with send_heartbeats_sync(self):
+                        self.logger.debug(
+                            f"Executing flow {self.flow.name!r} for flow run {self.flow_run.name!r}..."
+                        )
+                        yield self
             except TimeoutError as exc:
                 self.handle_timeout(exc)
             except Exception as exc:
@@ -930,6 +1107,7 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
 
         self._telemetry.update_state(state)
         await self.call_hooks(state)
+
         return state
 
     async def result(self, raise_on_failure: bool = True) -> "Union[R, State, None]":
@@ -1381,10 +1559,11 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                     seconds=self.flow.timeout_seconds,
                     timeout_exc_type=FlowRunTimeoutError,
                 ):
-                    self.logger.debug(
-                        f"Executing flow {self.flow.name!r} for flow run {self.flow_run.name!r}..."
-                    )
-                    yield self
+                    async with send_heartbeats_async(self):
+                        self.logger.debug(
+                            f"Executing flow {self.flow.name!r} for flow run {self.flow_run.name!r}..."
+                        )
+                        yield self
             except TimeoutError as exc:
                 await self.handle_timeout(exc)
             except Exception as exc:
@@ -1614,6 +1793,7 @@ def run_flow_in_subprocess(
     parameters: dict[str, Any] | None = None,
     wait_for: Iterable[PrefectFuture[Any]] | None = None,
     context: dict[str, Any] | None = None,
+    env: dict[str, str] | None = None,
 ) -> multiprocessing.context.SpawnProcess:
     """
     Run a flow in a subprocess.
@@ -1630,6 +1810,7 @@ def run_flow_in_subprocess(
             the current context will be used. A serialized context should be provided if
             this function is called in a separate memory space from the parent run (e.g.
             in a subprocess or on another machine).
+        env: Additional environment variables to set in the subprocess.
 
     Returns:
         A multiprocessing.context.SpawnProcess representing the process that is running the flow.
@@ -1672,7 +1853,8 @@ def run_flow_in_subprocess(
             | {
                 # TODO: make this a thing we can pass into the engine
                 "PREFECT__ENABLE_CANCELLATION_AND_CRASHED_HOOKS": "false",
-            },
+            }
+            | (env or {}),
             flow=flow,
             flow_run=flow_run,
             parameters=parameters,

prefect/flows.py

@@ -1717,8 +1717,7 @@ class Flow(Generic[P, R]):
             return_type=return_type,
         )
 
-    @sync_compatible
-    async def visualize(self, *args: "P.args", **kwargs: "P.kwargs"):
+    async def avisualize(self, *args: "P.args", **kwargs: "P.kwargs") -> None:
         """
         Generates a graphviz object representing the current flow. In IPython notebooks,
         it's rendered inline, otherwise in a new window as a PNG.
@@ -1776,6 +1775,66 @@ class Flow(Generic[P, R]):
             new_exception.__traceback__ = e.__traceback__
             raise new_exception
 
+    @async_dispatch(avisualize)
+    def visualize(self, *args: "P.args", **kwargs: "P.kwargs") -> None:
+        """
+        Generates a graphviz object representing the current flow. In IPython notebooks,
+        it's rendered inline, otherwise in a new window as a PNG.
+
+        Raises:
+            - ImportError: If `graphviz` isn't installed.
+            - GraphvizExecutableNotFoundError: If the `dot` executable isn't found.
+            - FlowVisualizationError: If the flow can't be visualized for any other reason.
+        """
+        from prefect.utilities.visualization import (
+            FlowVisualizationError,
+            GraphvizExecutableNotFoundError,
+            GraphvizImportError,
+            TaskVizTracker,
+            VisualizationUnsupportedError,
+            build_task_dependencies,
+            visualize_task_dependencies,
+        )
+
+        if not PREFECT_TESTING_UNIT_TEST_MODE:
+            warnings.warn(
+                "`flow.visualize()` will execute code inside of your flow that is not"
+                " decorated with `@task` or `@flow`."
+            )
+
+        try:
+            with TaskVizTracker() as tracker:
+                if self.isasync:
+                    # Run async flow via event loop
+                    run_coro_as_sync(self.fn(*args, **kwargs))
+                else:
+                    self.fn(*args, **kwargs)
+
+                graph = build_task_dependencies(tracker)
+
+                visualize_task_dependencies(graph, self.name)
+
+        except GraphvizImportError:
+            raise
+        except GraphvizExecutableNotFoundError:
+            raise
+        except VisualizationUnsupportedError:
+            raise
+        except FlowVisualizationError:
+            raise
+        except Exception as e:
+            msg = (
+                "It's possible you are trying to visualize a flow that contains "
+                "code that directly interacts with the result of a task"
+                " inside of the flow. \nTry passing a `viz_return_value` "
+                "to the task decorator, e.g. `@task(viz_return_value=[1, 2, 3]).`"
+            )
+
+            new_exception = type(e)(str(e) + "\n" + msg)
+            # Copy traceback information from the original exception
+            new_exception.__traceback__ = e.__traceback__
+            raise new_exception
+
 
 class FlowDecorator:
     @overload