prefect 3.6.28.dev2__tar.gz → 3.6.28.dev4__tar.gz

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/.gitignore

@@ -97,3 +97,4 @@ CLAUDE.md
 
 # Local planning artifacts
 .planning/
+repros/

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/PKG-INFO

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

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/AGENTS.md

@@ -21,10 +21,12 @@ 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.
 - **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 `_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 `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.
+- **`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.
 
 ## Logging
 

prefect-3.6.28.dev4/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.28.dev4"
+__build_date__ = "2026-04-22 08:43:46.963125+00:00"
+__git_commit__ = "093cd05d7fae5c8f8bc2f93f5fae8bbdb2eb97dd"
+__dirty__ = False

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/_experimental/bundles/__init__.py

@@ -23,7 +23,10 @@ from typing_extensions import Literal, NotRequired, TypeAlias
 
 import anyio
 import cloudpickle  # pyright: ignore[reportMissingTypeStubs]
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.version import Version
 
+import prefect
 from prefect._internal.control_listener import configure_from_env
 from prefect.client.schemas.objects import FlowRun
 from prefect.context import SettingsContext, get_settings_context, serialize_context
@@ -616,6 +619,52 @@ def execute_bundle_in_subprocess(
     return process
 
 
+def _pin_prefect_in_bundle_step_requires(requires: list[str]) -> list[str]:
+    """
+    Ensure the `uv run --with` requirements for an outer bundle-step process
+    include the exact current publishable Prefect version.
+
+    The outer bundle-step process imports Prefect before the bundle's frozen
+    dependencies are installed, so transitive constraints like
+    `prefect>=3.6.24` from integration packages can otherwise resolve an
+    older stable Prefect even when the bundle was built against a newer
+    version. Pinning `prefect=={prefect.__version__}` keeps the outer
+    process on the same version the bundle was built with.
+
+    - Rewrites any existing `prefect` (or `prefect[...]`) requirement to the
+      exact current version, preserving extras and markers.
+    - Appends `prefect=={prefect.__version__}` if no Prefect requirement is
+      present.
+    - Returns the requirements unchanged for local/unpublishable versions,
+      matching the behavior of `prefect._internal.installation`.
+    """
+    version = Version(prefect.__version__)
+    if version.local:
+        return requires
+
+    pinned_version = prefect.__version__
+    updated: list[str] = []
+    found_prefect = False
+    for requirement in requires:
+        try:
+            parsed = Requirement(requirement)
+        except InvalidRequirement:
+            updated.append(requirement)
+            continue
+        if parsed.name.lower() != "prefect":
+            updated.append(requirement)
+            continue
+        found_prefect = True
+        extras = f"[{','.join(sorted(parsed.extras))}]" if parsed.extras else ""
+        marker = f" ; {parsed.marker}" if parsed.marker else ""
+        updated.append(f"prefect{extras}=={pinned_version}{marker}")
+
+    if not found_prefect:
+        updated.append(f"prefect=={pinned_version}")
+
+    return updated
+
+
 def convert_step_to_command(
     step: dict[str, Any], key: str, quiet: bool = False
 ) -> list[str]:
@@ -655,6 +704,13 @@ def convert_step_to_command(
         if quiet:
             command.append("--quiet")
 
+        # Pin the outer bundle-step process to the current publishable Prefect
+        # version so integration `requires` like `prefect-aws>=0.5.5` cannot
+        # resolve an older stable Prefect via transitive `prefect>=...`
+        # constraints before the bundle's frozen dependencies are applied.
+        if requires:
+            requires = _pin_prefect_in_bundle_step_requires(requires)
+
         # Add the `--with` argument to handle dependencies for running the step
         if requires:
             command.extend(["--with", ",".join(requires)])

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/_experimental/bundles/execute.py

@@ -39,6 +39,7 @@ async def execute_bundle(bundle: dict) -> None:
                 control_channel=ctx.control_channel,
             ),
             resolve_flow=resolve_flow,
+            propose_submitting=False,
         )
         await executor.submit()
 

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/_internal/compatibility/deprecated.py

@@ -91,8 +91,14 @@ def generate_deprecation_message(
         if sys.version_info >= (3, 13):
             from whenever import PlainDateTime
 
+            _pdt_from_dt = (
+                PlainDateTime
+                if hasattr(PlainDateTime, "to_stdlib")
+                else PlainDateTime.from_py_datetime
+            )
+            _dt = _pdt_from_dt(start_date).add(months=6)
             end_date = (
-                PlainDateTime.from_py_datetime(start_date).add(months=6).py_datetime()
+                _dt.to_stdlib() if hasattr(_dt, "to_stdlib") else _dt.py_datetime()
             )
         else:
             import pendulum

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/_result_records.py

@@ -17,6 +17,7 @@ from pydantic import (
     BaseModel,
     Field,
     ValidationError,
+    field_validator,
     model_validator,
 )
 
@@ -24,8 +25,9 @@ import prefect
 from prefect.exceptions import (
     SerializationError,
 )
-from prefect.serializers import PickleSerializer, Serializer
+from prefect.serializers import PickleSerializer, Serializer, UnknownSerializer
 from prefect.types import DateTime
+from prefect.utilities.dispatch import lookup_type
 
 if TYPE_CHECKING:
     pass
@@ -49,6 +51,19 @@ class ResultRecordMetadata(BaseModel):
     prefect_version: str = Field(default=prefect.__version__)
     storage_block_id: Optional[uuid.UUID] = Field(default=None)
 
+    @field_validator("serializer", mode="before")
+    @classmethod
+    def _tolerate_unknown_serializer(
+        cls, value: Serializer | dict[str, Any] | Any
+    ) -> Serializer | dict[str, Any] | Any:
+        if isinstance(value, dict) and "type" in value:
+            try:
+                lookup_type(Serializer, dispatch_key=value["type"])
+            except KeyError:
+                return UnknownSerializer.model_construct(**value)
+            return Serializer(**value)
+        return value
+
     def dump_bytes(self) -> bytes:
         """
         Serialize the metadata to bytes.

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/client/_version_checking.py

@@ -142,7 +142,7 @@ async def check_server_version(
     if auth_string:
         token = base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")
         headers["Authorization"] = f"Basic {token}"
-    elif api_key:
+    elif api_key and "Authorization" not in headers:
         headers["Authorization"] = f"Bearer {api_key}"
     if headers:
         httpx_kwargs["headers"] = headers

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/runner/AGENTS.md

@@ -96,7 +96,11 @@ Each execution mode has a ProcessStarter implementation. To add a new execution
 
 `ScheduledRunPoller` now calls `propose_pending` (Scheduled → Pending) before handing off to `FlowRunExecutor`. `FlowRunExecutor` then calls `propose_submitting` (Pending → Submitting sub-state) as step 1 of its lifecycle **when `propose_submitting=True` (the default)**. These are two separate transitions — do not collapse them. The split exists so automations listening for the Pending state fire correctly before the executor begins.
 
-**Exception: `prefect flow-run execute` CLI path sets `propose_submitting=False`** via `FlowRunExecutorContext.create_executor(propose_submitting=False)`. The CLI is invoked by a worker that has already advanced the flow run past the Pending state, so proposing Submitting again would be wrong. The cancelling precheck (step 1a) still runs unconditionally even when `propose_submitting=False`.
+**Two callers set `propose_submitting=False`** via `FlowRunExecutorContext.create_executor(propose_submitting=False)` — both have already advanced the flow run past the Pending state, so proposing Submitting again would be wrong:
+- `prefect flow-run execute` CLI path (invoked by a worker)
+- `execute_bundle()` in `prefect._experimental.bundles.execute` (invoked by bundle dispatch)
+
+The cancelling precheck (step 1a) still runs unconditionally even when `propose_submitting=False`.
 
 ## ProcessWorker Migration (Known Gap)
 

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/serializers.py

@@ -132,9 +132,16 @@ class Serializer(BaseModel, Generic[D]):
             except KeyError as exc:
                 raise ValidationError.from_exception_data(
                     title=cls.__name__,
-                    line_errors=[{"type": str(exc), "input": kwargs["type"]}],
+                    line_errors=[
+                        {
+                            "type": "value_error",
+                            "loc": ("type",),
+                            "input": kwargs["type"],
+                            "ctx": {"error": exc},
+                        }
+                    ],
                     input_type="python",
-                )
+                ) from exc
 
             return super().__new__(subcls)
         else:
@@ -158,6 +165,35 @@ class Serializer(BaseModel, Generic[D]):
         return type_str if isinstance(type_str, str) else None
 
 
+class UnknownSerializer(Serializer):
+    """
+    Opaque placeholder for serializers that are unavailable in the current process.
+
+    This allows persisted result metadata to be inspected without importing the custom
+    serializer implementation. Actual serialization work still fails when attempted.
+    """
+
+    type: str
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
+
+    @classmethod
+    def __dispatch_key__(cls) -> str:
+        return "__unknown__"
+
+    def dumps(self, obj: Any) -> bytes:
+        raise RuntimeError(
+            f"Serializer {self.type!r} is not available in this environment, so "
+            "serialization cannot be performed."
+        )
+
+    def loads(self, blob: bytes) -> Any:
+        raise RuntimeError(
+            f"Serializer {self.type!r} is not available in this environment, so "
+            "deserialization cannot be performed."
+        )
+
+
 class PickleSerializer(Serializer[D]):
     """
     Serializes objects using the pickle protocol.

{prefect-3.6.28.dev2 → prefect-3.6.28.dev4}/src/prefect/server/schemas/schedules.py

@@ -43,6 +43,14 @@ MAX_ITERATIONS = 1000
 if sys.version_info >= (3, 13):
     from whenever import DateTimeDelta
 
+    try:
+        from whenever import ItemizedDelta as _ItemizedDelta
+
+        _WHENEVER_DELTA_TYPES: tuple[type, ...] = (_ItemizedDelta,)
+    except ImportError:
+        _ItemizedDelta = None  # type: ignore[assignment]
+        _WHENEVER_DELTA_TYPES = (DateTimeDelta,)
+
     AnchorDate: TypeAlias = datetime.datetime
 else:
     from pydantic import AfterValidator
@@ -174,22 +182,35 @@ class IntervalSchedule(PrefectBaseModel):
             from whenever import PlainDateTime, ZonedDateTime
 
             if start is None:
-                start = ZonedDateTime.now("UTC").py_datetime()
+                _zdt = ZonedDateTime.now("UTC")
+                start = (
+                    _zdt.to_stdlib()
+                    if hasattr(_zdt, "to_stdlib")
+                    else _zdt.py_datetime()
+                )
 
             target_timezone = self.timezone or "UTC"
+            _zdt_from_dt = (
+                ZonedDateTime
+                if hasattr(ZonedDateTime, "to_stdlib")
+                else ZonedDateTime.from_py_datetime
+            )
+            _pdt_from_dt = (
+                PlainDateTime
+                if hasattr(PlainDateTime, "to_stdlib")
+                else PlainDateTime.from_py_datetime
+            )
 
             def to_local_zdt(dt: datetime.datetime | None) -> ZonedDateTime | None:
                 if dt is None:
                     return None
                 if dt.tzinfo is None:
-                    return PlainDateTime.from_py_datetime(dt).assume_tz(target_timezone)
+                    return _pdt_from_dt(dt).assume_tz(target_timezone)
                 if isinstance(dt.tzinfo, ZoneInfo):
-                    return ZonedDateTime.from_py_datetime(dt).to_tz(target_timezone)
+                    return _zdt_from_dt(dt).to_tz(target_timezone)
                 # For offset-based tzinfo instances (e.g. datetime.timezone(+09:00)),
                 # use astimezone to preserve the instant, then convert to ZonedDateTime.
-                return ZonedDateTime.from_py_datetime(
-                    dt.astimezone(ZoneInfo(target_timezone))
-                )
+                return _zdt_from_dt(dt.astimezone(ZoneInfo(target_timezone)))
 
             anchor_zdt = to_local_zdt(self.anchor_date)
             assert anchor_zdt is not None
@@ -200,14 +221,24 @@ class IntervalSchedule(PrefectBaseModel):
             local_end = to_local_zdt(end)
 
             interval = self.interval
-            if isinstance(interval, DateTimeDelta):
-                # DateTimeDelta properly distinguishes calendar days from
-                # exact hours, so we can use it directly. We still need an
-                # approximate total-seconds value for the initial offset jump.
-                _months, _days, _secs, _nanos = interval.in_months_days_secs_nanos()
-                approx_total_seconds = (
-                    _months * 30 * 86400 + _days * 86400 + _secs + _nanos / 1e9
-                )
+            if isinstance(interval, _WHENEVER_DELTA_TYPES):
+                # whenever delta types distinguish calendar days from exact hours,
+                # so we can use them directly. We still need an approximate
+                # total-seconds value for the initial offset jump.
+                if isinstance(interval, DateTimeDelta):
+                    _months, _days, _secs, _nanos = interval.in_months_days_secs_nanos()
+                    approx_total_seconds = (
+                        _months * 30 * 86400 + _days * 86400 + _secs + _nanos / 1e9
+                    )
+                else:  # ItemizedDelta (whenever >= 0.10.0)
+                    _date, _time = interval.date_and_time_parts()
+                    _months = _date.get("months") or 0 if _date else 0
+                    _days = _date.get("days") or 0 if _date else 0
+                    approx_total_seconds = (
+                        _months * 30 * 86400
+                        + _days * 86400
+                        + (int(_time.total("seconds")) if _time else 0)
+                    )
 
                 def _advance(zdt: ZonedDateTime) -> ZonedDateTime:
                     return zdt + interval
@@ -224,7 +255,13 @@ class IntervalSchedule(PrefectBaseModel):
                 def _advance(zdt: ZonedDateTime) -> ZonedDateTime:
                     return zdt.add(days=_interval_days, seconds=_interval_seconds)
 
-            offset = (local_start - anchor_zdt).in_seconds() / approx_total_seconds
+            _diff = local_start - anchor_zdt
+            _diff_secs = (
+                _diff.total("seconds")
+                if hasattr(_diff, "total")
+                else _diff.in_seconds()
+            )
+            offset = _diff_secs / approx_total_seconds
             next_date = anchor_zdt.add(seconds=approx_total_seconds * int(offset))
 
             while next_date < local_start:
@@ -241,7 +278,11 @@ class IntervalSchedule(PrefectBaseModel):
                 # ensure no duplicates; weird things can happen with DST
                 if next_date not in dates:
                     dates.add(next_date)
-                    yield next_date.py_datetime()
+                    yield (
+                        next_date.to_stdlib()
+                        if hasattr(next_date, "to_stdlib")
+                        else next_date.py_datetime()
+                    )
 
                 # if enough dates have been collected or enough attempts were made, exit
                 if len(dates) >= n or counter > MAX_ITERATIONS:
@@ -449,10 +490,18 @@ class CronSchedule(PrefectBaseModel):
                 from whenever import ZonedDateTime
 
                 # Use `whenever` to handle DST correctly
+                _zdt_from_dt = (
+                    ZonedDateTime
+                    if hasattr(ZonedDateTime, "to_stdlib")
+                    else ZonedDateTime.from_py_datetime
+                )
+                _zdt = _zdt_from_dt(start_localized + delta).to_tz(
+                    self.timezone or "UTC"
+                )
                 next_date = (
-                    ZonedDateTime.from_py_datetime(start_localized + delta)
-                    .to_tz(self.timezone or "UTC")
-                    .py_datetime()
+                    _zdt.to_stdlib()
+                    if hasattr(_zdt, "to_stdlib")
+                    else _zdt.py_datetime()
                 )
             else:
                 next_date = create_datetime_instance(start_localized + delta)