prefect 3.7.4.dev4__py3-none-any.whl → 3.7.5.dev2__py3-none-any.whl

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.7.4.dev4"
-__build_date__ = "2026-06-05 09:17:18.703805+00:00"
-__git_commit__ = "0bad21f4ce99db95716f64cc2eab836eb274b52c"
+__version__ = "3.7.5.dev2"
+__build_date__ = "2026-06-09 09:17:59.185976+00:00"
+__git_commit__ = "d858cb6725864c9a993be6a6633009b03b5e6f5e"
 __dirty__ = False

prefect/cli/deploy/_core.py

@@ -19,7 +19,10 @@ from prefect.cli._prompts import (
 )
 from prefect.client.orchestration import get_client
 from prefect.client.schemas.filters import WorkerFilter
-from prefect.deployments.base import _save_deployment_to_prefect_file
+from prefect.deployments.base import (
+    _deployment_already_saved_to_prefect_file,
+    _save_deployment_to_prefect_file,
+)
 from prefect.deployments.runner import RunnerDeployment
 from prefect.deployments.steps.core import run_steps
 from prefect.exceptions import ObjectNotFound
@@ -420,7 +423,9 @@ async def _run_single_deploy(
         )
         console.print(message, soft_wrap=True)
 
-    if is_interactive() and not prefect_file.exists():
+    if is_interactive() and not _deployment_already_saved_to_prefect_file(
+        deploy_config_before_templating, prefect_file
+    ):
         if confirm(
             (
                 "Would you like to save configuration for this deployment for faster"

prefect/client/schemas/schedules.py

@@ -26,6 +26,26 @@ MAX_ITERATIONS = 1000
 MAX_RRULE_LENGTH = 6500
 
 
+def _iana_timezone_name(tzinfo: datetime.tzinfo) -> str:
+    """Return a valid IANA timezone name for *tzinfo*, or `"UTC"`."""
+    for attr in ("key", "name"):
+        value: Optional[str] = getattr(tzinfo, attr, None)
+        if value and is_valid_timezone(value):
+            return value
+
+    filename: Optional[str] = getattr(tzinfo, "_filename", None)
+    if filename:
+        normalized = filename.replace("\\", "/")
+        marker = "/zoneinfo/"
+        idx = normalized.find(marker)
+        if idx != -1:
+            candidate = normalized[idx + len(marker) :]
+            if candidate and is_valid_timezone(candidate):
+                return candidate
+
+    return "UTC"
+
+
 def is_valid_timezone(v: str) -> bool:
     """
     Validate that the provided timezone is a valid IANA timezone.
@@ -204,26 +224,27 @@ class RRuleSchedule(PrefectBaseModel):
         if isinstance(rrule, dateutil.rrule.rrule):
             dtstart = _rrule_dt(rrule)
             if dtstart and dtstart.tzinfo is not None:
-                timezone = dtstart.tzinfo.tzname(dtstart)
+                timezone = _iana_timezone_name(dtstart.tzinfo)
             else:
                 timezone = "UTC"
             return RRuleSchedule(rrule=str(rrule), timezone=timezone)
         rrules = _rrule(rrule)
         dtstarts = [dts for rr in rrules if (dts := _rrule_dt(rr)) is not None]
         unique_dstarts = set(d.astimezone(ZoneInfo("UTC")) for d in dtstarts)
-        unique_timezones = set(d.tzinfo for d in dtstarts if d.tzinfo is not None)
+        unique_tz_names = set(
+            _iana_timezone_name(d.tzinfo) for d in dtstarts if d.tzinfo is not None
+        )
 
-        if len(unique_timezones) > 1:
+        if len(unique_tz_names) > 1:
             raise ValueError(
-                f"rruleset has too many dtstart timezones: {unique_timezones}"
+                f"rruleset has too many dtstart timezones: {unique_tz_names}"
             )
 
         if len(unique_dstarts) > 1:
             raise ValueError(f"rruleset has too many dtstarts: {unique_dstarts}")
 
-        if unique_dstarts and unique_timezones:
-            [unique_tz] = unique_timezones
-            timezone = unique_tz.tzname(dtstarts[0])
+        if unique_dstarts and unique_tz_names:
+            [timezone] = unique_tz_names
         else:
             timezone = "UTC"
 

prefect/deployments/base.py

@@ -278,6 +278,33 @@ def _interval_schedule_to_dict(schedule: IntervalSchedule) -> dict[str, Any]:
     return schedule_config
 
 
+def _deployment_already_saved_to_prefect_file(
+    deployment: dict[str, Any],
+    prefect_file: Path = Path("prefect.yaml"),
+) -> bool:
+    """
+    Return True if `prefect.yaml` already contains a deployment entry matching the
+    given deployment's name and entrypoint.
+
+    Used to decide whether the interactive `prefect deploy` flow should offer to
+    persist a newly-created deployment: a deployment that is already declared in
+    the file does not need to be saved again, but a brand-new one (even when the
+    file otherwise exists) should still be offered up for saving.
+    """
+    if not prefect_file.exists():
+        return False
+
+    with prefect_file.open(mode="r") as f:
+        contents = yaml.safe_load(f) or {}
+
+    for existing in contents.get("deployments") or []:
+        if existing.get("name") == deployment.get("name") and existing.get(
+            "entrypoint"
+        ) == deployment.get("entrypoint"):
+            return True
+    return False
+
+
 def _save_deployment_to_prefect_file(
     deployment: dict[str, Any],
     build_steps: list[dict[str, Any]] | None = None,

prefect/flows.py

@@ -706,7 +706,11 @@ class Flow(Generic[P, R]):
                 from fastapi.encoders import jsonable_encoder
 
                 serialized_parameters[key] = jsonable_encoder(value)
-            except (TypeError, ValueError):
+            except (TypeError, ValueError, RecursionError):
+                # `jsonable_encoder` recurses into unknown objects with no cycle
+                # or depth limit, so a deeply-nested or self-referential value
+                # raises `RecursionError`. Treat it like any other unserializable
+                # value and fall back to the placeholder below.
                 logger.debug(
                     f"Parameter {key!r} for flow {self.name!r} is unserializable. "
                     f"Type {type(value).__name__!r} and will not be stored "

prefect/server/AGENTS.md

@@ -24,6 +24,13 @@ The `variables` endpoints are a good canonical example of this pattern for simpl
 
 **Singleton server settings** (not tied to a specific run or resource) skip a dedicated table — store them as JSON in the `Configuration` key-value store via `models/configuration.py`. Define a string key constant in the wrapping module (see `models/storage_defaults.py` for the pattern).
 
+## Object Lifecycle Events
+
+Domain objects emit `prefect.<object>.{created,updated,deleted}` events from their `models/` CRUD functions (`models/variables.py` is the simplest example). Two non-obvious rules:
+
+- **Builders live in `events/schemas/lifecycle.py`, not `models/events.py`.** `models/events.py` imports `models.deployments`, so a model imported early in `models/__init__` (e.g. `block_types`, `block_documents`) that imports a builder from there triggers a circular import. The builders in `lifecycle.py` are pure functions of an ORM object + timestamp with no model-layer imports, so any model can use them safely.
+- **Emission is inline and pre-commit.** `emit_*` helpers reference `clients.PrefectServerEventsClient` as a module attribute (so the autouse test fixture's single patch on `events.clients.PrefectServerEventsClient` captures them) and publish within the request transaction — there is no request-scoped buffer, so a rolled-back create still emits.
+
 ## Database Migrations
 
 Migrations use Alembic via wrapper functions in `database/alembic_commands.py`:

prefect/server/api/workers.py

@@ -25,8 +25,10 @@ import prefect.server.models as models
 import prefect.server.schemas as schemas
 from prefect._internal.uuid7 import uuid7
 from prefect.client.schemas.worker_channel import (
+    CLEANUP_DELIVERY_CAPABILITY,
     WORK_POOL_SNAPSHOT_CAPABILITY,
     WORKER_HEARTBEAT_CAPABILITY,
+    WorkerChannelCapability,
     WorkerChannelCloseReason,
     WorkerChannelProtocolError,
     WorkerHelloFrame,
@@ -48,6 +50,10 @@ from prefect.server.schemas.statuses import WorkQueueStatus
 from prefect.server.utilities import subscriptions
 from prefect.server.utilities import worker_channel as worker_channel_utils
 from prefect.server.utilities.server import PrefectRouter
+from prefect.server.worker_communication.cleanup_queue import (
+    WorkerCleanupQueue,
+    get_worker_cleanup_queue,
+)
 from prefect.types import DateTime
 from prefect.types._datetime import now
 
@@ -61,7 +67,7 @@ router: PrefectRouter = PrefectRouter(
 )
 logger: Logger = get_logger("prefect.server.api.workers")
 
-_OSS_WORKER_CHANNEL_ACCEPTED_CAPABILITIES = [
+_OSS_WORKER_CHANNEL_REQUIRED_CAPABILITIES: list[WorkerChannelCapability] = [
     WORKER_HEARTBEAT_CAPABILITY,
     WORK_POOL_SNAPSHOT_CAPABILITY,
 ]
@@ -183,6 +189,26 @@ class WorkerChannelWorkPoolUpdateEvent:
     changed_fields: dict[str, dict[str, Any]]
 
 
+def _worker_requested_cleanup_delivery(hello: WorkerHelloFrame) -> bool:
+    return (
+        CLEANUP_DELIVERY_CAPABILITY in hello.payload.requested_capabilities
+        and bool(hello.payload.handled_cleanup_kinds)
+        and hello.payload.max_cleanup_concurrency > 0
+    )
+
+
+def _accepted_worker_channel_capabilities(
+    hello: WorkerHelloFrame,
+    *,
+    cleanup_queue_available: bool,
+) -> list[WorkerChannelCapability]:
+    accepted = list(_OSS_WORKER_CHANNEL_REQUIRED_CAPABILITIES)
+    if cleanup_queue_available and _worker_requested_cleanup_delivery(hello):
+        accepted.append(CLEANUP_DELIVERY_CAPABILITY)
+
+    return accepted
+
+
 async def _receive_worker_hello(websocket: WebSocket) -> WorkerHelloFrame:
     try:
         message = await websocket.receive_json()
@@ -290,6 +316,7 @@ async def _build_worker_ready_frame(
     session: AsyncSession,
     work_pool_name: str,
     hello: WorkerHelloFrame,
+    cleanup_queue_available: bool,
 ) -> tuple[WorkerReadyFrame, WorkerChannelWorkPoolUpdateEvent | None]:
     try:
         selected_channel_version = select_worker_channel_version(
@@ -371,7 +398,10 @@ async def _build_worker_ready_frame(
     )
 
     requested_capabilities = list(dict.fromkeys(hello.payload.requested_capabilities))
-    accepted = _OSS_WORKER_CHANNEL_ACCEPTED_CAPABILITIES
+    accepted = _accepted_worker_channel_capabilities(
+        hello,
+        cleanup_queue_available=cleanup_queue_available,
+    )
     accepted_set = set(accepted)
     rejected = [
         capability
@@ -393,7 +423,11 @@ async def _build_worker_ready_frame(
                 ),
                 "accepted_capabilities": accepted,
                 "rejected_capabilities": rejected,
-                "effective_max_cleanup_concurrency": 0,
+                "effective_max_cleanup_concurrency": (
+                    hello.payload.max_cleanup_concurrency
+                    if CLEANUP_DELIVERY_CAPABILITY in accepted_set
+                    else 0
+                ),
                 "resolved_work_queues": [
                     {"id": work_queue.id, "name": work_queue.name}
                     for work_queue in work_queues
@@ -1058,6 +1092,16 @@ async def worker_channel_connect(
 
     try:
         hello = await _receive_worker_hello(websocket)
+        cleanup_queue: WorkerCleanupQueue | None = None
+        if _worker_requested_cleanup_delivery(hello):
+            try:
+                cleanup_queue = get_worker_cleanup_queue()
+            except Exception:
+                logger.exception(
+                    "Worker cleanup delivery queue initialization failed; "
+                    "rejecting cleanup delivery capability"
+                )
+
         async with worker_channel_utils.messaging.ephemeral_subscription(
             worker_channel_utils.WORKER_CHANNEL_SNAPSHOT_TOPIC,
         ) as consumer_kwargs:
@@ -1066,6 +1110,7 @@ async def worker_channel_connect(
                     session=session,
                     work_pool_name=work_pool_name,
                     hello=hello,
+                    cleanup_queue_available=cleanup_queue is not None,
                 )
 
             if work_pool_update_event is not None:
@@ -1094,6 +1139,17 @@ async def worker_channel_connect(
                 work_pool_id=ready.payload.initial_snapshot.work_pool.id,
                 consumer_id=hello.payload.consumer_id,
                 worker_name=hello.payload.worker_name,
+                cleanup_queue=(
+                    cleanup_queue
+                    if CLEANUP_DELIVERY_CAPABILITY
+                    in ready.payload.accepted_capabilities
+                    else None
+                ),
+                cleanup_kinds=tuple(hello.payload.handled_cleanup_kinds),
+                cleanup_work_queue_ids=tuple(
+                    work_queue.id for work_queue in ready.payload.resolved_work_queues
+                ),
+                max_cleanup_concurrency=ready.payload.effective_max_cleanup_concurrency,
             )
             await connection.run(ready, consumer_kwargs)
 

prefect/server/events/models/automations.py

@@ -10,7 +10,8 @@ from typing_extensions import Literal, TypeAlias
 
 from prefect.logging import get_logger
 from prefect.server.database import PrefectDBInterface, db_injector
-from prefect.server.events import filters
+from prefect.server.events import clients, filters
+from prefect.server.events.schemas import lifecycle
 from prefect.server.events.schemas.automations import (
     Automation,
     AutomationPartialUpdate,
@@ -23,6 +24,31 @@ from prefect.utilities.asyncutils import run_coro_as_sync
 
 logger: logging.Logger = get_logger(__name__)
 
+
+async def emit_automation_created_event(automation: Automation) -> None:
+    """Emit an event when an automation is created."""
+    async with clients.PrefectServerEventsClient() as events_client:
+        await events_client.emit(
+            lifecycle.automation_created_event(automation, now("UTC"))
+        )
+
+
+async def emit_automation_updated_event(automation: Automation) -> None:
+    """Emit an event when an automation is updated."""
+    async with clients.PrefectServerEventsClient() as events_client:
+        await events_client.emit(
+            lifecycle.automation_updated_event(automation, now("UTC"))
+        )
+
+
+async def emit_automation_deleted_event(automation: Automation) -> None:
+    """Emit an event when an automation is deleted."""
+    async with clients.PrefectServerEventsClient() as events_client:
+        await events_client.emit(
+            lifecycle.automation_deleted_event(automation, now("UTC"))
+        )
+
+
 AutomationChangeEvent: TypeAlias = Literal[
     "automation__created", "automation__updated", "automation__deleted"
 ]
@@ -176,6 +202,7 @@ async def create_automation(
     await _sync_automation_related_resources(session, new_automation.id, automation)
 
     await _notify(session, automation, "created")
+    await emit_automation_created_event(automation)
     return automation
 
 
@@ -220,6 +247,11 @@ async def update_automation(
         )
 
     await _notify(session, automation, "updated")
+
+    updated_automation = await read_automation(session, automation_id)
+    if updated_automation is not None:
+        await emit_automation_updated_event(updated_automation)
+
     return result.rowcount > 0  # type: ignore
 
 
@@ -260,6 +292,7 @@ async def delete_automation(
     await _sync_automation_related_resources(session, automation_id, None)
 
     await _notify(session, automation, "deleted")
+    await emit_automation_deleted_event(automation)
     return True