prefect 3.6.5.dev3__py3-none-any.whl → 3.6.6__py3-none-any.whl

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.6.5.dev3"
-__build_date__ = "2025-11-26 08:10:05.347240+00:00"
-__git_commit__ = "a9d0a54f5ed7685cbc9184771351439d97517d56"
+__version__ = "3.6.6"
+__build_date__ = "2025-12-11 20:20:23.556858+00:00"
+__git_commit__ = "f7d4baf4e04fc31b7a7949b9bc6f2e59d848272b"
 __dirty__ = False

prefect/_states.py

@@ -0,0 +1,292 @@
+"""
+Private module containing sync versions of state functions.
+
+These functions are used internally by the sync task engine to avoid
+run_coro_as_sync overhead on Windows.
+"""
+
+from __future__ import annotations
+
+import datetime
+import sys
+import uuid
+from types import GeneratorType
+from typing import TYPE_CHECKING, Any, Optional
+
+import anyio
+import httpx
+
+from prefect.client.schemas.objects import State, StateType
+from prefect.exceptions import MissingContextError, TerminationSignal
+from prefect.logging.loggers import get_logger, get_run_logger
+from prefect.states import (
+    Completed,
+    Crashed,
+    Failed,
+    StateGroup,
+    format_exception,
+    is_state_iterable,
+)
+from prefect.utilities.collections import ensure_iterable
+
+if TYPE_CHECKING:
+    import logging
+
+    from prefect.results import (
+        R,
+        ResultStore,
+    )
+
+logger: "logging.Logger" = get_logger("states")
+
+
+def exception_to_crashed_state_sync(
+    exc: BaseException,
+    result_store: Optional["ResultStore"] = None,
+) -> State:
+    """
+    Sync version of exception_to_crashed_state.
+
+    Takes an exception that occurs _outside_ of user code and converts it to a
+    'Crash' exception with a 'Crashed' state.
+    """
+    state_message = None
+
+    if isinstance(exc, anyio.get_cancelled_exc_class()):
+        state_message = "Execution was cancelled by the runtime environment."
+
+    elif isinstance(exc, KeyboardInterrupt):
+        state_message = "Execution was aborted by an interrupt signal."
+
+    elif isinstance(exc, TerminationSignal):
+        state_message = "Execution was aborted by a termination signal."
+
+    elif isinstance(exc, SystemExit):
+        state_message = "Execution was aborted by Python system exit call."
+
+    elif isinstance(exc, (httpx.TimeoutException, httpx.ConnectError)):
+        try:
+            request: httpx.Request = exc.request
+        except RuntimeError:
+            # The request property is not set
+            state_message = (
+                "Request failed while attempting to contact the server:"
+                f" {format_exception(exc)}"
+            )
+        else:
+            # TODO: We can check if this is actually our API url
+            state_message = f"Request to {request.url} failed: {format_exception(exc)}."
+
+    else:
+        state_message = (
+            "Execution was interrupted by an unexpected exception:"
+            f" {format_exception(exc)}"
+        )
+
+    if result_store:
+        key = uuid.uuid4().hex
+        data = result_store.create_result_record(exc, key=key)
+    else:
+        # Attach the exception for local usage, will not be available when retrieved
+        # from the API
+        data = exc
+
+    return Crashed(message=state_message, data=data)
+
+
+def exception_to_failed_state_sync(
+    exc: Optional[BaseException] = None,
+    result_store: Optional["ResultStore"] = None,
+    write_result: bool = False,
+    **kwargs: Any,
+) -> State[BaseException]:
+    """
+    Sync version of exception_to_failed_state.
+
+    Convenience function for creating `Failed` states from exceptions
+    """
+    try:
+        local_logger = get_run_logger()
+    except MissingContextError:
+        local_logger = logger
+
+    if not exc:
+        _, exc, _ = sys.exc_info()
+        if exc is None:
+            raise ValueError(
+                "Exception was not passed and no active exception could be found."
+            )
+    else:
+        pass
+
+    if result_store:
+        key = uuid.uuid4().hex
+        data = result_store.create_result_record(exc, key=key)
+        if write_result:
+            try:
+                result_store.persist_result_record(data)
+            except Exception as nested_exc:
+                local_logger.warning(
+                    "Failed to write result: %s Execution will continue, but the result has not been written",
+                    nested_exc,
+                )
+    else:
+        # Attach the exception for local usage, will not be available when retrieved
+        # from the API
+        data = exc
+
+    existing_message = kwargs.pop("message", "")
+    if existing_message and not existing_message.endswith(" "):
+        existing_message += " "
+
+    # TODO: Consider if we want to include traceback information, it is intentionally
+    #       excluded from messages for now
+    message = existing_message + format_exception(exc)
+
+    state = Failed(data=data, message=message, **kwargs)
+    state.state_details.retriable = False
+
+    return state
+
+
+def return_value_to_state_sync(
+    retval: "R",
+    result_store: "ResultStore",
+    key: Optional[str] = None,
+    expiration: Optional[datetime.datetime] = None,
+    write_result: bool = False,
+) -> "State[R]":
+    """
+    Sync version of return_value_to_state.
+
+    Given a return value from a user's function, create a `State` the run should
+    be placed in.
+
+    - If data is returned, we create a 'COMPLETED' state with the data
+    - If a single, manually created state is returned, we use that state as given
+        (manual creation is determined by the lack of ids)
+    - If an upstream state or iterable of upstream states is returned, we apply the
+        aggregate rule
+
+    The aggregate rule says that given multiple states we will determine the final state
+    such that:
+
+    - If any states are not COMPLETED the final state is FAILED
+    - If all of the states are COMPLETED the final state is COMPLETED
+    - The states will be placed in the final state `data` attribute
+
+    Callers should resolve all futures into states before passing return values to this
+    function.
+    """
+    from prefect.results import (
+        ResultRecord,
+        ResultRecordMetadata,
+    )
+
+    try:
+        local_logger = get_run_logger()
+    except MissingContextError:
+        local_logger = logger
+
+    if (
+        isinstance(retval, State)
+        # Check for manual creation
+        and not retval.state_details.flow_run_id
+        and not retval.state_details.task_run_id
+    ):
+        state = retval
+        # Unless the user has already constructed a result explicitly, use the store
+        # to update the data to the correct type
+        if not isinstance(state.data, (ResultRecord, ResultRecordMetadata)):
+            result_record = result_store.create_result_record(
+                state.data,
+                key=key,
+                expiration=expiration,
+            )
+            if write_result:
+                try:
+                    result_store.persist_result_record(result_record)
+                except Exception as exc:
+                    local_logger.warning(
+                        "Encountered an error while persisting result: %s Execution will continue, but the result has not been persisted",
+                        exc,
+                    )
+            state.data = result_record
+        return state
+
+    # Determine a new state from the aggregate of contained states
+    if isinstance(retval, State) or is_state_iterable(retval):
+        states = StateGroup(ensure_iterable(retval))
+
+        # Determine the new state type
+        if states.all_completed():
+            new_state_type = StateType.COMPLETED
+        elif states.any_cancelled():
+            new_state_type = StateType.CANCELLED
+        elif states.any_paused():
+            new_state_type = StateType.PAUSED
+        else:
+            new_state_type = StateType.FAILED
+
+        # Generate a nice message for the aggregate
+        if states.all_completed():
+            message = "All states completed."
+        elif states.any_cancelled():
+            message = f"{states.cancelled_count}/{states.total_count} states cancelled."
+        elif states.any_paused():
+            message = f"{states.paused_count}/{states.total_count} states paused."
+        elif states.any_failed():
+            message = f"{states.fail_count}/{states.total_count} states failed."
+        elif not states.all_final():
+            message = (
+                f"{states.not_final_count}/{states.total_count} states are not final."
+            )
+        else:
+            message = "Given states: " + states.counts_message()
+
+        # TODO: We may actually want to set the data to a `StateGroup` object and just
+        #       allow it to be unpacked into a tuple and such so users can interact with
+        #       it
+        result_record = result_store.create_result_record(
+            retval,
+            key=key,
+            expiration=expiration,
+        )
+        if write_result:
+            try:
+                result_store.persist_result_record(result_record)
+            except Exception as exc:
+                local_logger.warning(
+                    "Encountered an error while persisting result: %s Execution will continue, but the result has not been persisted",
+                    exc,
+                )
+        return State(
+            type=new_state_type,
+            message=message,
+            data=result_record,
+        )
+
+    # Generators aren't portable, implicitly convert them to a list.
+    if isinstance(retval, GeneratorType):
+        data = list(retval)
+    else:
+        data = retval
+
+    # Otherwise, they just gave data and this is a completed retval
+    if isinstance(data, ResultRecord):
+        return Completed(data=data)
+    else:
+        result_record = result_store.create_result_record(
+            data,
+            key=key,
+            expiration=expiration,
+        )
+        if write_result:
+            try:
+                result_store.persist_result_record(result_record)
+            except Exception as exc:
+                local_logger.warning(
+                    "Encountered an error while persisting result: %s Execution will continue, but the result has not been persisted",
+                    exc,
+                )
+        return Completed(data=result_record)

