prefect-client 3.7.1.dev9__tar.gz → 3.7.2.dev2__tar.gz

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.7.1.dev9
+Version: 3.7.2.dev2
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/AGENTS.md

@@ -23,13 +23,14 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 - **Engine ordering matters.** The engines apply features (retries, caching, result persistence, transactions) in a specific order. Changing the order or forgetting a feature in one engine path is the most common source of breakage.
 - **Set run metadata before state transitions.** Any run attribute that event subscribers observe at the moment of a state transition (e.g., custom `flow_run_name`) must be persisted to the server *before* `set_state()` is called for that transition. Metadata set after the call appears stale to subscribers of that state event.
 - **Sync and async must stay in sync.** Both `flow_engine.py` and `task_engine.py` have sync and async paths. Any behavior change must be applied to both.
-- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences between whenever 0.7.x–0.9.x and ≥ 0.10.0. The `_WHENEVER_NEW_API` flag (True when whenever ≥ 0.10.0) guards version-specific code. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Violations will silently break on whichever whenever version the helpers weren't written for.
+- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences between whenever 0.7.x–0.9.x and ≥ 0.10.0. The `_WHENEVER_NEW_API` flag (True when whenever ≥ 0.10.0) guards version-specific code. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Avoid no-argument `datetime.datetime.now()` because it returns a tz-naive datetime that raises `TypeError` when compared to the tz-aware datetimes produced by `now()`. Explicitly timezone-aware stdlib calls such as `datetime.now(ZoneInfo("UTC"))` are allowed when needed to preserve timezone information. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Violations will silently break on whichever whenever version the helpers weren't written for.
 - **Flow and task engines advance state differently.** The flow engine makes blocking API calls to the server to propose and advance states. The task engine emits `prefect.task_run.*` events (delivered via WebSockets) but advances state locally through `set_state` calls with polling/backoff — do not assume the two engines work the same way.
 - **Flow state transitions go through the server.** The flow engine proposes states to the server, which accepts or rejects them via orchestration rules. The task engine, by contrast, manages state transitions locally via `set_state` and emits `prefect.task_run.*` events — it does not propose states to the server.
 - **`ProcessPoolTaskRunner` requires picklable data across subprocess boundaries.** `PrefectFuture` objects are not picklable and cannot be passed to worker subprocesses. Any `wait_for` futures must be waited on in the parent process and converted to `State` objects before submission. The subprocess task engine handles `State` objects via `resolve_to_final_result`, which raises `UpstreamTaskError` for non-completed upstreams.
 - **`ProcessPoolTaskRunner` instances may be deserialized without `__init__` running.** When a runner is pickled and restored in a subprocess, `__init__` is not called, so instance attributes set there may be absent. Access any such attribute via `getattr(self, "_attr", default)` rather than `self._attr` directly — both in the property getter and in `duplicate()`. The `subprocess_message_processor_factories` property demonstrates the required pattern.
 - **`ThreadPoolTaskRunner` is cloudpickled when a flow run is dispatched to a subprocess.** `threading.Lock` and other non-picklable thread primitives must be dropped in `__getstate__` and rebuilt in `__setstate__`. Any new instance state added to this class must be evaluated for picklability.
 - **Nested task submissions on a bounded `ThreadPoolTaskRunner` can deadlock.** When a worker task submits children and blocks on `.result()` while all `max_workers` threads are busy, the pool starves. `_warn_if_nested_submit_would_deadlock` detects this and emits a one-time warning — preserve this detection when changing pool management.
