prefect-client 3.7.1.dev8__tar.gz → 3.7.2.dev1__tar.gz

{prefect_client-3.7.1.dev8 → prefect_client-3.7.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.7.1.dev8
+Version: 3.7.2.dev1
 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.dev8 → prefect_client-3.7.2.dev1}/src/prefect/AGENTS.md

@@ -23,7 +23,7 @@ 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.

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

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.2.dev1"
+__build_date__ = "2026-05-18 09:19:56.215908+00:00"
+__git_commit__ = "25ff793e11f525e8f7043525165e0ded57abaea9"
+__dirty__ = False

{prefect_client-3.7.1.dev8 → prefect_client-3.7.2.dev1}/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.dev8 → prefect_client-3.7.2.dev1}/src/prefect/runner/_scheduled_run_poller.py

@@ -182,18 +182,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.dev8 → prefect_client-3.7.2.dev1}/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.dev8 → prefect_client-3.7.2.dev1}/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.dev8/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.7.1.dev8"
-__build_date__ = "2026-05-14 09:02:56.534802+00:00"
-__git_commit__ = "7057b0df499b140407d3abf264538c21444724ce"
-__dirty__ = False