prefect 3.6.3.dev1__tar.gz → 3.6.3.dev3__tar.gz

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect
-Version: 3.6.3.dev1
+Version: 3.6.3.dev3
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

prefect-3.6.3.dev3/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.3.dev3"
+__build_date__ = "2025-11-19 08:09:35.708811+00:00"
+__git_commit__ = "a3db33d4f9ee7a665430ae6017c649d057139bd3"
+__dirty__ = False

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/_internal/pydantic/validated_func.py

@@ -73,6 +73,7 @@ class ValidatedFunction:
         self.positional_only_args: set[str] = set()
         self.v_args_name = V_ARGS_NAME
         self.v_kwargs_name = V_KWARGS_NAME
+        self._needs_rebuild = False
 
         # Check for conflicts with internal field names
         reserved_names = {
@@ -236,8 +237,14 @@ class ValidatedFunction:
         # This is necessary when using `from __future__ import annotations` or when
         # parameters reference types not in the current scope
         # Only rebuild if we detected forward references to avoid performance overhead
+        # If rebuild fails (e.g., forward-referenced types not yet defined), defer to validation time
         if has_forward_refs:
-            self.model.model_rebuild(_types_namespace=self.raw_function.__globals__)
+            try:
+                self.model.model_rebuild(_types_namespace=self.raw_function.__globals__)
+            except (NameError, AttributeError):
+                # Forward references can't be resolved yet (e.g., types defined after decorator)
+                # Model will be rebuilt during validate_call_args when types are available
+                self._needs_rebuild = True
 
     def validate_call_args(
         self, args: tuple[Any, ...], kwargs: dict[str, Any]
@@ -302,6 +309,17 @@ class ValidatedFunction:
         if duplicate_kwargs:
             values[V_DUPLICATE_KWARGS] = duplicate_kwargs
 
+        # Rebuild model if needed to resolve any forward references that weren't available
+        # at initialization time (e.g., when using `from __future__ import annotations`)
+        # Only rebuild if we previously failed to resolve forward refs at init time
+        if self._needs_rebuild:
+            # Try rebuilding with raise_errors=False to handle any remaining issues gracefully
+            self.model.model_rebuild(
+                _types_namespace=self.raw_function.__globals__, raise_errors=False
+            )
+            # Clear the flag - we only need to rebuild once
+            self._needs_rebuild = False
+
         # Validate using the model
         try:
             validated = self.model.model_validate(values)

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/cli/deploy/_core.py

@@ -246,13 +246,6 @@ async def _run_single_deploy(
             console=app.console, deploy_config=deploy_config, actions=actions
         )
 
-    if trigger_specs := _gather_deployment_trigger_definitions(
-        options.get("triggers"), deploy_config.get("triggers")
-    ):
-        triggers = _initialize_deployment_triggers(deployment_name, trigger_specs)
-    else:
-        triggers = []
-
     # Prefer the originally captured pull_steps (taken before resolution) to
     # preserve unresolved block placeholders in the deployment spec. Only fall
     # back to the config/actions/default if no pull steps were provided.
@@ -307,6 +300,14 @@ async def _run_single_deploy(
     deploy_config["parameter_openapi_schema"] = _parameter_schema
     deploy_config["schedules"] = _schedules
 
+    # This initialises triggers after templating to ensure that jinja variables are resolved
+    if trigger_specs := _gather_deployment_trigger_definitions(
+        options.get("triggers"), deploy_config.get("triggers")
+    ):
+        triggers = _initialize_deployment_triggers(deployment_name, trigger_specs)
+    else:
+        triggers = []
+
     if isinstance(deploy_config.get("concurrency_limit"), dict):
         deploy_config["concurrency_options"] = {
             "collision_strategy": get_from_dict(

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/cli/dev.py

@@ -248,6 +248,13 @@ def build_image(
             "Defaults to the standard Python base image"
         ),
     ),
+    build_arg: list[str] = typer.Option(
+        [],
+        help=(
+            "This will directly pass a --build-arg into the docker build process. "
+            "Can be added to the command line multiple times."
+        ),
+    ),
     dry_run: bool = False,
 ):
     """
@@ -280,6 +287,9 @@ def build_image(
     if flavor:
         command += ["--build-arg", f"BASE_IMAGE=prefect-{flavor}"]
 
+    for arg in build_arg:
+        command += ["--build-arg", arg]
+
     if dry_run:
         print(" ".join(command))
         return

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/concurrency/_asyncio.py

@@ -22,9 +22,11 @@ from prefect.concurrency._leases import amaintain_concurrency_lease
 from prefect.concurrency.context import ConcurrencyContext
 from prefect.logging import get_logger
 from prefect.logging.loggers import get_run_logger
-from prefect.utilities.timeout import timeout_async
 
-from .services import ConcurrencySlotAcquisitionService
+from .services import (
+    ConcurrencySlotAcquisitionService,
+    ConcurrencySlotAcquisitionWithLeaseService,
+)
 
 if TYPE_CHECKING:
     from prefect.client.schemas.objects import ConcurrencyLeaseHolder
@@ -92,57 +94,12 @@ async def aacquire_concurrency_slots_with_lease(
     holder: "Optional[ConcurrencyLeaseHolder]" = None,
     suppress_warnings: bool = False,
 ) -> ConcurrencyLimitWithLeaseResponse:
+    service = ConcurrencySlotAcquisitionWithLeaseService.instance(frozenset(names))
+    future = service.send(
+        (slots, mode, timeout_seconds, max_retries, lease_duration, strict, holder)
+    )
     try:
-        # Use a run logger if available
-        logger = get_run_logger()
-    except Exception:
-        logger = get_logger("concurrency")
-
-    try:
-        with timeout_async(seconds=timeout_seconds):
-            async with get_client() as client:
-                while True:
-                    try:
-                        response = await client.increment_concurrency_slots_with_lease(
-                            names=names,
-                            slots=slots,
-                            mode=mode,
-                            lease_duration=lease_duration,
-                            holder=holder,
-                        )
-                        retval = ConcurrencyLimitWithLeaseResponse.model_validate(
-                            response.json()
-                        )
-                        if not retval.limits:
-                            if strict:
-                                raise ConcurrencySlotAcquisitionError(
-                                    f"Concurrency limits {names!r} must be created before acquiring slots"
-                                )
-                            else:
-                                log_level = (
-                                    logging.DEBUG
-                                    if suppress_warnings
-                                    else logging.WARNING
-                                )
-                                logger.log(
-                                    log_level,
-                                    f"Concurrency limits {names!r} do not exist - skipping acquisition.",
-                                )
-
-                        return retval
-                    except httpx.HTTPStatusError as exc:
-                        if not exc.response.status_code == 423:  # HTTP_423_LOCKED
-                            raise
-
-                        if max_retries is not None and max_retries <= 0:
-                            raise exc
-                        retry_after = float(exc.response.headers["Retry-After"])
-                        logger.debug(
-                            f"Unable to acquire concurrency slot. Retrying in {retry_after} second(s)."
-                        )
-                        await asyncio.sleep(retry_after)
-                        if max_retries is not None:
-                            max_retries -= 1
+        response = await asyncio.wrap_future(future)
     except TimeoutError as timeout:
         raise AcquireConcurrencySlotTimeoutError(
             f"Attempt to acquire concurrency slots timed out after {timeout_seconds} second(s)"
@@ -152,6 +109,28 @@ async def aacquire_concurrency_slots_with_lease(
             f"Unable to acquire concurrency slots on {names!r}"
         ) from exc
 
+    retval = ConcurrencyLimitWithLeaseResponse.model_validate(response.json())
+
+    if not retval.limits:
+        if strict:
+            raise ConcurrencySlotAcquisitionError(
+                f"Concurrency limits {names!r} must be created before acquiring slots"
+            )
+        else:
+            try:
+                # Use a run logger if available
+                task_logger = get_run_logger()
+            except Exception:
+                task_logger = get_logger("concurrency")
+
+            log_level = logging.DEBUG if suppress_warnings else logging.WARNING
+            task_logger.log(
+                log_level,
+                f"Concurrency limits {names!r} do not exist - skipping acquisition.",
+            )
+
+    return retval
+
 
 async def arelease_concurrency_slots(
     names: list[str], slots: int, occupancy_seconds: float

prefect-3.6.3.dev3/src/prefect/concurrency/services.py

@@ -0,0 +1,153 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Literal, Optional
+
+import httpx
+from starlette import status
+from typing_extensions import TypeAlias, Unpack
+
+from prefect._internal.concurrency import logger
+from prefect._internal.concurrency.services import FutureQueueService
+from prefect.client.orchestration import get_client
+from prefect.utilities.timeout import timeout_async
+
+if TYPE_CHECKING:
+    from prefect.client.orchestration import PrefectClient
+    from prefect.client.schemas.objects import ConcurrencyLeaseHolder
+
+_Item: TypeAlias = tuple[
+    int, Literal["concurrency", "rate_limit"], Optional[float], Optional[int]
+]
+
+_ItemWithLease: TypeAlias = tuple[
+    int,
+    Literal["concurrency", "rate_limit"],
+    Optional[float],
+    Optional[int],
+    float,
+    bool,
+    Optional["ConcurrencyLeaseHolder"],
+]
+
+
+class ConcurrencySlotAcquisitionService(
+    FutureQueueService[Unpack[_Item], httpx.Response]
+):
+    def __init__(self, concurrency_limit_names: frozenset[str]):
+        super().__init__(concurrency_limit_names)
+        self._client: PrefectClient
+        self.concurrency_limit_names: list[str] = sorted(list(concurrency_limit_names))
+
+    @asynccontextmanager
+    async def _lifespan(self) -> AsyncGenerator[None, None]:
+        async with get_client() as client:
+            self._client = client
+            yield
+
+    async def acquire(
+        self,
+        slots: int,
+        mode: Literal["concurrency", "rate_limit"],
+        timeout_seconds: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> httpx.Response:
+        with timeout_async(seconds=timeout_seconds):
+            while True:
+                try:
+                    return await self._client.increment_concurrency_slots(
+                        names=self.concurrency_limit_names,
+                        slots=slots,
+                        mode=mode,
+                    )
+                except httpx.HTTPStatusError as exc:
+                    if not exc.response.status_code == status.HTTP_423_LOCKED:
+                        raise
+
+                    if max_retries is not None and max_retries <= 0:
+                        raise exc
+                    retry_after = float(exc.response.headers["Retry-After"])
+                    logger.debug(
+                        f"Unable to acquire concurrency slot. Retrying in {retry_after} second(s)."
+                    )
+                    await asyncio.sleep(retry_after)
+                    if max_retries is not None:
+                        max_retries -= 1
+
+
+class ConcurrencySlotAcquisitionWithLeaseService(
+    FutureQueueService[Unpack[_ItemWithLease], httpx.Response]
+):
+    """A service that acquires concurrency slots with leases.
+
+    This service serializes acquisition attempts for a given set of limit names,
+    preventing thundering herd issues when many tasks try to acquire slots simultaneously.
+    Each unique set of limit names gets its own singleton service instance.
+
+    Args:
+        concurrency_limit_names: A frozenset of concurrency limit names to acquire slots from.
+    """
+
+    def __init__(self, concurrency_limit_names: frozenset[str]):
+        super().__init__(concurrency_limit_names)
+        self._client: PrefectClient
+        self.concurrency_limit_names: list[str] = sorted(list(concurrency_limit_names))
+
+    @asynccontextmanager
+    async def _lifespan(self) -> AsyncGenerator[None, None]:
+        async with get_client() as client:
+            self._client = client
+            yield
+
+    async def acquire(
+        self,
+        slots: int,
+        mode: Literal["concurrency", "rate_limit"],
+        timeout_seconds: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        lease_duration: float = 300,
+        strict: bool = False,
+        holder: Optional["ConcurrencyLeaseHolder"] = None,
+    ) -> httpx.Response:
+        """Acquire concurrency slots with a lease, with retry logic for 423 responses.
+
+        Args:
+            slots: Number of slots to acquire
+            mode: Either "concurrency" or "rate_limit"
+            timeout_seconds: Optional timeout for the entire acquisition attempt
+            max_retries: Maximum number of retries on 423 LOCKED responses
+            lease_duration: Duration of the lease in seconds
+            strict: Whether to raise errors for missing limits
+            holder: Optional holder information for the lease
+
+        Returns:
+            HTTP response from the server
+
+        Raises:
+            httpx.HTTPStatusError: If the server returns an error other than 423 LOCKED
+            TimeoutError: If acquisition times out
+        """
+        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,
+                    )
+                except httpx.HTTPStatusError as exc:
+                    if exc.response.status_code != status.HTTP_423_LOCKED:
+                        raise
+
+                    if max_retries is not None and max_retries <= 0:
+                        raise exc
+
+                    retry_after = float(exc.response.headers["Retry-After"])
+                    logger.debug(
+                        f"Unable to acquire concurrency slot with lease for {self.concurrency_limit_names}. Retrying in {retry_after} second(s)."
+                    )
+                    await asyncio.sleep(retry_after)
+                    if max_retries is not None:
+                        max_retries -= 1

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/context.py

@@ -776,10 +776,23 @@ def get_run_context() -> Union[FlowRunContext, TaskRunContext]:
         RuntimeError: If called outside of a flow or task run.
     """
     task_run_ctx = TaskRunContext.get()
+    flow_run_ctx = FlowRunContext.get()
+
+    # When both contexts exist, determine which represents the currently executing code.
+    # If the flow_run_id from the flow context differs from the task's flow_run_id,
+    # we're in a subflow running inside a task, so prefer the flow context.
+    # Otherwise, we're in a regular task within the flow, so prefer the task context.
+    if task_run_ctx and flow_run_ctx:
+        if (
+            flow_run_ctx.flow_run
+            and flow_run_ctx.flow_run.id != task_run_ctx.task_run.flow_run_id
+        ):
+            return flow_run_ctx
+        return task_run_ctx
+
     if task_run_ctx:
         return task_run_ctx
 
-    flow_run_ctx = FlowRunContext.get()
     if flow_run_ctx:
         return flow_run_ctx
 

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/flow_runs.py

@@ -249,9 +249,8 @@ async def _in_process_pause(
     if TYPE_CHECKING:
         assert client is not None
 
-    if TaskRunContext.get():
-        raise RuntimeError("Cannot pause task runs.")
-
+    # Get the flow run context - this works even when called from within a task
+    # since both FlowRunContext and TaskRunContext are independently active
     context = FlowRunContext.get()
     if not context:
         raise RuntimeError("Flow runs can only be paused from within a flow run.")

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/logging/loggers.py

@@ -289,7 +289,29 @@ def print_as_log(*args: Any, **kwargs: Any) -> None:
     """
     from prefect.context import FlowRunContext, TaskRunContext
 
-    context = TaskRunContext.get() or FlowRunContext.get()
+    # When both contexts exist, we need to determine which one represents the
+    # currently executing code:
+    # - If we're in a subflow that's wrapped by a task, FlowRunContext represents
+    #   the subflow and should take precedence
+    # - If we're in a regular task, TaskRunContext represents the task
+    #
+    # We can distinguish by checking flow_run_id:
+    # - Regular task: flow_ctx.flow_run.id == task_ctx.task_run.flow_run_id
+    # - Subflow in task: flow_ctx.flow_run.id != task_ctx.task_run.flow_run_id
+    flow_ctx = FlowRunContext.get()
+    task_ctx = TaskRunContext.get()
+
+    if flow_ctx and task_ctx:
+        # If the flow_run_id from the flow context differs from the task's flow_run_id,
+        # we're in a subflow that's running inside a task, so prefer the flow context
+        if flow_ctx.flow_run and flow_ctx.flow_run.id != task_ctx.task_run.flow_run_id:
+            context = flow_ctx
+        else:
+            # We're in a regular task within the flow
+            context = task_ctx
+    else:
+        context = flow_ctx or task_ctx
+
     if (
         not context
         or not context.log_prints

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/server/api/concurrency_limits_v2.py

@@ -25,12 +25,6 @@ router: PrefectRouter = PrefectRouter(
     prefix="/v2/concurrency_limits", tags=["Concurrency Limits V2"]
 )
 
-# Max retry delay (in seconds) for non-tag concurrency limits when slot occupancy is high.
-# Tag-based limits use the legacy tag_concurrency_slot_wait_seconds setting (default 30s)
-# to restore V1 behavior. Non-tag limits use this higher value to allow more uniform queues
-# to check more frequently while still preventing excessive delays from long-running tasks.
-DEFAULT_SLOT_WAIT_SECONDS = 30.0
-
 
 @router.post("/", status_code=status.HTTP_201_CREATED)
 async def create_concurrency_limit_v2(
@@ -234,8 +228,8 @@ async def _generate_concurrency_locked_response(
 
     - Tag-based limits (name starts with "tag:"): Capped at tag_concurrency_slot_wait_seconds
       (default 30s) to restore V1 behavior that users relied on
-    - Other limits: Capped at DEFAULT_SLOT_WAIT_SECONDS (30s) to allow more uniform queues
-      while still preventing astronomical delays
+    - Other limits: Capped at maximum_concurrency_slot_wait_seconds (default 30s) to allow
+      more uniform queues while still preventing astronomical delays
 
     Low average occupancies are always respected (e.g., 2s stays 2s, not forced higher).
     Limits with slot decay use the decay rate directly without capping.
@@ -265,7 +259,7 @@ async def _generate_concurrency_locked_response(
         max_wait = (
             settings.server.tasks.tag_concurrency_slot_wait_seconds
             if blocking_limit.name.startswith("tag:")
-            else DEFAULT_SLOT_WAIT_SECONDS
+            else settings.server.concurrency.maximum_concurrency_slot_wait_seconds
         )
         wait_time_per_slot = min(blocking_limit.avg_slot_occupancy_seconds, max_wait)
     else:

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/server/models/concurrency_limits_v2.py

@@ -7,11 +7,13 @@ from sqlalchemy.sql.elements import ColumnElement
 
 import prefect.server.schemas as schemas
 from prefect.server.database import PrefectDBInterface, db_injector, orm_models
+from prefect.server.utilities.database import greatest, least
+from prefect.settings import get_current_settings
 
 
 def active_slots_after_decay(db: PrefectDBInterface) -> ColumnElement[float]:
     # Active slots will decay at a rate of `slot_decay_per_second` per second.
-    return sa.func.greatest(
+    return greatest(
         0,
         db.ConcurrencyLimitV2.active_slots
         - sa.func.floor(
@@ -22,28 +24,53 @@ def active_slots_after_decay(db: PrefectDBInterface) -> ColumnElement[float]:
 
 
 def denied_slots_after_decay(db: PrefectDBInterface) -> ColumnElement[float]:
-    # Denied slots decay at a rate of `slot_decay_per_second` per second if it's
-    # greater than 0, otherwise it decays at a rate of `avg_slot_occupancy_seconds`.
-    # The combination of `denied_slots` and `slot_decay_per_second` /
-    # `avg_slot_occupancy_seconds` is used to by the API to give a best guess at
-    # when slots will be available again.
-    return sa.func.greatest(
+    """
+    Calculate denied_slots after applying decay.
+
+    Denied slots decay at a rate of `slot_decay_per_second` per second if it's
+    greater than 0 (rate limits), otherwise for concurrency limits it decays at
+    a rate based on clamped `avg_slot_occupancy_seconds`.
+
+    The clamping matches the retry-after calculation to prevent denied_slots from
+    accumulating when clients retry faster than the unclamped decay rate.
+    """
+    settings = get_current_settings()
+
+    # Determine max_wait based on limit name prefix
+    max_wait_for_limit = sa.case(
+        (
+            db.ConcurrencyLimitV2.name.like("tag:%"),
+            sa.literal(settings.server.tasks.tag_concurrency_slot_wait_seconds),
+        ),
+        else_=sa.literal(
+            settings.server.concurrency.maximum_concurrency_slot_wait_seconds
+        ),
+    )
+
+    # Clamp avg_slot_occupancy_seconds with minimum bound to prevent division by zero
+    clamped_occupancy = greatest(
+        sa.literal(MINIMUM_OCCUPANCY_SECONDS_PER_SLOT),
+        least(
+            sa.cast(db.ConcurrencyLimitV2.avg_slot_occupancy_seconds, sa.Float),
+            max_wait_for_limit,
+        ),
+    )
+
+    # Calculate decay rate: use slot_decay_per_second for rate limits,
+    # use 1/clamped_occupancy for concurrency limits
+    decay_rate_per_second = sa.case(
+        (
+            db.ConcurrencyLimitV2.slot_decay_per_second > 0.0,
+            db.ConcurrencyLimitV2.slot_decay_per_second,  # Rate limits - no clamping
+        ),
+        else_=(1.0 / clamped_occupancy),  # Concurrency limits - use clamped value
+    )
+
+    return greatest(
         0,
         db.ConcurrencyLimitV2.denied_slots
         - sa.func.floor(
-            sa.case(
-                (
-                    db.ConcurrencyLimitV2.slot_decay_per_second > 0.0,
-                    db.ConcurrencyLimitV2.slot_decay_per_second,
-                ),
-                else_=(
-                    1.0
-                    / sa.cast(
-                        db.ConcurrencyLimitV2.avg_slot_occupancy_seconds,
-                        sa.Float,
-                    )
-                ),
-            )
+            decay_rate_per_second
             * sa.func.date_diff_seconds(db.ConcurrencyLimitV2.updated)
         ),
     )

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/server/utilities/database.py

@@ -724,6 +724,20 @@ def sqlite_greatest_as_max(
     return compiler.process(sa.func.max(*element.clauses), **kwargs)
 
 
+class least(functions.ReturnTypeFromArgs[T]):
+    inherit_cache: bool = True
+
+
+@compiles(least, "sqlite")
+def sqlite_least_as_min(
+    element: least[Any], compiler: SQLCompiler, **kwargs: Any
+) -> str:
+    # SQLite doesn't have LEAST(), use MIN() instead.
+    # Note: Like MAX(), SQLite MIN() returns NULL if _any_ clause is NULL,
+    # whereas PostgreSQL LEAST() only returns NULL if _all_ clauses are NULL.
+    return compiler.process(sa.func.min(*element.clauses), **kwargs)
+
+
 def get_dialect(obj: Union[str, Session, sa.Engine]) -> type[sa.Dialect]:
     """
     Get the dialect of a session, engine, or connection url.

{prefect-3.6.3.dev1 → prefect-3.6.3.dev3}/src/prefect/settings/models/server/concurrency.py

@@ -22,3 +22,9 @@ class ServerConcurrencySettings(PrefectBaseSettings):
         le=3600.0,  # Maximum 1 hour
         description="Initial duration for deployment concurrency lease in seconds.",
     )
+
+    maximum_concurrency_slot_wait_seconds: float = Field(
+        default=30,
+        ge=0,
+        description="The maximum number of seconds to wait before retrying when a concurrency slot cannot be acquired.",
+    )