prefect 3.6.7.dev3__py3-none-any.whl → 3.6.8.dev3__py3-none-any.whl

prefect/__init__.py

@@ -12,21 +12,22 @@ if TYPE_CHECKING:
     from importlib.machinery import ModuleSpec
     from .main import (
         allow_failure,
+        aresume_flow_run,
+        aserve,
         flow,
         Flow,
         get_client,
         get_run_logger,
+        pause_flow_run,
+        resume_flow_run,
+        serve,
         State,
+        suspend_flow_run,
         tags,
         task,
         Task,
         Transaction,
         unmapped,
-        serve,
-        aserve,
-        pause_flow_run,
-        resume_flow_run,
-        suspend_flow_run,
     )
     from prefect.deployments.runner import deploy
 
@@ -118,6 +119,7 @@ _initialize_plugins()
 
 _public_api: dict[str, tuple[Optional[str], str]] = {
     "allow_failure": (__spec__.parent, ".main"),
+    "aresume_flow_run": (__spec__.parent, ".main"),
     "aserve": (__spec__.parent, ".main"),
     "deploy": (__spec__.parent, ".deployments.runner"),
     "flow": (__spec__.parent, ".main"),
@@ -140,6 +142,7 @@ _public_api: dict[str, tuple[Optional[str], str]] = {
 __all__ = [
     "__version__",
     "allow_failure",
+    "aresume_flow_run",
     "aserve",
     "deploy",
     "flow",

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.6.7.dev3"
-__build_date__ = "2025-12-14 08:09:01.617063+00:00"
-__git_commit__ = "96ab33fd33df46b6a16e3015b5bd1131e61f3ee1"
+__version__ = "3.6.8.dev3"
+__build_date__ = "2025-12-24 08:10:40.420068+00:00"
+__git_commit__ = "4baedb2efecfb4d82ce18b339ce16383da4a5754"
 __dirty__ = False

prefect/_experimental/bundles/__init__.py

@@ -38,14 +38,18 @@ logger: logging.Logger = get_logger(__name__)
 
 
 def _get_uv_path() -> str:
+    """
+    Get the path to the uv binary.
+
+    First tries to use the uv Python package to find the binary.
+    Falls back to "uv" string (assumes uv is in PATH).
+    """
     try:
         import uv
 
-        uv_path = uv.find_uv_bin()
+        return uv.find_uv_bin()
     except (ImportError, ModuleNotFoundError, FileNotFoundError):
-        uv_path = "uv"
-
-    return uv_path
+        return "uv"
 
 
 class SerializedBundle(TypedDict):

prefect/blocks/notifications.py

@@ -679,7 +679,7 @@ class MattermostWebhook(AbstractAppriseNotificationBlock):
                 token=self.token.get_secret_value(),
                 fullpath=self.path,
                 host=self.hostname,
-                botname=self.botname,
+                user=self.botname,
                 channels=self.channels,
                 include_image=self.include_image,
                 port=self.port,

prefect/cache_policies.py

@@ -1,6 +1,7 @@
 import inspect
 from copy import deepcopy
 from dataclasses import dataclass, field
+from logging import Logger
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -16,6 +17,7 @@ from typing_extensions import Self
 
 from prefect.context import TaskRunContext
 from prefect.exceptions import HashError
+from prefect.logging import get_logger
 from prefect.utilities.hashing import hash_objects
 
 if TYPE_CHECKING:
@@ -25,6 +27,8 @@ if TYPE_CHECKING:
 
 STABLE_TRANSFORMS: dict[type, Callable[[Any], Any]] = {}
 
+logger: Logger = get_logger(__name__)
+
 
 def _register_stable_transforms() -> None:
     """
@@ -291,6 +295,13 @@ class TaskSource(CachePolicy):
     ) -> Optional[str]:
         if not task_ctx:
             return None
+
+        # Use stored source code if available (works after cloudpickle serialization)
+        lines = getattr(task_ctx.task, "source_code", None)
+        if lines is not None:
+            return hash_objects(lines, raise_on_failure=True)
+
+        # Fall back to inspect.getsource for local execution
         try:
             lines = inspect.getsource(task_ctx.task)
         except TypeError:
@@ -300,6 +311,7 @@ class TaskSource(CachePolicy):
                 lines = task_ctx.task.fn.__code__.co_code
             else:
                 raise
+
         return hash_objects(lines, raise_on_failure=True)
 
 

prefect/cli/server.py

@@ -709,13 +709,29 @@ def run_manager_process():
 
     logger.debug("Manager process started. Starting services...")
     try:
-        asyncio.run(Service.run_services())
+        asyncio.run(_run_all_services())
     except KeyboardInterrupt:
         pass
     finally:
         logger.debug("Manager process has exited.")
 
 
+async def _run_all_services() -> None:
+    """Run Service-based services and docket-based perpetual services."""
+    from docket import Docket
+
+    from prefect.server.api.background_workers import background_worker
+    from prefect.server.services.base import Service
+    from prefect.settings.context import get_current_settings
+
+    docket_url = get_current_settings().server.docket.url
+
+    async with Docket(name="prefect", url=docket_url) as docket:
+        async with background_worker(docket, ephemeral=False, webserver_only=False):
+            # Run Service-based services (will block until shutdown)
+            await Service.run_services()
+
+
 # public, user-facing `prefect server services` commands
 @services_app.command(aliases=["ls"])
 def list_services():
@@ -772,7 +788,7 @@ def start_services(
     if not background:
         app.console.print("\n[blue]Starting services... Press CTRL+C to stop[/]\n")
         try:
-            asyncio.run(Service.run_services())
+            asyncio.run(_run_all_services())
         except KeyboardInterrupt:
             pass
         app.console.print("\n[green]All services stopped.[/]")

prefect/client/orchestration/_deployments/client.py

@@ -157,6 +157,12 @@ class DeploymentClient(BaseClient):
             payload["version_info"] = deployment_create.version_info.model_dump(
                 mode="json"
             )
+        if deployment_create.concurrency_options:
+            payload["concurrency_options"] = (
+                deployment_create.concurrency_options.model_dump(
+                    mode="json", exclude_unset=True
+                )
+            )
 
         try:
             response = self.request("POST", "/deployments/", json=payload)
@@ -823,6 +829,12 @@ class DeploymentAsyncClient(BaseAsyncClient):
             payload["version_info"] = deployment_create.version_info.model_dump(
                 mode="json"
             )
+        if deployment_create.concurrency_options:
+            payload["concurrency_options"] = (
+                deployment_create.concurrency_options.model_dump(
+                    mode="json", exclude_unset=True
+                )
+            )
 
         try:
             response = await self.request("POST", "/deployments/", json=payload)

prefect/events/clients.py

@@ -281,7 +281,11 @@ class PrefectEventsClient(EventsClient):
         # 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__()
-        await self._reconnect()
+        try:
+            await self._reconnect()
+        except Exception as e:
+            self._log_connection_error(e)
+            raise
         return self
 
     async def __aexit__(
@@ -298,6 +302,18 @@ class PrefectEventsClient(EventsClient):
         message = f"EventsClient(id={id(self)}): " + message
         logger.debug(message, *args, **kwargs)
 
+    def _log_connection_error(self, error: Exception) -> None:
+        logger.warning(
+            "Unable to connect to %r. "
+            "Please check your network settings to ensure websocket connections "
+            "to the API are allowed. Otherwise event data (including task run data) may be lost. "
+            "Reason: %s. "
+            "Set PREFECT_DEBUG_MODE=1 to see the full error.",
+            self._events_socket_url,
+            str(error),
+            exc_info=PREFECT_DEBUG_MODE.value(),
+        )
+
     async def _reconnect(self) -> None:
         logger.debug("Reconnecting websocket connection.")
 
@@ -315,15 +331,10 @@ class PrefectEventsClient(EventsClient):
             await pong
             logger.debug("Pong received. Websocket connected.")
         except Exception as e:
-            # The client is frequently run in a background thread
-            # so we log an additional warning to ensure
-            # surfacing the error to the user.
-            logger.warning(
-                "Unable to connect to %r. "
-                "Please check your network settings to ensure websocket connections "
-                "to the API are allowed. Otherwise event data (including task run data) may be lost. "
-                "Reason: %s. "
-                "Set PREFECT_DEBUG_MODE=1 to see the full error.",
+            # Log at debug level during reconnection attempts - the warning will
+            # only be logged if all reconnection attempts fail (in _emit)
+            logger.debug(
+                "Unable to connect to %r, will retry. Reason: %s",
                 self._events_socket_url,
                 str(e),
                 exc_info=PREFECT_DEBUG_MODE.value(),
@@ -391,10 +402,11 @@ class PrefectEventsClient(EventsClient):
                 await self._checkpoint()
 
                 return
-            except ConnectionClosed:
+            except ConnectionClosed as e:
                 self._log_debug("Got ConnectionClosed error.")
                 if i == self._reconnection_attempts:
-                    # this was our final chance, raise the most recent error
+                    # this was our final chance, log warning and raise
+                    self._log_connection_error(e)
                     raise
 
                 if i > 2:

prefect/flow_runs.py

@@ -11,6 +11,7 @@ from uuid import UUID, uuid4
 
 import anyio
 
+from prefect._internal.compatibility.async_dispatch import async_dispatch
 from prefect.client.orchestration import PrefectClient, get_client
 from prefect.client.schemas import FlowRun
 from prefect.client.schemas.objects import (
@@ -42,9 +43,7 @@ from prefect.states import (
     Paused,
     Suspended,
 )
-from prefect.utilities.asyncutils import (
-    sync_compatible,
-)
+from prefect.utilities.asyncutils import sync_compatible
 from prefect.utilities.engine import (
     propose_state,
 )
@@ -459,28 +458,50 @@ async def suspend_flow_run(
         raise Pause(state=state)
 
 
-@sync_compatible
-async def resume_flow_run(
+async def aresume_flow_run(
     flow_run_id: UUID, run_input: dict[str, Any] | None = None
 ) -> None:
     """
-    Resumes a paused flow.
+    Resumes a paused flow asynchronously.
 
     Args:
         flow_run_id: the flow_run_id to resume
         run_input: a dictionary of inputs to provide to the flow run.
     """
-    client = get_client()
-    async with client:
+    async with get_client() as client:
         flow_run = await client.read_flow_run(flow_run_id)
 
-        if not flow_run.state.is_paused():
+        if not flow_run.state or not flow_run.state.is_paused():
             raise NotPausedError("Cannot resume a run that isn't paused!")
 
         response = await client.resume_flow_run(flow_run_id, run_input=run_input)
 
     if response.status == SetStateStatus.REJECT:
-        if response.state.type == StateType.FAILED:
+        if response.state and response.state.type == StateType.FAILED:
+            raise FlowPauseTimeout("Flow run can no longer be resumed.")
+        else:
+            raise RuntimeError(f"Cannot resume this run: {response.details.reason}")
+
+
+@async_dispatch(aresume_flow_run)
+def resume_flow_run(flow_run_id: UUID, run_input: dict[str, Any] | None = None) -> None:
+    """
+    Resumes a paused flow.
+
+    Args:
+        flow_run_id: the flow_run_id to resume
+        run_input: a dictionary of inputs to provide to the flow run.
+    """
+    with get_client(sync_client=True) as client:
+        flow_run = client.read_flow_run(flow_run_id)
+
+        if not flow_run.state or not flow_run.state.is_paused():
+            raise NotPausedError("Cannot resume a run that isn't paused!")
+
+        response = client.resume_flow_run(flow_run_id, run_input=run_input)
+
+    if response.status == SetStateStatus.REJECT:
+        if response.state and response.state.type == StateType.FAILED:
             raise FlowPauseTimeout("Flow run can no longer be resumed.")
         else:
             raise RuntimeError(f"Cannot resume this run: {response.details.reason}")

prefect/logging/logging.yml

@@ -43,6 +43,7 @@ handlers:
     level: 0
     class: prefect.logging.handlers.PrefectConsoleHandler
     formatter: standard
+    stream: ext://sys.stderr
     styles:
       log.web_url: bright_blue
       log.local_url: bright_blue
@@ -69,6 +70,7 @@ handlers:
     level: 0
     class: logging.StreamHandler
     formatter: debug
+    stream: ext://sys.stderr
 
   worker_api:
     level: 0

prefect/main.py

@@ -8,7 +8,12 @@ from prefect.tasks import task, Task
 from prefect.context import tags
 from prefect.utilities.annotations import unmapped, allow_failure
 from prefect._result_records import ResultRecordMetadata
-from prefect.flow_runs import pause_flow_run, resume_flow_run, suspend_flow_run
+from prefect.flow_runs import (
+    aresume_flow_run,
+    pause_flow_run,
+    resume_flow_run,
+    suspend_flow_run,
+)
 from prefect.client.orchestration import get_client
 from prefect.client.cloud import get_cloud_client
 import prefect.variables  # pyright: ignore[reportUnusedImport] # TODO: Does this need to be imported here?
@@ -58,20 +63,21 @@ flow: FlowDecorator
 # Declare API for type-checkers
 __all__ = [
     "allow_failure",
+    "aresume_flow_run",
+    "aserve",
     "flow",
     "Flow",
     "get_client",
     "get_cloud_client",
     "get_run_logger",
+    "pause_flow_run",
+    "resume_flow_run",
+    "serve",
     "State",
+    "suspend_flow_run",
     "tags",
     "task",
     "Task",
     "Transaction",
     "unmapped",
-    "serve",
-    "aserve",
-    "pause_flow_run",
-    "resume_flow_run",
-    "suspend_flow_run",
 ]

prefect/runner/storage.py

@@ -919,7 +919,36 @@ def _format_token_from_credentials(
     if username:
         return f"{username}:{user_provided_token}"
 
-    # Fallback for plain dict credentials without a block
+    # Netloc-based provider detection for dict credentials (e.g., from YAML block references).
+    # When credentials come from deployment YAML like:
+    #   credentials: "{{ prefect.blocks.gitlab-credentials.my-block }}"
+    # they resolve to dicts, not Block instances, so the protocol check above doesn't apply.
+    # This provides sensible defaults for common git providers.
+    if "bitbucketserver" in netloc:
+        if ":" not in user_provided_token:
+            raise ValueError(
+                "Please provide a `username` and a `password` or `token` in your"
+                " BitBucketCredentials block to clone a repo from BitBucket Server."
+            )
+        return user_provided_token
+
+    elif "bitbucket" in netloc:
+        if (
+            user_provided_token.startswith("x-token-auth:")
+            or ":" in user_provided_token
+        ):
+            return user_provided_token
+        return f"x-token-auth:{user_provided_token}"
+
+    elif "gitlab" in netloc:
+        if user_provided_token.startswith("oauth2:"):
+            return user_provided_token
+        # Deploy tokens contain ":" (username:token format) and should not get oauth2: prefix
+        if ":" in user_provided_token:
+            return user_provided_token
+        return f"oauth2:{user_provided_token}"
+
+    # GitHub and other providers: plain token
     return user_provided_token
 
 

prefect/serializers.py

@@ -41,6 +41,21 @@ D = TypeVar("D", default=Any)
 _TYPE_ADAPTER_CACHE: dict[str, TypeAdapter[Any]] = {}
 
 
+def _get_importable_class(cls: type) -> type:
+    """
+    Get an importable class from a potentially parameterized generic.
+
+    For Pydantic generic models like `APIResult[str]`, the class name includes
+    type parameters (e.g., `APIResult[str]`) which cannot be imported. This
+    function extracts the origin class (e.g., `APIResult`) which can be imported.
+    """
+    if hasattr(cls, "__pydantic_generic_metadata__"):
+        origin = cls.__pydantic_generic_metadata__.get("origin")
+        if origin is not None:
+            return origin
+    return cls
+
+
 def prefect_json_object_encoder(obj: Any) -> Any:
     """
     `JSONEncoder.default` for encoding objects into JSON with extended type support.
@@ -58,8 +73,9 @@ def prefect_json_object_encoder(obj: Any) -> Any:
             ),
         }
     else:
+        importable_class = _get_importable_class(obj.__class__)
         return {
-            "__class__": to_qualified_name(obj.__class__),
+            "__class__": to_qualified_name(importable_class),
             "data": custom_pydantic_encoder({}, obj),
         }
 

prefect/server/api/background_workers.py

@@ -1,15 +1,16 @@
 import asyncio
 from contextlib import asynccontextmanager
+from logging import Logger
 from typing import Any, AsyncGenerator, Callable
 
 from docket import Docket, Worker
 
+from prefect.logging import get_logger
 from prefect.server.api.flow_runs import delete_flow_run_logs
 from prefect.server.api.task_runs import delete_task_run_logs
+from prefect.server.events.services import triggers as _triggers_module  # noqa: F401
 from prefect.server.models.deployments import mark_deployments_ready
 from prefect.server.models.work_queues import mark_work_queues_ready
-
-# Import task functions that need to be registered with docket
 from prefect.server.services.cancellation_cleanup import (
     cancel_child_task_runs,
     cancel_subflow_run,
@@ -21,6 +22,8 @@ from prefect.server.services.perpetual_services import (
 )
 from prefect.server.services.repossessor import revoke_expired_lease
 
+logger: Logger = get_logger(__name__)
+
 # Task functions to register with docket for background processing
 task_functions: list[Callable[..., Any]] = [
     # Simple background tasks (from Alex's PR #19377)
@@ -63,6 +66,16 @@ async def background_worker(
         if worker_task:
             worker_task.cancel()
             try:
-                await worker_task
+                logger.debug(
+                    "Waiting for background worker to finish after cancellation..."
+                )
+                await asyncio.wait_for(worker_task, timeout=5.0)
+                logger.debug(
+                    "Background worker finished successfully after cancellation"
+                )
+            except asyncio.TimeoutError:
+                logger.debug(
+                    "Background worker did not finish within 5 seconds after cancellation. Proceeding with shutdown"
+                )
             except asyncio.CancelledError:
                 pass

prefect/server/events/schemas/events.py

@@ -34,6 +34,7 @@ from prefect.settings import (
     PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE,
     PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES,
 )
+from prefect.utilities.urls import url_for
 
 if TYPE_CHECKING:
     import logging
@@ -212,6 +213,12 @@ class ReceivedEvent(Event):
         description="When the event was received by Prefect Cloud",
     )
 
+    @property
+    def url(self) -> Optional[str]:
+        """Returns the UI URL for this event, allowing users to link to events
+        in automation templates without parsing date strings."""
+        return url_for(self, url_type="ui")
+
     def as_database_row(self) -> dict[str, Any]:
         row = self.model_dump()
         row["resource_id"] = self.resource.id

prefect/server/events/services/triggers.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
 import asyncio
-from typing import TYPE_CHECKING, Any, NoReturn, Optional
+from typing import TYPE_CHECKING, NoReturn
+
+from docket import Perpetual
 
 from prefect.logging import get_logger
 from prefect.server.events import triggers
-from prefect.server.services.base import LoopService, RunInEphemeralServers, Service
+from prefect.server.services.base import RunInEphemeralServers, Service
+from prefect.server.services.perpetual_services import perpetual_service
 from prefect.server.utilities.messaging import Consumer, create_consumer
 from prefect.server.utilities.messaging._consumer_names import (
     generate_unique_consumer_name,
 )
-from prefect.settings import PREFECT_EVENTS_PROACTIVE_GRANULARITY
 from prefect.settings.context import get_current_settings
 from prefect.settings.models.server.services import ServicesBaseSetting
 
@@ -65,21 +67,15 @@ class ReactiveTriggers(RunInEphemeralServers, Service):
         logger.debug("Reactive triggers stopped")
 
 
-class ProactiveTriggers(RunInEphemeralServers, LoopService):
-    """Evaluates proactive automation triggers"""
-
-    @classmethod
-    def service_settings(cls) -> ServicesBaseSetting:
-        return get_current_settings().server.services.triggers
-
-    def __init__(self, loop_seconds: Optional[float] = None, **kwargs: Any):
-        super().__init__(
-            loop_seconds=(
-                loop_seconds
-                or PREFECT_EVENTS_PROACTIVE_GRANULARITY.value().total_seconds()
-            ),
-            **kwargs,
-        )
-
-    async def run_once(self) -> None:
-        await triggers.evaluate_proactive_triggers()
+@perpetual_service(
+    enabled_getter=lambda: get_current_settings().server.services.triggers.enabled,
+    run_in_ephemeral=True,
+)
+async def evaluate_proactive_triggers_periodic(
+    perpetual: Perpetual = Perpetual(
+        automatic=True,
+        every=get_current_settings().server.events.proactive_granularity,
+    ),
+) -> None:
+    """Evaluate proactive automation triggers on a periodic schedule."""
+    await triggers.evaluate_proactive_triggers()

prefect/server/models/events.py

@@ -419,6 +419,73 @@ async def work_pool_status_event(
     )
 
 
+async def work_pool_updated_event(
+    session: AsyncSession,
+    work_pool: "ORMWorkPool",
+    changed_fields: Dict[
+        str, Dict[str, Any]
+    ],  # {"field_name": {"old": value, "new": value}}
+    occurred: DateTime,
+) -> Event:
+    """Create an event for work pool field updates (non-status)."""
+    return Event(
+        occurred=occurred,
+        event="prefect.work-pool.updated",
+        resource={
+            "prefect.resource.id": f"prefect.work-pool.{work_pool.id}",
+            "prefect.resource.name": work_pool.name,
+            "prefect.work-pool.type": work_pool.type,
+            "prefect.resource.role": "work-pool",
+        },
+        payload={
+            "updated_fields": list(changed_fields.keys()),
+            "updates": changed_fields,
+        },
+        id=uuid7(),
+    )
+
+
+async def work_queue_updated_event(
+    session: AsyncSession,
+    work_queue: "ORMWorkQueue",
+    changed_fields: Dict[str, Dict[str, Any]],
+    occurred: DateTime,
+) -> Event:
+    """Create an event for work queue field updates (non-status)."""
+    related_work_pool_info: List[Dict[str, Any]] = []
+
+    if work_queue.work_pool_id:
+        work_pool = await models.workers.read_work_pool(
+            session=session,
+            work_pool_id=work_queue.work_pool_id,
+        )
+        if work_pool and work_pool.id and work_pool.name:
+            related_work_pool_info.append(
+                {
+                    "prefect.resource.id": f"prefect.work-pool.{work_pool.id}",
+                    "prefect.resource.name": work_pool.name,
+                    "prefect.work-pool.type": work_pool.type,
+                    "prefect.resource.role": "work-pool",
+                }
+            )
+
+    return Event(
+        occurred=occurred,
+        event="prefect.work-queue.updated",
+        resource={
+            "prefect.resource.id": f"prefect.work-queue.{work_queue.id}",
+            "prefect.resource.name": work_queue.name,
+            "prefect.resource.role": "work-queue",
+        },
+        related=related_work_pool_info,
+        payload={
+            "updated_fields": list(changed_fields.keys()),
+            "updates": changed_fields,
+        },
+        id=uuid7(),
+    )
+
+
 def _get_recent_preceding_work_pool_event_id(
     work_pool: Optional["ORMWorkPool"],
 ) -> Optional[UUID]: