prefect-client 3.1.15__py3-none-any.whl → 3.2.0__py3-none-any.whl

prefect/_experimental/sla/objects.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import abc
+from datetime import timedelta
 from typing import Literal, Optional, Union
 from uuid import UUID
 
@@ -49,6 +50,33 @@ class TimeToCompletionSla(ServiceLevelAgreement):
     )
 
 
+class FrequencySla(ServiceLevelAgreement):
+    """An SLA that triggers when a completed flow run is not detected in the specified time.
+
+    For example, if stale_after is 1 hour, if a flow run does not complete
+    within an hour of the previous flow run, the SLA will trigger.
+    """
+
+    stale_after: timedelta = Field(
+        default=...,
+        description="The amount of time after which a flow run is considered in violation.",
+    )
+
+
+class LatenessSla(ServiceLevelAgreement):
+    """An SLA that triggers when a flow run does not start within the specified window.
+
+    For example, if you schedule the deployment to run every day at 2:00pm and you pass
+    within=timedelta(minutes=10) to this SLA, if a run hasn't started by 2:10pm the SLA
+    violation will be recorded.
+    """
+
+    within: timedelta = Field(
+        default=...,
+        description="The amount of time before a flow run is considered in violation.",
+    )
+
+
 class SlaMergeResponse(PrefectBaseModel):
     """A response object for the apply_slas_for_deployment method. Contains the names of the created, updated, and deleted SLAs."""
 
@@ -58,4 +86,4 @@ class SlaMergeResponse(PrefectBaseModel):
 
 
 # Concrete SLA types
-SlaTypes: TypeAlias = Union[TimeToCompletionSla]
+SlaTypes: TypeAlias = Union[TimeToCompletionSla, LatenessSla, FrequencySla]

prefect/_internal/compatibility/deprecated.py

@@ -15,10 +15,10 @@ import sys
 import warnings
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 
-import pendulum
 from pydantic import BaseModel
 from typing_extensions import ParamSpec, TypeAlias, TypeVar
 