+- **Result storage resolves through three tiers, potentially making an API call.** `get_default_result_storage()` checks: (1) `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting, (2) server-configured default block (API call to the server's Configuration store), (3) local storage path. The API call is silently suppressed on any HTTP error. Engines use `_get_default_persist_result()` — not `should_persist_result()` — at context setup time to auto-enable persistence when a server default block is configured. Do not swap `_get_default_persist_result()` back to `should_persist_result()` in engine initialization paths; `should_persist_result()` does not consult the server default.
 - **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
 - **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
 

prefect_client-3.7.2.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.2.dev2"
+__build_date__ = "2026-05-19 09:17:54.056516+00:00"
+__git_commit__ = "68244724cf7a168f14f81bdf032689c912a404de"
+__dirty__ = False

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/blocks/notifications.py

@@ -57,7 +57,15 @@ class AbstractAppriseNotificationBlock(NotificationBlock, ABC):
         body: str,
         subject: str | None = None,
     ) -> None:
-        with LogEavesdropper("apprise", level=logging.DEBUG) as eavesdropper:
+        apprise_logger = logging.getLogger("apprise")
+        root_logger = logging.getLogger()
+
+        if apprise_logger.level == logging.NOTSET:
+            log_level = root_logger.getEffectiveLevel()
+        else:
+            log_level = max(apprise_logger.level, root_logger.getEffectiveLevel())
+
+        with LogEavesdropper("apprise", level=log_level) as eavesdropper:
             result = await self._apprise_client.async_notify(  # pyright: ignore[reportUnknownMemberType] incomplete type hints in apprise
                 body=body,
                 title=subject or "",
@@ -72,7 +80,15 @@ class AbstractAppriseNotificationBlock(NotificationBlock, ABC):
         body: str,
         subject: str | None = None,
     ) -> None:
-        with LogEavesdropper("apprise", level=logging.DEBUG) as eavesdropper:
+        apprise_logger = logging.getLogger("apprise")
+        root_logger = logging.getLogger()
+
+        if apprise_logger.level == logging.NOTSET:
+            log_level = root_logger.getEffectiveLevel()
+        else:
+            log_level = max(apprise_logger.level, root_logger.getEffectiveLevel())
+
+        with LogEavesdropper("apprise", level=log_level) as eavesdropper:
             result = self._apprise_client.notify(  # pyright: ignore[reportUnknownMemberType] incomplete type hints in apprise
                 body=body,
                 title=subject or "",

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/bundles/__init__.py

@@ -593,8 +593,23 @@ def execute_bundle_in_subprocess(
 
     # Install dependencies if necessary
     if dependencies := bundle.get("dependencies"):
+        dep_lines = [line.strip() for line in dependencies.split("\n") if line.strip()]
+        validated_deps: list[str] = []
+        for dep_line in dep_lines:
+            if dep_line.startswith("-"):
+                raise ValueError(
+                    f"Invalid dependency (command-line flags are not allowed): {dep_line!r}"
+                )
+            try:
+                Requirement(dep_line)
+            except InvalidRequirement as e:
+                raise ValueError(
+                    f"Invalid PEP 508 dependency specifier: {dep_line!r}"
+                ) from e
+            validated_deps.append(dep_line)
+
         subprocess.check_call(
-            [_get_uv_path(), "pip", "install", *dependencies.split("\n")],
+            [_get_uv_path(), "pip", "install", *validated_deps],
             # Copy the current environment to ensure we install into the correct venv
             env=os.environ,
         )

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/flow_engine.py

@@ -909,10 +909,15 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
         This method attempts to load an existing flow run for a subflow task
         run, if appropriate.
 
-        If the parent task run is in a final but not COMPLETED state, and not
-        being rerun, then we attempt to load an existing flow run instead of
-        creating a new one. This will prevent the engine from running the
-        subflow again.
+        If the parent task run is in a final state, we return the existing
+        subflow run to avoid re-execution (unless the parent is being rerun
+        and the subflow did not complete, in which case a fresh run is
+        desired).
+
+        If the parent task run is in a non-final state (e.g. still Running
+        after a process restart), we also look for an existing subflow run
+        to reattach to, preventing duplicate subflow runs from being created
+        under the same parent task run.
 
         If no existing flow run is found, or if the subflow should be rerun,
         then no flow run is returned.
@@ -926,27 +931,32 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             else False
         )
 
-        # if the parent task run is in a final but not completed state, and
-        # not rerunning, then retrieve the most recent flow run instead of
-        # creating a new one. This effectively loads a cached flow run for
-        # situations where we are confident the flow should not be run
-        # again.
         assert isinstance(parent_task_run.state, State)
-        if parent_task_run.state.is_final() and not (
-            rerunning and not parent_task_run.state.is_completed()
+
+        # If the user explicitly triggered a re-run and the subflow did not
+        # complete, allow a fresh subflow to be created.
+        if (
+            parent_task_run.state.is_final()
+            and rerunning
+            and not parent_task_run.state.is_completed()
         ):
-            # return the most recent flow run, if it exists
-            flow_runs = client.read_flow_runs(
-                flow_run_filter=FlowRunFilter(
-                    parent_task_run_id={"any_": [parent_task_run.id]}
-                ),
-                sort=FlowRunSort.EXPECTED_START_TIME_ASC,
-                limit=1,
-            )
-            if flow_runs:
-                loaded_flow_run = flow_runs[-1]
+            return None
+
+        # Look for an existing subflow run attached to this parent task run.
+        flow_runs = client.read_flow_runs(
+            flow_run_filter=FlowRunFilter(
+                parent_task_run_id={"any_": [parent_task_run.id]}
+            ),
+            sort=FlowRunSort.EXPECTED_START_TIME_DESC,
+            limit=1,
+        )
+        if flow_runs:
+            loaded_flow_run = flow_runs[0]
+            # When the parent task run is final the subflow has already
+            # finished; cache the result so the engine skips re-execution.
+            if parent_task_run.state.is_final():
                 self._return_value = loaded_flow_run.state
-                return loaded_flow_run
+            return loaded_flow_run
 
     def create_flow_run(self, client: SyncPrefectClient) -> FlowRun:
         flow_run_ctx = FlowRunContext.get()
@@ -1594,10 +1604,15 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
         This method attempts to load an existing flow run for a subflow task
         run, if appropriate.
 
-        If the parent task run is in a final but not COMPLETED state, and not
-        being rerun, then we attempt to load an existing flow run instead of
-        creating a new one. This will prevent the engine from running the
-        subflow again.
+        If the parent task run is in a final state, we return the existing
+        subflow run to avoid re-execution (unless the parent is being rerun
+        and the subflow did not complete, in which case a fresh run is
+        desired).
+
+        If the parent task run is in a non-final state (e.g. still Running
+        after a process restart), we also look for an existing subflow run
+        to reattach to, preventing duplicate subflow runs from being created
+        under the same parent task run.
 
         If no existing flow run is found, or if the subflow should be rerun,
         then no flow run is returned.
@@ -1611,27 +1626,32 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             else False
         )
 
-        # if the parent task run is in a final but not completed state, and
-        # not rerunning, then retrieve the most recent flow run instead of
-        # creating a new one. This effectively loads a cached flow run for
-        # situations where we are confident the flow should not be run
-        # again.
         assert isinstance(parent_task_run.state, State)
-        if parent_task_run.state.is_final() and not (
-            rerunning and not parent_task_run.state.is_completed()
+
+        # If the user explicitly triggered a re-run and the subflow did not
+        # complete, allow a fresh subflow to be created.
+        if (
+            parent_task_run.state.is_final()
+            and rerunning
+            and not parent_task_run.state.is_completed()
         ):
-            # return the most recent flow run, if it exists
-            flow_runs = await client.read_flow_runs(
-                flow_run_filter=FlowRunFilter(
-                    parent_task_run_id={"any_": [parent_task_run.id]}
-                ),
-                sort=FlowRunSort.EXPECTED_START_TIME_ASC,
-                limit=1,
-            )
-            if flow_runs:
-                loaded_flow_run = flow_runs[-1]
+            return None
+
+        # Look for an existing subflow run attached to this parent task run.
+        flow_runs = await client.read_flow_runs(
+            flow_run_filter=FlowRunFilter(
+                parent_task_run_id={"any_": [parent_task_run.id]}
+            ),
+            sort=FlowRunSort.EXPECTED_START_TIME_DESC,
+            limit=1,
+        )
+        if flow_runs:
+            loaded_flow_run = flow_runs[0]
+            # When the parent task run is final the subflow has already
+            # finished; cache the result so the engine skips re-execution.
+            if parent_task_run.state.is_final():
                 self._return_value = loaded_flow_run.state
-                return loaded_flow_run
+            return loaded_flow_run
 
     async def create_flow_run(self, client: PrefectClient) -> FlowRun:
         flow_run_ctx = FlowRunContext.get()

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/runner/_scheduled_run_poller.py

@@ -126,7 +126,6 @@ class ScheduledRunPoller:
             ),
         )
 
-        submitted_ids: set[UUID] = set()
         for flow_run in submittable_flow_runs:
             if flow_run.id in self._submitting_flow_run_ids:
                 continue
@@ -135,13 +134,12 @@ class ScheduledRunPoller:
             except anyio.WouldBlock:
                 break  # sorted: no earlier run fits
             self._submitting_flow_run_ids.add(flow_run.id)
-            submitted_ids.add(flow_run.id)
             task_group.start_soon(self._submit_run, flow_run, task_group, slot_token)
 
         skipped_count = sum(
             1
             for r in submittable_flow_runs
-            if r.id not in self._submitting_flow_run_ids and r.id not in submitted_ids
+            if r.id not in self._submitting_flow_run_ids
         )
         if skipped_count > 0:
             self._logger.info("%d scheduled runs skipped (at capacity)", skipped_count)
@@ -182,18 +180,15 @@ class ScheduledRunPoller:
             pull_interval = getattr(storage, "pull_interval", None)
             if storage and isinstance(pull_interval, (int, float)) and pull_interval:
                 last_adhoc_pull = getattr(storage, "last_adhoc_pull", None)
-                if (
-                    last_adhoc_pull is None
-                    or last_adhoc_pull
-                    < datetime.datetime.now()
-                    - datetime.timedelta(seconds=storage.pull_interval)
-                ):
+                if last_adhoc_pull is None or last_adhoc_pull < now(
+                    "UTC"
+                ) - datetime.timedelta(seconds=storage.pull_interval):
                     self._logger.debug(
                         "Performing adhoc pull of code for flow run %s",
                         flow_run.id,
                     )
                     await storage.pull_code()
-                    storage.last_adhoc_pull = datetime.datetime.now()
+                    storage.last_adhoc_pull = now("UTC")
 
             executor = FlowRunExecutor(
                 flow_run=flow_run,

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/runner/runner.py

@@ -129,6 +129,7 @@ from prefect.settings import (
 from prefect.states import (
     AwaitingRetry,
 )
+from prefect.types._datetime import now
 from prefect.types.entrypoint import EntrypointType
 from prefect.utilities.annotations import NotSet
 from prefect.utilities.asyncutils import (
@@ -1051,19 +1052,16 @@ class Runner:
             # adhoc pull hasn't been performed in the last pull_interval
             # TODO: Explore integrating this behavior with global concurrency.
             last_adhoc_pull = getattr(storage, "last_adhoc_pull", None)
-            if (
-                last_adhoc_pull is None
-                or last_adhoc_pull
-                < datetime.datetime.now()
-                - datetime.timedelta(seconds=storage.pull_interval)
-            ):
+            if last_adhoc_pull is None or last_adhoc_pull < now(
+                "UTC"
+            ) - datetime.timedelta(seconds=storage.pull_interval):
                 self._logger.debug(
                     "Performing adhoc pull of code for flow run %s with storage %r",
                     flow_run.id,
                     storage,
                 )
                 await storage.pull_code()
-                setattr(storage, "last_adhoc_pull", datetime.datetime.now())
+                setattr(storage, "last_adhoc_pull", now("UTC"))
 
         handed_off = False
 

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/types/_datetime.py

@@ -13,6 +13,8 @@ from pydantic import AfterValidator
 from typing_extensions import TypeAlias
 
 if sys.version_info >= (3, 13):
+    from pydantic import GetCoreSchemaHandler
+    from pydantic_core import core_schema as _core_schema
     from whenever import DateTimeDelta
     from whenever import ZonedDateTime as _ZDTProbe
 
@@ -21,7 +23,34 @@ if sys.version_info >= (3, 13):
     _WHENEVER_NEW_API: bool = hasattr(_ZDTProbe, "to_stdlib")
     del _ZDTProbe
 
-    DateTime: TypeAlias = datetime.datetime
+    class _DateTime(datetime.datetime):
+        """`datetime.datetime` with a Pydantic schema that coerces naive to UTC.
+
+        On Python <= 3.12 the pendulum-backed `PydanticDateTime` enforces
+        tz-awareness during validation. This class is the 3.13+ equivalent so
+        any field typed as `DateTime` gets the same guarantee instead of
+        deferring to ad-hoc per-field validators (see #21949). Coercion reuses
+        the existing `create_datetime_instance` helper rather than open-coding
+        the naive→UTC check.
+
+        Runtime construction (`DateTime(2020, 1, 1)`) preserves the underlying
+        `datetime.datetime` semantics — naive in, naive out. The coercion
+        applies during Pydantic validation, which is where the silent
+        server-side drop originated.
+        """
+
+        @classmethod
+        def __get_pydantic_core_schema__(
+            cls,
+            source_type: Any,
+            handler: GetCoreSchemaHandler,
+        ) -> _core_schema.CoreSchema:
+            return _core_schema.no_info_after_validator_function(
+                create_datetime_instance,
+                handler(datetime.datetime),
+            )
+
+    DateTime: TypeAlias = _DateTime
     Date: TypeAlias = datetime.date
     Duration: TypeAlias = datetime.timedelta
     if _WHENEVER_NEW_API:

{prefect_client-3.7.1.dev9 → prefect_client-3.7.2.dev2}/src/prefect/workers/_worker_channel/_sync.py

@@ -16,7 +16,7 @@ from prefect.client.base import ServerType
 from prefect.client.orchestration import PrefectClient
 from prefect.client.schemas.actions import WorkPoolCreate, WorkPoolUpdate
 from prefect.client.schemas.objects import WorkerMetadata, WorkPool
-from prefect.exceptions import ObjectNotFound
+from prefect.exceptions import ObjectAlreadyExists, ObjectNotFound
 from prefect.workers._cleanup import WorkerCleanupExecutor
 from prefect.workers._worker_channel._protocol import WorkerChannelProtocolHandler
 from prefect.workers._worker_channel._state import (
@@ -310,8 +310,21 @@ class WorkPoolWorkerChannel:
                 if self.base_job_template is not None:
                     wp.base_job_template = self.base_job_template
 
-                work_pool = await self._client.create_work_pool(work_pool=wp)
-                self._logger.info(f"Work pool {self.work_pool_name!r} created.")
+                try:
+                    work_pool = await self._client.create_work_pool(work_pool=wp)
+                    self._logger.info(f"Work pool {self.work_pool_name!r} created.")
+                except ObjectAlreadyExists:
+                    # Another worker created the pool between our read and
+                    # create. Re-read so we can continue with the existing
+                    # pool rather than failing setup.
+                    self._logger.debug(
+                        "Work pool %r was created concurrently by another "
+                        "worker; re-reading.",
+                        self.work_pool_name,
+                    )
+                    work_pool = await self._client.read_work_pool(
+                        work_pool_name=self.work_pool_name
+                    )
             else:
                 self._logger.warning(f"Work pool {self.work_pool_name!r} not found!")
                 if self.base_job_template is not None:

prefect_client-3.7.1.dev9/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.7.1.dev9"
-__build_date__ = "2026-05-15 09:11:51.705996+00:00"
-__git_commit__ = "7b3d832873540f6c92ce44e75089070d46502dbb"
-__dirty__ = False