prefect-client 3.9.1.dev1__tar.gz → 3.9.1.dev3__tar.gz

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.9.1.dev1
+Version: 3.9.1.dev3
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -50,7 +50,7 @@ Requires-Dist: pydantic-core<3.0.0,>=2.12.0
 Requires-Dist: pydantic-extra-types<3.0.0,>=2.8.2
 Requires-Dist: pydantic-settings<3.0.0,>=2.9.1
 Requires-Dist: python-dateutil<3.0.0,>=2.8.2
-Requires-Dist: python-slugify<9.1,>=9
+Requires-Dist: python-slugify<9.2,>=9
 Requires-Dist: pytz<2027,>=2021.1
 Requires-Dist: pyyaml<7.0.0,>=5.4.1
 Requires-Dist: rfc3339-validator<0.2.0,>=0.1.4
@@ -62,9 +62,9 @@ Requires-Dist: toml>=0.10.0
 Requires-Dist: typing-extensions<5.0.0,>=4.10.0
 Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<17.0,>=15.0.1
-Requires-Dist: whenever<0.11.0,>=0.10.5; python_version >= '3.13'
+Requires-Dist: whenever<0.12.0,>=0.10.5; python_version >= '3.13'
 Provides-Extra: notifications
-Requires-Dist: apprise<2.0.0,>=1.13.0; extra == 'notifications'
+Requires-Dist: apprise<2.1.0,>=1.13.0; extra == 'notifications'
 Description-Content-Type: text/markdown
 
 <p align="center"><img src="https://github.com/PrefectHQ/prefect/assets/3407835/c654cbc6-63e8-4ada-a92a-efd2f8f24b85" width=1000></p>

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/pyproject.toml

@@ -55,7 +55,7 @@ dependencies = [
     "pydantic_extra_types>=2.8.2,<3.0.0",
     "pydantic_settings>=2.9.1,<3.0.0",
     "python-dateutil>=2.8.2,<3.0.0",
-    "python-slugify>=9,<9.1",
+    "python-slugify>=9,<9.2",
     "pytz>=2021.1,<2027",
     "pyyaml>=5.4.1,<7.0.0",
     "rfc3339-validator>=0.1.4,<0.2.0",
@@ -67,7 +67,7 @@ dependencies = [
     "typing_extensions>=4.10.0,<5.0.0",
     "uvicorn>=0.14.0,!=0.29.0",
     "websockets>=15.0.1,<17.0",
-    "whenever>=0.10.5,<0.11.0; python_version>='3.13'",
+    "whenever>=0.10.5,<0.12.0; python_version>='3.13'",
 ]
 [project.urls]
 Changelog = "https://github.com/PrefectHQ/prefect/releases"
@@ -75,7 +75,7 @@ Documentation = "https://docs.prefect.io"
 Source = "https://github.com/PrefectHQ/prefect"
 Tracker = "https://github.com/PrefectHQ/prefect/issues"
 [project.optional-dependencies]
-notifications = ["apprise>=1.13.0, <2.0.0"]
+notifications = ["apprise>=1.13.0, <2.1.0"]
 
 
 [tool.hatch.version]

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/AGENTS.md

@@ -25,7 +25,7 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 - **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.
 - **Event and log WebSocket subscribers are parallel implementations.** `events/clients.py::PrefectEventSubscriber` and `logging/clients.py::PrefectLogsSubscriber` duplicate the same reconnect/backoff/dedup logic, including the `reconnect_on_clean_close` option (used by `events/subscribers.py::FlowRunSubscriber` so a clean disconnect doesn't hide a terminal event). Mirror any reconnection-behavior change across both.
 - **Flow run observers own their stream recovery.** `_internal/observers.py` observers create subscribers with `reconnection_attempts=0` and delegate polling fallback, reconnect backoff, and setup deadlines to `_internal/_observation_delivery.py::ObservationDelivery`. Subscribers close any socket left by a failed or cancelled `__aenter__`, since callers never exit a context that failed to enter.
-- **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.
+- **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 across supported whenever releases. Version-specific code is guarded by feature-detection flags (`_WHENEVER_NEW_API` for ≥ 0.10.0, `_SYSTEM_TZ` for ≥ 0.11), not version checks. 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. Likewise avoid `.assume_system_tz()`/`.to_system_tz()` (deprecated in 0.11; the warning fails tests under `filterwarnings = error`) — use `in_local_tz()` — and direct `DateTimeDelta` imports (removed in 0.11) — use the `Interval` alias. 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.9.1.dev3/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.9.1.dev3"
+__build_date__ = "2026-10-24 08:17:11.725751+00:00"
+__git_commit__ = "f1f98c3f2468ef5af3992db9439a2ead26c9e27e"
+__dirty__ = False

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/blocks/notifications.py

@@ -47,7 +47,7 @@ class AbstractAppriseNotificationBlock(NotificationBlock, ABC):
         )
 
         self._apprise_client = Apprise(asset=prefect_app_data)
-        self._apprise_client.add(servers=url.get_secret_value())  # pyright: ignore[reportUnknownMemberType]
+        self._apprise_client.add(url.get_secret_value())  # pyright: ignore[reportUnknownMemberType]
 
     def block_initialization(self) -> None:
         self._start_apprise_client(getattr(self, "url"))
@@ -1115,9 +1115,7 @@ class SendgridEmail(AbstractAppriseNotificationBlock):
         """Update apprise client with current to_emails before sending."""
         if hasattr(self, "_apprise_client") and self._apprise_client:
             self._apprise_client.clear()
-            self._apprise_client.add(
-                servers=self._build_sendgrid_url().get_secret_value()
-            )
+            self._apprise_client.add(self._build_sendgrid_url().get_secret_value())
 
     async def anotify(
         self,

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/flow_engine.py

@@ -810,8 +810,17 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             )
         )
         raise_if_flow_run_suspension_requested()
