prefect 3.6.6__py3-none-any.whl → 3.6.7__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.6"
-__build_date__ = "2025-12-11 20:20:23.556858+00:00"
-__git_commit__ = "f7d4baf4e04fc31b7a7949b9bc6f2e59d848272b"
+__version__ = "3.6.7"
+__build_date__ = "2025-12-18 19:54:23.981675+00:00"
+__git_commit__ = "ebfef643e5d55b20a7b0b6a80e9756987ac415cb"
 __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/_experimental/plugins/spec.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass
-from typing import Callable, Mapping, Optional
+from typing import Any, Callable, Mapping, Optional
 
 import pluggy
 
@@ -83,3 +83,22 @@ class HookSpec:
             - May be async or sync
             - Exceptions are caught and logged unless required=True in strict mode
         """
+
+    @hookspec
+    def set_database_connection_params(
+        self, connection_url: str, settings: Any
+    ) -> Mapping[str, Any]:
+        """
+        Set additional database connection parameters.
+
+        This hook is called when creating a database engine. It allows plugins
+        to provide additional connection parameters, such as authentication
+        tokens or SSL configuration.
+
+        Args:
+            connection_url: The database connection URL
+            settings: The current Prefect settings
+
+        Returns:
+            Dictionary of connection parameters to merge into connect_args
+        """

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/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

@@ -6,18 +6,19 @@ from docket import Docket, Worker
 
 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,
 )
+from prefect.server.services.late_runs import mark_flow_run_late
 from prefect.server.services.pause_expirations import fail_expired_pause
 from prefect.server.services.perpetual_services import (
     register_and_schedule_perpetual_services,
 )
+from prefect.server.services.repossessor import revoke_expired_lease
 
 # Task functions to register with docket for background processing
 task_functions: list[Callable[..., Any]] = [
@@ -30,6 +31,8 @@ task_functions: list[Callable[..., Any]] = [
     cancel_child_task_runs,
     cancel_subflow_run,
     fail_expired_pause,
+    mark_flow_run_late,
+    revoke_expired_lease,
 ]
 
 

prefect/server/api/server.py

@@ -156,6 +156,7 @@ def _install_sqlite_locked_log_filter() -> None:
 
     filter_ = _SQLiteLockedOperationalErrorFilter()
     logging.getLogger("uvicorn.error").addFilter(filter_)
+    logging.getLogger("docket.worker").addFilter(filter_)
     _SQLITE_LOCKED_LOG_FILTER = filter_
 
 

prefect/server/database/configurations.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import sqlite3
 import ssl
 import traceback
@@ -25,6 +26,12 @@ from sqlalchemy.ext.asyncio import (
 from sqlalchemy.pool import ConnectionPoolEntry
 from typing_extensions import TypeAlias
 
+from prefect._experimental.plugins import (
+    HookSpec,
+    build_manager,
+    call_async_hook,
+    load_entry_point_plugins,
+)
 from prefect._internal.observability import configure_logfire
 from prefect.settings import (
     PREFECT_API_DATABASE_CONNECTION_TIMEOUT,
@@ -279,6 +286,33 @@ class AsyncPostgresConfiguration(BaseDatabaseConfiguration):
                 pg_ctx.verify_mode = ssl.CERT_REQUIRED
                 connect_args["ssl"] = pg_ctx
 
+            # Initialize plugin manager
+            if get_current_settings().experiments.plugins.enabled:
+                pm = build_manager(HookSpec)
+                load_entry_point_plugins(
+                    pm,
+                    allow=get_current_settings().experiments.plugins.allow,
+                    deny=get_current_settings().experiments.plugins.deny,
+                    logger=logging.getLogger("prefect.plugins"),
+                )
+
+                # Call set_database_connection_params hook
+                results = await call_async_hook(
+                    pm,
+                    "set_database_connection_params",
+                    connection_url=self.connection_url,
+                    settings=get_current_settings(),
+                )
+
+                for _, params, error in results:
+                    if error:
+                        # Log error but don't fail, other plugins might succeed
+                        logging.getLogger("prefect.server.database").warning(
+                            "Plugin failed to set database connection params: %s", error
+                        )
+                    elif params:
+                        connect_args.update(params)
+
             if connect_args:
                 kwargs["connect_args"] = connect_args
 

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()