prefect/blocks/notifications.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import re
 from abc import ABC
 from typing import Any, Optional, cast
 
@@ -105,6 +106,9 @@ class SlackWebhook(AppriseNotificationBlock):
     """
     Enables sending notifications via a provided Slack webhook.
 
+    Supports both standard Slack webhooks (hooks.slack.com) and Slack GovCloud
+    webhooks (hooks.slack-gov.com).
+
     Examples:
         Load a saved Slack webhook and send a message:
         ```python
@@ -130,6 +134,73 @@ class SlackWebhook(AppriseNotificationBlock):
         examples=["https://hooks.slack.com/XXX"],
     )
 
+    _SLACK_WEBHOOK_URL_PATTERN: re.Pattern[str] = re.compile(
+        r"^https?://(?P<host>hooks\.slack(?:-gov)?\.com)/services/"
+        r"(?P<token_a>[A-Z0-9]+)/"
+        r"(?P<token_b>[A-Z0-9]+)/"
+        r"(?P<token_c>[A-Z0-9]+)/?$",
+        re.I,
+    )
+
+    def block_initialization(self) -> None:
+        """Initialize the Slack webhook client.
+
+        This method handles both standard Slack webhooks and Slack GovCloud webhooks.
+        Apprise's built-in Slack plugin only supports hooks.slack.com, so we need to
+        manually construct the NotifySlack instance for slack-gov.com URLs to ensure
+        notifications are sent to the correct host.
+
+        See: https://github.com/caronc/apprise/issues/XXXX (upstream issue)
+        """
+        webhook_url = self.url.get_secret_value()
+        match = self._SLACK_WEBHOOK_URL_PATTERN.match(webhook_url)
+
+        # If it's not a recognized Slack webhook shape, delegate to the base behavior.
+        # This lets restricted-URL checks and existing Apprise validation run as before.
+        if not match:
+            self._start_apprise_client(self.url)
+            return
+
+        host = match.group("host")
+
+        # Standard Slack: let Apprise handle it like it always has.
+        if host == "hooks.slack.com":
+            self._start_apprise_client(self.url)
+            return
+
+        # GovCloud: we know it's a valid Slack webhook and host is hooks.slack-gov.com
+        # We must add the NotifySlack instance directly to the apprise client
+        # (rather than passing slack_instance.url()) because the webhook_url
+        # override is an instance attribute that would be lost if apprise
+        # re-parsed the URL string.
+        from apprise import Apprise, AppriseAsset
+
+        try:
+            from apprise.plugins.slack import NotifySlack
+        except ImportError:
+            from apprise.plugins.NotifySlack import (
+                NotifySlack,  # pyright: ignore[reportMissingImports]
+            )
+
+        token_a = match.group("token_a")
+        token_b = match.group("token_b")
+        token_c = match.group("token_c")
+
+        slack_instance = NotifySlack(
+            token_a=token_a,
+            token_b=token_b,
+            token_c=token_c,
+        )
+        slack_instance.webhook_url = f"https://{host}/services"
+
+        prefect_app_data = AppriseAsset(
+            app_id="Prefect Notifications",
+            app_desc="Prefect Notifications",
+            app_url="https://prefect.io",
+        )
+        self._apprise_client = Apprise(asset=prefect_app_data)
+        self._apprise_client.add(slack_instance)
+
 
 class MicrosoftTeamsWebhook(AppriseNotificationBlock):
     """