-        self.set_state(terminal_state)
         self._return_value = resolved_result
+        state = self.set_state(terminal_state)
+        if terminal_state.is_failed() and state.is_scheduled():
+            self.logger.info(
+                f"Received non-final state {state.name!r} when proposing final"
+                f" state {terminal_state.name!r} and will attempt to run again..."
+            )
+            raise_if_flow_run_suspension_requested()
+            self._return_value = NotSet
+            self.set_state(Running())
+            return result
 
         link_state_to_flow_run_result(terminal_state, resolved_result)
         self._telemetry.end_span_on_success()
@@ -1332,6 +1341,8 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                 self.handle_timeout(exc)
             except Exception as exc:
                 self.logger.exception("Encountered exception during execution: %r", exc)
+                if self.state.is_final() or self._return_value is not NotSet:
+                    raise
                 self.handle_exception(exc)
 
     def call_flow_fn(self) -> Union[R, Coroutine[Any, Any, R]]:
@@ -1531,8 +1542,17 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             write_result=should_persist_result(),
         )
         raise_if_flow_run_suspension_requested()
-        await self.set_state(terminal_state)
         self._return_value = resolved_result
+        state = await self.set_state(terminal_state)
+        if terminal_state.is_failed() and state.is_scheduled():
+            self.logger.info(
+                f"Received non-final state {state.name!r} when proposing final"
+                f" state {terminal_state.name!r} and will attempt to run again..."
+            )
+            raise_if_flow_run_suspension_requested()
+            self._return_value = NotSet
+            await self.set_state(Running())
+            return result
 
         self._telemetry.end_span_on_success()
 
@@ -2075,6 +2095,8 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                 await self.handle_timeout(exc)
             except Exception as exc:
                 self.logger.exception("Encountered exception during execution: %r", exc)
+                if self.state.is_final() or self._return_value is not NotSet:
+                    raise
                 await self.handle_exception(exc)
 
     async def call_flow_fn(self) -> Coroutine[Any, Any, R]:

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/server/api/__init__.py

