prefect 3.6.12__py3-none-any.whl → 3.6.13__py3-none-any.whl

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.6.12"
-__build_date__ = "2026-01-20 18:20:13.303126+00:00"
-__git_commit__ = "eb710303965c126b83f41f180d257b258b815543"
+__version__ = "3.6.13"
+__build_date__ = "2026-01-23 03:49:46.368256+00:00"
+__git_commit__ = "9eb03a74b91426b564a1aa313670eb08a8b9ece8"
 __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/_internal/urls.py

@@ -0,0 +1,29 @@
+from urllib.parse import urlparse, urlunparse
+
+
+def strip_auth_from_url(url: str) -> str:
+    """
+    Remove authentication credentials (username/password) from a URL.
+
+    Useful for sanitizing URLs before including them in error messages
+    or logs to avoid leaking secrets.
+    """
+    parsed = urlparse(url)
+
+    if not parsed.hostname:
+        return url
+
+    netloc = parsed.hostname
+    if parsed.port:
+        netloc = f"{netloc}:{parsed.port}"
+
+    return urlunparse(
+        (
+            parsed.scheme,
+            netloc,
+            parsed.path,
+            parsed.params,
+            parsed.query,
+            parsed.fragment,
+        )
+    )

prefect/_states.py

@@ -58,10 +58,13 @@ def exception_to_crashed_state_sync(
     # calling it from sync-only code raises an error. Since anyio cancellation
     # exceptions can only occur in async contexts anyway, we can safely skip
     # this check when no async backend is running.
+    # anyio 4.12+ raises anyio.NoEventLoopError, older versions raise
+    # sniffio.AsyncLibraryNotFoundError. Catch both for compatibility.
+    # TODO: remove sniffio handling once anyio lower bound is >=4.12.1
     try:
         cancelled_exc_class = anyio.get_cancelled_exc_class()
         is_anyio_cancelled = isinstance(exc, cancelled_exc_class)
-    except sniffio.AsyncLibraryNotFoundError:
+    except (sniffio.AsyncLibraryNotFoundError, anyio.NoEventLoopError):
         is_anyio_cancelled = False
 
     if is_anyio_cancelled:

prefect/client/orchestration/_concurrency_limits/client.py

@@ -446,22 +446,22 @@ class ConcurrencyLimitClient(BaseClient):
             existing_limit = None
 
         if not existing_limit:
+            create_kwargs: dict[str, Any] = {"name": name, "limit": limit}
+            if slot_decay_per_second is not None:
+                create_kwargs["slot_decay_per_second"] = slot_decay_per_second
             self.create_global_concurrency_limit(
-                GlobalConcurrencyLimitCreate(
-                    name=name,
-                    limit=limit,
-                    slot_decay_per_second=slot_decay_per_second,
-                )
+                GlobalConcurrencyLimitCreate(**create_kwargs)
             )
         elif existing_limit.limit != limit or (
             slot_decay_per_second is not None
             and existing_limit.slot_decay_per_second != slot_decay_per_second
         ):
+            update_kwargs: dict[str, Any] = {"limit": limit}
+            if slot_decay_per_second is not None:
+                update_kwargs["slot_decay_per_second"] = slot_decay_per_second
             self.update_global_concurrency_limit(
                 name,
-                GlobalConcurrencyLimitUpdate(
-                    limit=limit, slot_decay_per_second=slot_decay_per_second
-                ),
+                GlobalConcurrencyLimitUpdate(**update_kwargs),
             )
 
     def read_global_concurrency_limits(
@@ -908,22 +908,22 @@ class ConcurrencyLimitAsyncClient(BaseAsyncClient):
             existing_limit = None
 
         if not existing_limit:
+            create_kwargs: dict[str, Any] = {"name": name, "limit": limit}
+            if slot_decay_per_second is not None:
+                create_kwargs["slot_decay_per_second"] = slot_decay_per_second
             await self.create_global_concurrency_limit(
-                GlobalConcurrencyLimitCreate(
-                    name=name,
-                    limit=limit,
-                    slot_decay_per_second=slot_decay_per_second,
-                )
+                GlobalConcurrencyLimitCreate(**create_kwargs)
             )
         elif existing_limit.limit != limit or (
             slot_decay_per_second is not None
             and existing_limit.slot_decay_per_second != slot_decay_per_second
         ):
+            update_kwargs: dict[str, Any] = {"limit": limit}
+            if slot_decay_per_second is not None:
+                update_kwargs["slot_decay_per_second"] = slot_decay_per_second
             await self.update_global_concurrency_limit(
                 name,
-                GlobalConcurrencyLimitUpdate(
-                    limit=limit, slot_decay_per_second=slot_decay_per_second
-                ),
+                GlobalConcurrencyLimitUpdate(**update_kwargs),
             )
 
     async def read_global_concurrency_limits(

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/client/subscriptions.py

@@ -90,7 +90,7 @@ class Subscription(Generic[S]):
             )
 
             auth: dict[str, Any] = orjson.loads(await websocket.recv())
-            assert auth["type"] == "auth_success", auth.get("message")
+            assert auth["type"] == "auth_success", auth.get("reason", "")
 
             message: dict[str, Any] = {"type": "subscribe", "keys": self.keys}
             if self.client_id:

prefect/events/clients.py

@@ -73,6 +73,17 @@ if TYPE_CHECKING:
 
 logger: "logging.Logger" = get_logger(__name__)
 
+# Exceptions that indicate transient network issues and should trigger retries.
+# These are used consistently across all event client retry loops.
+# - ConnectionClosed: WebSocket connection was closed (e.g., server restart, load balancer timeout)
+# - TimeoutError: Connection or operation timed out
+# - OSError: Network-level errors (connection refused, DNS failures, network unreachable, etc.)
+RETRYABLE_EXCEPTIONS: Tuple[Type[Exception], ...] = (
+    ConnectionClosed,
+    TimeoutError,
+    OSError,
+)
+
 
 def http_to_ws(url: str) -> str:
     return url.replace("https://", "wss://").replace("http://", "ws://").rstrip("/")
@@ -278,14 +289,30 @@ class PrefectEventsClient(EventsClient):
         self._checkpoint_every = checkpoint_every
 
     async def __aenter__(self) -> Self:
-        # Don't handle any errors in the initial connection, because these are most
-        # likely a permission or configuration issue that should propagate
         await super().__aenter__()
-        try:
-            await self._reconnect()
-        except Exception as e:
-            self._log_connection_error(e)
-            raise
+        # Ensure at least one connection attempt even if reconnection_attempts is negative
+        max_attempts = max(1, self._reconnection_attempts + 1)
+        for i in range(max_attempts):
+            try:
+                await self._reconnect()
+                break
+            except RETRYABLE_EXCEPTIONS as e:
+                logger.debug(
+                    "Initial connection attempt %s/%s failed: %s",
+                    i + 1,
+                    max_attempts,
+                    str(e),
+                )
+                if i == max_attempts - 1:
+                    self._log_connection_error(e)
+                    raise
+                if i > 2:
+                    await asyncio.sleep(1)
+            except Exception as e:
+                # Non-retryable exceptions (config/permission issues) should
+                # propagate immediately with a warning
+                self._log_connection_error(e)
+                raise
         return self
 
     async def __aexit__(
@@ -295,7 +322,13 @@ class PrefectEventsClient(EventsClient):
         exc_tb: Optional[TracebackType],
     ) -> None:
         self._websocket = None
-        await self._connect.__aexit__(exc_type, exc_val, exc_tb)
+        # Only call __aexit__ on the connection if it was successfully established.
+        # The websockets library sets the "connection" attribute on the connect
+        # object only after __aenter__() completes successfully. Without this guard,
+        # we would get an AttributeError when cleaning up a connection that failed
+        # during establishment.
+        if hasattr(self._connect, "connection"):
+            await self._connect.__aexit__(exc_type, exc_val, exc_tb)
         return await super().__aexit__(exc_type, exc_val, exc_tb)
 
     def _log_debug(self, message: str, *args: Any, **kwargs: Any) -> None:
@@ -402,8 +435,8 @@ class PrefectEventsClient(EventsClient):
                 await self._checkpoint()
 
                 return
-            except ConnectionClosed as e:
-                self._log_debug("Got ConnectionClosed error.")
+            except RETRYABLE_EXCEPTIONS as e:
+                self._log_debug("Got retryable error: %s", type(e).__name__)
                 if i == self._reconnection_attempts:
                     # this was our final chance, log warning and raise
                     self._log_connection_error(e)
@@ -643,7 +676,13 @@ class PrefectEventSubscriber:
         exc_tb: Optional[TracebackType],
     ) -> None:
         self._websocket = None
-        await self._connect.__aexit__(exc_type, exc_val, exc_tb)
+        # Only call __aexit__ on the connection if it was successfully established.
+        # The websockets library sets the "connection" attribute on the connect
+        # object only after __aenter__() completes successfully. Without this guard,
+        # we would get an AttributeError when cleaning up a connection that failed
+        # during establishment.
+        if hasattr(self._connect, "connection"):
+            await self._connect.__aexit__(exc_type, exc_val, exc_tb)
 
     def __aiter__(self) -> Self:
         return self
@@ -681,9 +720,9 @@ class PrefectEventSubscriber:
             except ConnectionClosedOK:
                 logger.debug('Connection closed with "OK" status')
                 raise StopAsyncIteration
-            except ConnectionClosed:
+            except RETRYABLE_EXCEPTIONS:
                 logger.debug(
-                    "Connection closed with %s/%s attempts",
+                    "Retryable error with %s/%s attempts",
                     i + 1,
                     self._reconnection_attempts,
                 )

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