prefect/cli/deploy/_core.py

@@ -327,11 +327,17 @@ async def _run_single_deploy(
         triggers = []
 
     if isinstance(deploy_config.get("concurrency_limit"), dict):
-        deploy_config["concurrency_options"] = {
+        concurrency_options = {
             "collision_strategy": get_from_dict(
                 deploy_config, "concurrency_limit.collision_strategy"
             )
         }
+        grace_period_seconds = get_from_dict(
+            deploy_config, "concurrency_limit.grace_period_seconds"
+        )
+        if grace_period_seconds is not None:
+            concurrency_options["grace_period_seconds"] = grace_period_seconds
+        deploy_config["concurrency_options"] = concurrency_options
         deploy_config["concurrency_limit"] = get_from_dict(
             deploy_config, "concurrency_limit.limit"
         )

prefect/cli/deploy/_models.py

@@ -7,7 +7,6 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 from prefect._experimental.sla.objects import SlaTypes
 from prefect.client.schemas.actions import DeploymentScheduleCreate
 from prefect.client.schemas.schedules import SCHEDULE_TYPES
-from prefect.events import DeploymentTriggerTypes
 
 
 class WorkPoolConfig(BaseModel):
@@ -52,7 +51,9 @@ class DeploymentConfig(BaseModel):
     work_pool: Optional[WorkPoolConfig] = None
 
     # automations metadata
-    triggers: Optional[List[DeploymentTriggerTypes]] = None
+    # Triggers are stored as raw dicts to allow Jinja templating (e.g., enabled: "{{ prefect.variables.is_prod }}")
+    # Strict validation happens later in _initialize_deployment_triggers after template resolution
+    triggers: Optional[List[Dict[str, Any]]] = None
     sla: Optional[List[SlaTypes]] = None
 
 
@@ -99,6 +100,7 @@ class ConcurrencyLimitSpec(BaseModel):
 
     limit: Optional[int] = None
     collision_strategy: Optional[str] = None
+    grace_period_seconds: Optional[int] = None
 
 
 class RawScheduleConfig(BaseModel):

prefect/client/orchestration/_flow_runs/client.py

@@ -456,6 +456,7 @@ class FlowRunClient(BaseClient):
             value: The input value.
             sender: The sender of the input.
         """
+        from prefect.client.schemas.objects import FlowRunInput
 
         # Initialize the input to ensure that the key is valid.
         FlowRunInput(flow_run_id=flow_run_id, key=key, value=value)

prefect/client/schemas/objects.py

@@ -155,6 +155,12 @@ class ConcurrencyOptions(PrefectBaseModel):
     """
 
     collision_strategy: ConcurrencyLimitStrategy
+    grace_period_seconds: Optional[int] = Field(
+        default=None,
+        ge=60,
+        le=86400,
+        description="Grace period in seconds for infrastructure to start before concurrency slots are revoked. If not set, falls back to server setting.",
+    )
 
 
 class ConcurrencyLimitConfig(PrefectBaseModel):
@@ -164,6 +170,12 @@ class ConcurrencyLimitConfig(PrefectBaseModel):
 
     limit: int
     collision_strategy: ConcurrencyLimitStrategy = ConcurrencyLimitStrategy.ENQUEUE
+    grace_period_seconds: Optional[int] = Field(
+        default=None,
+        ge=60,
+        le=86400,
+        description="Grace period in seconds for infrastructure to start before concurrency slots are revoked",
+    )
 
 
 class ConcurrencyLeaseHolder(PrefectBaseModel):

prefect/concurrency/services.py

@@ -1,8 +1,12 @@
 import asyncio
+import json
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
+from threading import Lock
 from typing import TYPE_CHECKING, Literal, Optional
+from uuid import uuid4
 
+import cachetools
 import httpx
 from starlette import status
 from typing_extensions import TypeAlias, Unpack
@@ -16,6 +20,14 @@ if TYPE_CHECKING:
     from prefect.client.orchestration import PrefectClient
     from prefect.client.schemas.objects import ConcurrencyLeaseHolder
 
+# Shared cache for tags with no concurrency limits.
+# When a set of tags is known to have no limits, we cache that result
+# to avoid unnecessary API calls.
+_no_limits_cache: cachetools.TTLCache[frozenset[str], bool] = cachetools.TTLCache(
+    maxsize=1000, ttl=5.0
+)
+_cache_lock = Lock()
+
 _Item: TypeAlias = tuple[
     int, Literal["concurrency", "rate_limit"], Optional[float], Optional[int]
 ]
@@ -127,16 +139,37 @@ class ConcurrencySlotAcquisitionWithLeaseService(
             httpx.HTTPStatusError: If the server returns an error other than 423 LOCKED
             TimeoutError: If acquisition times out
         """
+        use_cache = _should_use_cache(self.concurrency_limit_names, holder)
+        cache_key = frozenset(self.concurrency_limit_names)
+
         with timeout_async(seconds=timeout_seconds):
             while True:
                 try:
-                    return await self._client.increment_concurrency_slots_with_lease(
-                        names=self.concurrency_limit_names,
-                        slots=slots,
-                        mode=mode,
-                        lease_duration=lease_duration,
-                        holder=holder,
+                    if use_cache:
+                        with _cache_lock:
+                            if _no_limits_cache.get(cache_key, False):
+                                return _create_empty_limits_response()
+
+                    response = (
+                        await self._client.increment_concurrency_slots_with_lease(
+                            names=self.concurrency_limit_names,
+                            slots=slots,
+                            mode=mode,
+                            lease_duration=lease_duration,
+                            holder=holder,
+                        )
                     )
+
+                    if use_cache:
+                        try:
+                            response_data = response.json()
+                            if not response_data.get("limits"):
+                                with _cache_lock:
+                                    _no_limits_cache[cache_key] = True
+                        except Exception:
+                            pass
+
+                    return response
                 except httpx.HTTPStatusError as exc:
                     if exc.response.status_code != status.HTTP_423_LOCKED:
                         raise
@@ -151,3 +184,35 @@ class ConcurrencySlotAcquisitionWithLeaseService(
                     await asyncio.sleep(retry_after)
                     if max_retries is not None:
                         max_retries -= 1
+
+
+def _should_use_cache(
+    names: list[str], holder: Optional["ConcurrencyLeaseHolder"]
+) -> bool:
+    """Determine if caching should be used for this concurrency acquisition.
+
+    Caching is only enabled for task-run tag-based concurrency checks to avoid
+    unnecessary API calls when no limits exist for those tags. This specifically
+    targets the task engine path that uses names like "tag:..." with a task_run holder.
+    """
+    if holder is None:
+        return False
+    if getattr(holder, "type", None) != "task_run":
+        return False
+    if not names:
+        return False
+    return all(name.startswith("tag:") for name in names)
+
+
+def _create_empty_limits_response() -> httpx.Response:
+    """Create a synthetic httpx.Response indicating no concurrency limits exist.
+
+    This is used when we've cached that a set of tags has no limits,
+    allowing us to skip the API call entirely.
+    """
+    response_data = {"lease_id": str(uuid4()), "limits": []}
+    return httpx.Response(
+        status_code=200,
+        content=json.dumps(response_data).encode(),
+        headers={"content-type": "application/json"},
+    )

prefect/deployments/base.py

@@ -251,6 +251,9 @@ def _format_deployment_for_saving_to_prefect_file(
                 concurrency_limit["collision_strategy"] = str(
                     concurrency_limit["collision_strategy"].value
                 )
+            concurrency_limit = {
+                k: v for k, v in concurrency_limit.items() if v is not None
+            }
         deployment["concurrency_limit"] = concurrency_limit
 
     return deployment