@@ -24,6 +24,7 @@ if TYPE_CHECKING:
         flows,
         logs,
         middleware,
+        observed_states,
         root,
         run_history,
         saved_searches,
@@ -58,6 +59,7 @@ __all__ = [
     "flows",
     "logs",
     "middleware",
+    "observed_states",
     "root",
     "run_history",
     "saved_searches",

prefect_client-3.9.1.dev3/src/prefect/server/api/observed_states.py

@@ -0,0 +1,32 @@
+"""Routes for discovering observed state types and names."""
+
+from typing import Annotated
+
+from fastapi import Depends, Query
+
+from prefect.server import models
+from prefect.server.database import PrefectDBInterface, provide_database_interface
+from prefect.server.schemas.observed_states import ObservedState, ObservedStateSort
+from prefect.server.utilities.server import PrefectRouter
+
+router: PrefectRouter = PrefectRouter(
+    prefix="/observed-states", tags=["Observed States"]
+)
+
+
+@router.get("")
+async def read_observed_states(
+    db: Annotated[PrefectDBInterface, Depends(provide_database_interface)],
+    query: Annotated[str | None, Query(max_length=100)] = None,
+    order_by: ObservedStateSort = ObservedStateSort.LAST_SEEN_DESC,
+    limit: Annotated[int, Query(ge=1, le=200)] = 200,
+) -> list[ObservedState]:
+    """Discover exact state names and types from retained run transitions.
+
+    Search by case-insensitive name or type prefix. Timestamps describe retained
+    history; deleting runs can change them or remove a state from the results.
+    """
+    async with db.session_context() as session:
+        return await models.observed_states.read_observed_states(
+            session=session, query=query, order_by=order_by, limit=limit
+        )

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/server/api/server.py

@@ -105,6 +105,7 @@ API_ROUTERS = (
     api.task_runs.router,
     api.flow_run_states.router,
     api.task_run_states.router,
+    api.observed_states.router,
     api.deployments.router,
     api.saved_searches.router,
     api.logs.router,

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/types/_datetime.py

@@ -14,7 +14,7 @@ from pydantic_core import core_schema as _core_schema
 from typing_extensions import TypeAlias
 
 if sys.version_info >= (3, 13):
-    from whenever import DateTimeDelta
+    import whenever as _whenever
     from whenever import ZonedDateTime as _ZDTProbe
 
     # True on whenever >= 0.10.0, which introduced ZonedDateTime(stdlib_dt),
@@ -22,6 +22,9 @@ if sys.version_info >= (3, 13):
     _WHENEVER_NEW_API: bool = hasattr(_ZDTProbe, "to_stdlib")
     del _ZDTProbe
 
+    # SYSTEM_TZ replaces the system-timezone methods in whenever 0.11.
+    _SYSTEM_TZ = getattr(_whenever, "SYSTEM_TZ", None)
+
     class _DateTime(datetime.datetime):
         """`datetime.datetime` with a Pydantic schema that coerces naive to UTC.
 
@@ -57,6 +60,8 @@ if sys.version_info >= (3, 13):
 
         Interval: TypeAlias = Union[datetime.timedelta, ItemizedDelta]
     else:
+        from whenever import DateTimeDelta
+
         Interval: TypeAlias = Union[datetime.timedelta, DateTimeDelta]
 else:
     _WHENEVER_NEW_API = False
@@ -345,7 +350,12 @@ def travel_to(dt: Any):
 def in_local_tz(dt: datetime.datetime) -> datetime.datetime:
     if sys.version_info >= (3, 13):
         if dt.tzinfo is None:
-            wdt = _whenever_pdt_from_py(dt).assume_system_tz()
+            pdt = _whenever_pdt_from_py(dt)
+            wdt = (
+                pdt.assume_tz(_SYSTEM_TZ)
+                if _SYSTEM_TZ is not None
+                else pdt.assume_system_tz()
+            )
         else:
             if not isinstance(dt.tzinfo, ZoneInfo):
                 if key := getattr(dt.tzinfo, "key", None):
@@ -354,7 +364,10 @@ def in_local_tz(dt: datetime.datetime) -> datetime.datetime:
                     utc_dt = dt.astimezone(datetime.timezone.utc)
                     dt = utc_dt.replace(tzinfo=ZoneInfo("UTC"))
 
-            wdt = _whenever_zdt_from_py(dt).to_system_tz()
+            zdt = _whenever_zdt_from_py(dt)
+            wdt = (
+                zdt.to_tz(_SYSTEM_TZ) if _SYSTEM_TZ is not None else zdt.to_system_tz()
+            )
 
         return _whenever_to_stdlib(wdt)
     else:

{prefect_client-3.9.1.dev1 → prefect_client-3.9.1.dev3}/src/prefect/utilities/collections.py

@@ -13,6 +13,7 @@ from collections.abc import (
     Hashable,
     Iterable,
     Iterator,
+    Mapping,
     Sequence,
     Set,
 )
@@ -543,8 +544,10 @@ def visit_collection(
                 model_instance = expr.model_construct(
                     _fields_set=expr.model_fields_set, **updated_data
                 )
-                for private_attr in expr.__private_attributes__:
-                    setattr(model_instance, private_attr, getattr(expr, private_attr))
+                # Only copy private attributes that have values; unset
+                # private attributes are absent from `__pydantic_private__`
+                for private_attr, value in (expr.__pydantic_private__ or {}).items():
+                    setattr(model_instance, private_attr, value)
                 result = model_instance
 
     # Update the cache with the final transformed result
@@ -617,6 +620,21 @@ def distinct(
         yield item
 
 
+def _canonical_int_or_key(key: Any) -> Any:
+    """
+    Convert a string like `"1"` or `"-1"` to an int, leaving any other key
+    (including non-canonical forms like `"01"`) unchanged.
+    """
+    if isinstance(key, str):
+        try:
+            int_key = int(key)
+        except ValueError:
+            return key
+        if str(int_key) == key:
+            return int_key
+    return key
+
+
 @overload
 def get_from_dict(
     dct: NestedDict[str, VT], keys: Union[str, list[str]], default: None = None
@@ -645,7 +663,9 @@ def get_from_dict(
         keys: The sequence of keys to use for access. Can be a
             dot-separated string or a list of keys. List indices can be included
             in the sequence as either integer keys or as string indices in square
-            brackets.
+            brackets. When indexing a dictionary, a string key is matched
+            exactly first and only falls back to the equivalent integer key
+            (e.g. `"1"` -> `1`) if no exact match exists.
         default: The default value to return if the requested key path does not
             exist. Defaults to None.
 
@@ -658,6 +678,7 @@ def get_from_dict(
     get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]') # 2
     get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1]) # 2
     get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default') # 'default'
+    get_from_dict({'years': {'2026': 42}}, 'years.2026') # 42
     ```
     """
     if isinstance(keys, str):
@@ -665,13 +686,16 @@ def get_from_dict(
     value = dct
     try:
         for key in keys:
-            try:
-                # Try to cast to int to handle list indices
-                key = int(key)
-            except ValueError:
-                # If it's not an int, use the key as-is
-                # for dict lookup
-                pass
+            if isinstance(value, Mapping):
+                # Prefer an exact match so numeric string keys like "2026" resolve
+                if key not in value:
+                    key = _canonical_int_or_key(key)
+            else:
+                try:
+                    # Try to cast to int to handle list indices
+                    key = int(key)
+                except ValueError:
+                    pass
             value = value[key]  # type: ignore
         return cast(VT, value)
     except (TypeError, KeyError, IndexError):

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

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.9.1.dev1"
-__build_date__ = "2026-10-22 08:19:36.634713+00:00"
-__git_commit__ = "7d1688ff034a89a47c900c0e2951c78ff1979f0d"
-__dirty__ = False