+from prefect.types._datetime import DateTime, from_format
 from prefect.utilities.callables import get_call_parameters
 from prefect.utilities.importtools import (
     AliasedModuleDefinition,
@@ -60,18 +60,18 @@ def generate_deprecation_message(
     if not start_date and not end_date:
         raise ValueError(
             "A start date is required if an end date is not provided. Suggested start"
-            f" date is {pendulum.now('UTC').format(DEPRECATED_DATEFMT)!r}"
+            f" date is {DateTime.now('UTC').format(DEPRECATED_DATEFMT)!r}"
         )
 
     if not end_date:
         if TYPE_CHECKING:
             assert start_date is not None
-        parsed_start_date = pendulum.from_format(start_date, DEPRECATED_DATEFMT)
+        parsed_start_date = from_format(start_date, DEPRECATED_DATEFMT)
         parsed_end_date = parsed_start_date.add(months=6)
         end_date = parsed_end_date.format(DEPRECATED_DATEFMT)
     else:
         # Validate format
-        pendulum.from_format(end_date, DEPRECATED_DATEFMT)
+        from_format(end_date, DEPRECATED_DATEFMT)
 
     if when:
         when = " when " + when

prefect/_internal/compatibility/migration.py

@@ -34,7 +34,7 @@ Removed objects:
     ```python
     # at top
     from prefect._internal.compatibility.migration import getattr_migration
-    
+
     # at bottom
     __getattr__ = getattr_migration(__name__)
     ```

prefect/_internal/concurrency/calls.py

@@ -155,8 +155,7 @@ class Future(concurrent.futures.Future[T]):
 
     if TYPE_CHECKING:
 
-        def __get_result(self) -> T:
-            ...
+        def __get_result(self) -> T: ...
 
     def result(self, timeout: Optional[float] = None) -> T:
         """Return the result of the call that the future represents.

prefect/_internal/concurrency/cancellation.py

@@ -473,13 +473,11 @@ class WatcherThreadCancelScope(CancelScope):
 
 
 @overload
-def get_deadline(timeout: float) -> float:
-    ...
+def get_deadline(timeout: float) -> float: ...
 
 
 @overload
-def get_deadline(timeout: None) -> None:
-    ...
+def get_deadline(timeout: None) -> None: ...
 
 
 def get_deadline(timeout: Optional[float]) -> Optional[float]:

prefect/_internal/concurrency/threads.py

@@ -135,9 +135,9 @@ class EventLoopThread(Portal):
         self.thread = threading.Thread(
             name=name, daemon=daemon, target=self._entrypoint
         )
-        self._ready_future: concurrent.futures.Future[
-            bool
-        ] = concurrent.futures.Future()
+        self._ready_future: concurrent.futures.Future[bool] = (
+            concurrent.futures.Future()
+        )
         self._loop: Optional[asyncio.AbstractEventLoop] = None
         self._shutdown_event: Event = Event()
         self._run_once: bool = run_once

prefect/_internal/schemas/bases.py

@@ -3,7 +3,6 @@ Utilities for creating and working with Prefect REST API schemas.
 """
 
 import datetime
-import os
 from typing import Any, ClassVar, Optional, TypeVar, cast
 from uuid import UUID, uuid4
 
@@ -25,9 +24,7 @@ class PrefectBaseModel(BaseModel):
     fields that are passed to it at instantiation. Because adding new fields to
     API payloads is not considered a breaking change, this ensures that any
     Prefect client loading data from a server running a possibly-newer version
-    of Prefect will be able to process those new fields gracefully. However,
-    when PREFECT_TEST_MODE is on, extra fields are forbidden in order to catch
-    subtle unintentional testing errors.
+    of Prefect will be able to process those new fields gracefully.
     """
 
     _reset_fields: ClassVar[set[str]] = set()
@@ -35,16 +32,11 @@ class PrefectBaseModel(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(
         ser_json_timedelta="float",
         defer_build=True,
-        extra=(
-            "ignore"
-            if os.getenv("PREFECT_TEST_MODE", "0").lower() not in ["true", "1"]
-            and os.getenv("PREFECT_TESTING_TEST_MODE", "0").lower() not in ["true", "1"]
-            else "forbid"
-        ),
+        extra="ignore",
     )
 
     def __eq__(self, other: Any) -> bool:
-        """Equaltiy operator that ignores the resettable fields of the PrefectBaseModel.
+        """Equality operator that ignores the resettable fields of the PrefectBaseModel.
 
         NOTE: this equality operator will only be applied if the PrefectBaseModel is
         the left-hand operand. This is a limitation of Python.

prefect/_internal/schemas/validators.py

@@ -40,13 +40,15 @@ LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX = "^[a-z0-9_]*$"
 
 
 @overload
-def raise_on_name_alphanumeric_dashes_only(value: str, field_name: str = ...) -> str:
-    ...
+def raise_on_name_alphanumeric_dashes_only(
+    value: str, field_name: str = ...
+) -> str: ...
 
 
 @overload
-def raise_on_name_alphanumeric_dashes_only(value: None, field_name: str = ...) -> None:
-    ...
+def raise_on_name_alphanumeric_dashes_only(
+    value: None, field_name: str = ...
+) -> None: ...
 
 
 def raise_on_name_alphanumeric_dashes_only(
@@ -64,15 +66,13 @@ def raise_on_name_alphanumeric_dashes_only(
 @overload
 def raise_on_name_alphanumeric_underscores_only(
     value: str, field_name: str = ...
-) -> str:
-    ...
+) -> str: ...
 
 
 @overload
 def raise_on_name_alphanumeric_underscores_only(
     value: None, field_name: str = ...
-) -> None:
-    ...
+) -> None: ...
 
 
 def raise_on_name_alphanumeric_underscores_only(
@@ -149,13 +149,13 @@ def validate_parameters_conform_to_schema(
 
 
 @overload
-def validate_parameter_openapi_schema(schema: M, values: Mapping[str, Any]) -> M:
-    ...
+def validate_parameter_openapi_schema(schema: M, values: Mapping[str, Any]) -> M: ...
 
 
 @overload
-def validate_parameter_openapi_schema(schema: None, values: Mapping[str, Any]) -> None:
-    ...
+def validate_parameter_openapi_schema(
+    schema: None, values: Mapping[str, Any]
+) -> None: ...
 
 
 def validate_parameter_openapi_schema(
@@ -198,13 +198,11 @@ def reconcile_schedules_runner(values: MM) -> MM:
 
 
 @overload
-def validate_schedule_max_scheduled_runs(v: int, limit: int) -> int:
-    ...
+def validate_schedule_max_scheduled_runs(v: int, limit: int) -> int: ...
 
 
 @overload
-def validate_schedule_max_scheduled_runs(v: None, limit: int) -> None:
-    ...
+def validate_schedule_max_scheduled_runs(v: None, limit: int) -> None: ...
 
 
 def validate_schedule_max_scheduled_runs(v: Optional[int], limit: int) -> Optional[int]:
@@ -260,15 +258,13 @@ def default_anchor_date(v: pendulum.DateTime) -> pendulum.DateTime:
 
 
 @overload
-def default_timezone(v: str, values: Optional[Mapping[str, Any]] = ...) -> str:
-    ...
+def default_timezone(v: str, values: Optional[Mapping[str, Any]] = ...) -> str: ...
 
 
 @overload
 def default_timezone(
     v: None, values: Optional[Mapping[str, Any]] = ...
-) -> Optional[str]:
-    ...
+) -> Optional[str]: ...
 
 
 def default_timezone(
@@ -411,13 +407,11 @@ def validate_load_kwargs(value: M) -> M:
 
 
 @overload
-def cast_type_names_to_serializers(value: str) -> "Serializer[Any]":
-    ...
+def cast_type_names_to_serializers(value: str) -> "Serializer[Any]": ...
 
 
 @overload
-def cast_type_names_to_serializers(value: "Serializer[T]") -> "Serializer[T]":
-    ...
+def cast_type_names_to_serializers(value: "Serializer[T]") -> "Serializer[T]": ...
 
 
 def cast_type_names_to_serializers(
@@ -457,13 +451,11 @@ def validate_compressionlib(value: str) -> str:
 
 # TODO: if we use this elsewhere we can change the error message to be more generic
 @overload
-def list_length_50_or_less(v: list[float]) -> list[float]:
-    ...
+def list_length_50_or_less(v: list[float]) -> list[float]: ...
 
 
 @overload
-def list_length_50_or_less(v: None) -> None:
-    ...
+def list_length_50_or_less(v: None) -> None: ...
 
 
 def list_length_50_or_less(v: Optional[list[float]]) -> Optional[list[float]]:
@@ -474,13 +466,11 @@ def list_length_50_or_less(v: Optional[list[float]]) -> Optional[list[float]]:
 
 # TODO: if we use this elsewhere we can change the error message to be more generic
 @overload
-def validate_not_negative(v: float) -> float:
-    ...
+def validate_not_negative(v: float) -> float: ...
 
 
 @overload
-def validate_not_negative(v: None) -> None:
-    ...
+def validate_not_negative(v: None) -> None: ...
 
 
 def validate_not_negative(v: Optional[float]) -> Optional[float]:
@@ -490,13 +480,11 @@ def validate_not_negative(v: Optional[float]) -> Optional[float]:
 
 
 @overload
-def validate_message_template_variables(v: str) -> str:
-    ...
+def validate_message_template_variables(v: str) -> str: ...
 
 
 @overload
-def validate_message_template_variables(v: None) -> None:
-    ...
+def validate_message_template_variables(v: None) -> None: ...
 
 
 def validate_message_template_variables(v: Optional[str]) -> Optional[str]:
@@ -521,13 +509,11 @@ def validate_default_queue_id_not_none(v: Optional[UUID]) -> UUID:
 
 
 @overload
-def validate_max_metadata_length(v: MM) -> MM:
-    ...
+def validate_max_metadata_length(v: MM) -> MM: ...
 
 
 @overload
-def validate_max_metadata_length(v: None) -> None:
-    ...
+def validate_max_metadata_length(v: None) -> None: ...
 
 
 def validate_max_metadata_length(v: Optional[MM]) -> Optional[MM]:
@@ -544,13 +530,11 @@ def validate_max_metadata_length(v: Optional[MM]) -> Optional[MM]:
 
 
 @overload
-def validate_cache_key_length(cache_key: str) -> str:
-    ...
+def validate_cache_key_length(cache_key: str) -> str: ...
 
 
 @overload
-def validate_cache_key_length(cache_key: None) -> None:
-    ...
+def validate_cache_key_length(cache_key: None) -> None: ...
 
 
 def validate_cache_key_length(cache_key: Optional[str]) -> Optional[str]:
@@ -587,13 +571,11 @@ def set_run_policy_deprecated_fields(values: MM) -> MM:
 
 
 @overload
-def return_v_or_none(v: str) -> str:
-    ...
+def return_v_or_none(v: str) -> str: ...
 
 
 @overload
-def return_v_or_none(v: None) -> None:
-    ...
+def return_v_or_none(v: None) -> None: ...
 
 
 def return_v_or_none(v: Optional[str]) -> Optional[str]:
@@ -629,13 +611,11 @@ def validate_name_present_on_nonanonymous_blocks(values: M) -> M:
 
 
 @overload
-def validate_working_dir(v: str) -> Path:
-    ...
+def validate_working_dir(v: str) -> Path: ...
 
 
 @overload
-def validate_working_dir(v: None) -> None:
-    ...
+def validate_working_dir(v: None) -> None: ...
 
 
 def validate_working_dir(v: Optional[Path | str]) -> Optional[Path]:
@@ -652,13 +632,11 @@ def validate_working_dir(v: Optional[Path | str]) -> Optional[Path]:
 
 
 @overload
-def validate_block_document_name(value: str) -> str:
-    ...
+def validate_block_document_name(value: str) -> str: ...
 
 
 @overload
-def validate_block_document_name(value: None) -> None:
-    ...
+def validate_block_document_name(value: None) -> None: ...
 
 
 def validate_block_document_name(value: Optional[str]) -> Optional[str]:
@@ -673,13 +651,11 @@ def validate_artifact_key(value: str) -> str:
 
 
 @overload
-def validate_variable_name(value: str) -> str:
-    ...
+def validate_variable_name(value: str) -> str: ...
 
 
 @overload
-def validate_variable_name(value: None) -> None:
-    ...
+def validate_variable_name(value: None) -> None: ...
 
 
 def validate_variable_name(value: Optional[str]) -> Optional[str]:

prefect/_result_records.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import inspect
+import uuid
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+)
+from uuid import UUID
+
+from pydantic import (
+    BaseModel,
+    Field,
+    ValidationError,
+    model_validator,
+)
+
+import prefect
+from prefect.exceptions import (
+    SerializationError,
+)
+from prefect.serializers import PickleSerializer, Serializer
+from prefect.types import DateTime
+
+if TYPE_CHECKING:
+    pass
+
+
+ResultSerializer = Union[Serializer, str]
+LITERAL_TYPES: set[type] = {type(None), bool, UUID}
+R = TypeVar("R")
+
+
+class ResultRecordMetadata(BaseModel):
+    """
+    Metadata for a result record.
+    """
+
+    storage_key: Optional[str] = Field(
+        default=None
+    )  # optional for backwards compatibility
+    expiration: Optional[DateTime] = Field(default=None)
+    serializer: Serializer = Field(default_factory=PickleSerializer)
+    prefect_version: str = Field(default=prefect.__version__)
+    storage_block_id: Optional[uuid.UUID] = Field(default=None)
+
+    def dump_bytes(self) -> bytes:
+        """
+        Serialize the metadata to bytes.
+
+        Returns:
+            bytes: the serialized metadata
+        """
+        return self.model_dump_json(serialize_as_any=True).encode()
+
+    @classmethod
+    def load_bytes(cls, data: bytes) -> "ResultRecordMetadata":
+        """
+        Deserialize metadata from bytes.
+
+        Args:
+            data: the serialized metadata
+
+        Returns:
+            ResultRecordMetadata: the deserialized metadata
+        """
+        return cls.model_validate_json(data)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, ResultRecordMetadata):
+            return False
+        return (
+            self.storage_key == other.storage_key
+            and self.expiration == other.expiration
+            and self.serializer == other.serializer
+            and self.prefect_version == other.prefect_version
+            and self.storage_block_id == other.storage_block_id
+        )
+
+
+class ResultRecord(BaseModel, Generic[R]):
+    """
+    A record of a result.
+    """
+
+    metadata: ResultRecordMetadata
+    result: R
+
+    @property
+    def expiration(self) -> DateTime | None:
+        return self.metadata.expiration
+
+    @property
+    def serializer(self) -> Serializer:
+        return self.metadata.serializer
+
+    def serialize_result(self) -> bytes:
+        try:
+            data = self.serializer.dumps(self.result)
+        except Exception as exc:
+            extra_info = (
+                'You can try a different serializer (e.g. result_serializer="json") '
+                "or disabling persistence (persist_result=False) for this flow or task."
+            )
+            # check if this is a known issue with cloudpickle and pydantic
+            # and add extra information to help the user recover
+
+            if (
+                isinstance(exc, TypeError)
+                and isinstance(self.result, BaseModel)
+                and str(exc).startswith("cannot pickle")
+            ):
+                try:
+                    from IPython.core.getipython import get_ipython
+
+                    if get_ipython() is not None:
+                        extra_info = inspect.cleandoc(
+                            """
+                            This is a known issue in Pydantic that prevents
+                            locally-defined (non-imported) models from being
+                            serialized by cloudpickle in IPython/Jupyter
+                            environments. Please see
+                            https://github.com/pydantic/pydantic/issues/8232 for
+                            more information. To fix the issue, either: (1) move
+                            your Pydantic class definition to an importable
+                            location, (2) use the JSON serializer for your flow
+                            or task (`result_serializer="json"`), or (3)
+                            disable result persistence for your flow or task
+                            (`persist_result=False`).
+                            """
+                        ).replace("\n", " ")
+                except ImportError:
+                    pass
+            raise SerializationError(
+                f"Failed to serialize object of type {type(self.result).__name__!r} with "
+                f"serializer {self.serializer.type!r}. {extra_info}"
+            ) from exc
+
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce_old_format(cls, value: dict[str, Any] | Any) -> dict[str, Any]:
+        if isinstance(value, dict):
+            if "data" in value:
+                value["result"] = value.pop("data")
+            if "metadata" not in value:
+                value["metadata"] = {}
+            if "expiration" in value:
+                value["metadata"]["expiration"] = value.pop("expiration")
+            if "serializer" in value:
+                value["metadata"]["serializer"] = value.pop("serializer")
+            if "prefect_version" in value:
+                value["metadata"]["prefect_version"] = value.pop("prefect_version")
+        return value
+
+    def serialize_metadata(self) -> bytes:
+        return self.metadata.dump_bytes()
+
+    def serialize(
+        self,
+    ) -> bytes:
+        """
+        Serialize the record to bytes.
+
+        Returns:
+            bytes: the serialized record
+
+        """
+        return (
+            self.model_copy(update={"result": self.serialize_result()})
+            .model_dump_json(serialize_as_any=True)
+            .encode()
+        )
+
+    @classmethod
+    def deserialize(
+        cls, data: bytes, backup_serializer: Serializer | None = None
+    ) -> "ResultRecord[R]":
+        """
+        Deserialize a record from bytes.
+
+        Args:
+            data: the serialized record
+            backup_serializer: The serializer to use to deserialize the result record. Only
+                necessary if the provided data does not specify a serializer.
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        try:
+            instance = cls.model_validate_json(data)
+        except ValidationError:
+            if backup_serializer is None:
+                raise
+            else:
+                result = backup_serializer.loads(data)
+                return cls(
+                    metadata=ResultRecordMetadata(serializer=backup_serializer),
+                    result=result,
+                )
+        if isinstance(instance.result, bytes):
+            instance.result = instance.serializer.loads(instance.result)
+        elif isinstance(instance.result, str):
+            instance.result = instance.serializer.loads(instance.result.encode())
+        return instance
+
+    @classmethod
+    def deserialize_from_result_and_metadata(
+        cls, result: bytes, metadata: bytes
+    ) -> "ResultRecord[R]":
+        """
+        Deserialize a record from separate result and metadata bytes.
+
+        Args:
+            result: the result
+            metadata: the serialized metadata
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        result_record_metadata = ResultRecordMetadata.load_bytes(metadata)
+        return cls(
+            metadata=result_record_metadata,
+            result=result_record_metadata.serializer.loads(result),
+        )
+
+    def __eq__(self, other: Any | "ResultRecord[Any]") -> bool:
+        if not isinstance(other, ResultRecord):
+            return False
+        return self.metadata == other.metadata and self.result == other.result

prefect/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-01-30T11:31:29-0800",
+ "date": "2025-02-07T18:02:21-0800",
  "dirty": true,
  "error": null,
- "full-revisionid": "3ac3d54885a6157989efd79cbfc0d681b4bb7e0c",
- "version": "3.1.15"
+ "full-revisionid": "c8986edebb2dde3e2a931adbe24d2eaefcb799cb",
+ "version": "3.2.0"
 }
 '''  # END VERSION_JSON
 

prefect/agent.py

@@ -1,6 +1,7 @@
 """
 2024-06-27: This surfaces an actionable error message for moved or removed objects in Prefect 3.0 upgrade.
 """
+
 from typing import Any, Callable
 
 from prefect._internal.compatibility.migration import getattr_migration