prefect-client 2.16.5__py3-none-any.whl → 2.16.7__py3-none-any.whl

prefect/deployments/deployments.py

@@ -21,6 +21,14 @@ from prefect._internal.compatibility.deprecated import (
     deprecated_class,
 )
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect._internal.schemas.validators import (
+    handle_openapi_schema,
+    infrastructure_must_have_capabilities,
+    reconcile_schedules,
+    storage_must_have_capabilities,
+    validate_automation_names,
+    validate_deprecated_schedule_fields,
+)
 from prefect.client.schemas.actions import DeploymentScheduleCreate
 
 if HAS_PYDANTIC_V2:
@@ -40,11 +48,9 @@ from prefect.client.utilities import inject_client
 from prefect.context import FlowRunContext, PrefectObjectRegistry, TaskRunContext
 from prefect.deployments.schedules import (
     FlexibleScheduleList,
-    create_minimal_deployment_schedule,
-    normalize_to_minimal_deployment_schedules,
 )
 from prefect.deployments.steps.core import run_steps
-from prefect.events.schemas import DeploymentTrigger
+from prefect.events import DeploymentTriggerTypes
 from prefect.exceptions import (
     BlockMissingCapabilities,
     ObjectAlreadyExists,
@@ -56,7 +62,6 @@ from prefect.infrastructure import Infrastructure, Process
 from prefect.logging.loggers import flow_run_logger, get_logger
 from prefect.states import Scheduled
 from prefect.tasks import Task
-from prefect.utilities.annotations import NotSet
 from prefect.utilities.asyncutils import run_sync_in_worker_thread, sync_compatible
 from prefect.utilities.callables import ParameterSchema, parameter_schema
 from prefect.utilities.filesystem import relative_path_to_current_platform, tmpchdir
@@ -579,7 +584,7 @@ class Deployment(BaseModel):
         description="The parameter schema of the flow, including defaults.",
     )
     timestamp: datetime = Field(default_factory=partial(pendulum.now, "UTC"))
-    triggers: List[DeploymentTrigger] = Field(
+    triggers: List[DeploymentTriggerTypes] = Field(
         default_factory=list,
         description="The triggers that should cause this deployment to run.",
     )
@@ -593,97 +598,28 @@ class Deployment(BaseModel):
     )
 
     @validator("infrastructure", pre=True)
-    def infrastructure_must_have_capabilities(cls, value):
-        if isinstance(value, dict):
-            if "_block_type_slug" in value:
-                # Replace private attribute with public for dispatch
-                value["block_type_slug"] = value.pop("_block_type_slug")
-            block = Block(**value)
-        elif value is None:
-            return value
-        else:
-            block = value
-
-        if "run-infrastructure" not in block.get_block_capabilities():
-            raise ValueError(
-                "Infrastructure block must have 'run-infrastructure' capabilities."
-            )
-        return block
+    def validate_infrastructure_capabilities(cls, value):
+        return infrastructure_must_have_capabilities(value)
 
     @validator("storage", pre=True)
-    def storage_must_have_capabilities(cls, value):
-        if isinstance(value, dict):
-            block_type = Block.get_block_class_from_key(value.pop("_block_type_slug"))
-            block = block_type(**value)
-        elif value is None:
-            return value
-        else:
-            block = value
-
-        capabilities = block.get_block_capabilities()
-        if "get-directory" not in capabilities:
-            raise ValueError(
-                "Remote Storage block must have 'get-directory' capabilities."
-            )
-        return block
+    def validate_storage(cls, value):
+        return storage_must_have_capabilities(value)
 
     @validator("parameter_openapi_schema", pre=True)
-    def handle_openapi_schema(cls, value):
-        """
-        This method ensures setting a value of `None` is handled gracefully.
-        """
-        if value is None:
-            return ParameterSchema()
-        return value
+    def validate_parameter_openapi_schema(cls, value):
+        return handle_openapi_schema(value)
 
     @validator("triggers")
-    def validate_automation_names(cls, field_value, values, field, config):
-        """Ensure that each trigger has a name for its automation if none is provided."""
-        for i, trigger in enumerate(field_value, start=1):
-            if trigger.name is None:
-                trigger.name = f"{values['name']}__automation_{i}"
-
-        return field_value
+    def validate_triggers(cls, field_value, values):
+        return validate_automation_names(field_value, values)
 
     @root_validator(pre=True)
-    def validate_deprecated_schedule_fields(cls, values):
-        if values.get("schedule") and not values.get("schedules"):
-            logger.warning(
-                "The field 'schedule' in 'Deployment' has been deprecated. It will not be "
-                "available after Sep 2024. Define schedules in the `schedules` list instead."
-            )
-        elif values.get("is_schedule_active") and not values.get("schedules"):
-            logger.warning(
-                "The field 'is_schedule_active' in 'Deployment' has been deprecated. It will "
-                "not be available after Sep 2024. Use the `active` flag within a schedule in "
-                "the `schedules` list instead and the `pause` flag in 'Deployment' to pause "
-                "all schedules."
-            )
-        return values
+    def validate_schedule(cls, values):
+        return validate_deprecated_schedule_fields(values, logger)
 
     @root_validator(pre=True)
-    def reconcile_schedules(cls, values):
-        schedule = values.get("schedule", NotSet)
-        schedules = values.get("schedules", NotSet)
-
-        if schedules is not NotSet:
-            values["schedules"] = normalize_to_minimal_deployment_schedules(schedules)
-        elif schedule is not NotSet:
-            values["schedule"] = None
-
-            if schedule is None:
-                values["schedules"] = []
-            else:
-                values["schedules"] = [
-                    create_minimal_deployment_schedule(
-                        schedule=schedule, active=values.get("is_schedule_active")
-                    )
-                ]
-
-        for schedule in values.get("schedules", []):
-            cls._validate_schedule(schedule.schedule)
-
-        return values
+    def validate_backwards_compatibility_for_schedule(cls, values):
+        return reconcile_schedules(cls, values)
 
     @classmethod
     @sync_compatible

prefect/deployments/runner.py

@@ -44,6 +44,7 @@ from rich.table import Table
 
 from prefect._internal.concurrency.api import create_call, from_async
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect._internal.schemas.validators import validate_automation_names
 from prefect.runner.storage import RunnerStorage
 from prefect.settings import (
     PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE,
@@ -68,7 +69,7 @@ from prefect.deployments.schedules import (
     create_minimal_deployment_schedule,
     normalize_to_minimal_deployment_schedules,
 )
-from prefect.events.schemas import DeploymentTrigger
+from prefect.events import DeploymentTriggerTypes
 from prefect.exceptions import (
     ObjectNotFound,
     PrefectHTTPStatusError,
@@ -175,7 +176,7 @@ class RunnerDeployment(BaseModel):
             "The path to the entrypoint for the workflow, relative to the `path`."
         ),
     )
-    triggers: List[DeploymentTrigger] = Field(
+    triggers: List[DeploymentTriggerTypes] = Field(
         default_factory=list,
         description="The triggers that should cause this deployment to run.",
     )
@@ -229,13 +230,9 @@ class RunnerDeployment(BaseModel):
         return self._entrypoint_type
 
     @validator("triggers", allow_reuse=True)
-    def validate_automation_names(cls, field_value, values, field, config):
+    def validate_automation_names(cls, field_value, values):
         """Ensure that each trigger has a name for its automation if none is provided."""
-        for i, trigger in enumerate(field_value, start=1):
-            if trigger.name is None:
-                trigger.name = f"{values['name']}__automation_{i}"
-
-        return field_value
+        return validate_automation_names(field_value, values)
 
     @root_validator(pre=True)
     def reconcile_paused(cls, values):
@@ -467,7 +464,7 @@ class RunnerDeployment(BaseModel):
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
         version: Optional[str] = None,
@@ -603,7 +600,7 @@ class RunnerDeployment(BaseModel):
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
         version: Optional[str] = None,
@@ -701,7 +698,7 @@ class RunnerDeployment(BaseModel):
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
         version: Optional[str] = None,

prefect/events/__init__.py

@@ -1,9 +1,48 @@
-from .schemas import Event, RelatedResource, Resource
+from .schemas.events import Event, ReceivedEvent
+from .schemas.events import Resource, RelatedResource, ResourceSpecification
+from .schemas.automations import (
+    Automation,
+    Posture,
+    Trigger,
+    ResourceTrigger,
+    EventTrigger,
+    MetricTrigger,
+    MetricTriggerOperator,
+    MetricTriggerQuery,
+    CompositeTrigger,
+    CompoundTrigger,
+    SequenceTrigger,
+)
+from .schemas.deployment_triggers import (
+    DeploymentTriggerTypes,
+    DeploymentEventTrigger,
+    DeploymentMetricTrigger,
+    DeploymentCompoundTrigger,
+    DeploymentSequenceTrigger,
+)
 from .utilities import emit_event
 
 __all__ = [
     "Event",
+    "ReceivedEvent",
     "Resource",
     "RelatedResource",
+    "ResourceSpecification",
+    "Automation",
+    "Posture",
+    "Trigger",
+    "ResourceTrigger",
+    "EventTrigger",
+    "MetricTrigger",
+    "MetricTriggerOperator",
+    "MetricTriggerQuery",
+    "CompositeTrigger",
+    "CompoundTrigger",
+    "SequenceTrigger",
+    "DeploymentTriggerTypes",
+    "DeploymentEventTrigger",
+    "DeploymentMetricTrigger",
+    "DeploymentCompoundTrigger",
+    "DeploymentSequenceTrigger",
     "emit_event",
 ]

prefect/events/clients.py

@@ -16,12 +16,7 @@ from uuid import UUID
 
 import orjson
 import pendulum
-
-try:
-    from cachetools import TTLCache
-except ImportError:
-    pass
-from prefect._vendor.starlette.status import WS_1008_POLICY_VIOLATION
+from cachetools import TTLCache
 from websockets.client import WebSocketClientProtocol, connect
 from websockets.exceptions import (
     ConnectionClosed,
@@ -304,6 +299,8 @@ class PrefectCloudEventSubscriber:
         )
         self._websocket = None
         self._reconnection_attempts = reconnection_attempts
+        if self._reconnection_attempts < 0:
+            raise ValueError("reconnection_attempts must be a non-negative integer")
 
     async def __aenter__(self) -> "PrefectCloudEventSubscriber":
         # Don't handle any errors in the initial connection, because these are most
@@ -333,19 +330,18 @@ class PrefectCloudEventSubscriber:
             message: Dict[str, Any] = orjson.loads(await self._websocket.recv())
             logger.debug("  auth result %s", message)
             assert message["type"] == "auth_success", message.get("reason", "")
-        except (AssertionError, ConnectionClosedError) as e:
-            if isinstance(e, AssertionError) or e.code == WS_1008_POLICY_VIOLATION:
-                if isinstance(e, AssertionError):
-                    reason = e.args[0]
-                elif isinstance(e, ConnectionClosedError):
-                    reason = e.reason
-
-                raise Exception(
-                    "Unable to authenticate to the event stream. Please ensure the "
-                    "provided api_key you are using is valid for this environment. "
-                    f"Reason: {reason}"
-                ) from e
-            raise
+        except AssertionError as e:
+            raise Exception(
+                "Unable to authenticate to the event stream. Please ensure the "
+                "provided api_key you are using is valid for this environment. "
+                f"Reason: {e.args[0]}"
+            )
+        except ConnectionClosedError as e:
+            raise Exception(
+                "Unable to authenticate to the event stream. Please ensure the "
+                "provided api_key you are using is valid for this environment. "
+                f"Reason: {e.reason}"
+            ) from e
 
         from prefect.events.filters import EventOccurredFilter
 
@@ -374,7 +370,8 @@ class PrefectCloudEventSubscriber:
         return self
 
     async def __anext__(self) -> Event:
-        for i in range(self._reconnection_attempts + 1):
+        assert self._reconnection_attempts >= 0
+        for i in range(self._reconnection_attempts + 1):  # pragma: no branch
             try:
                 # If we're here and the websocket is None, then we've had a failure in a
                 # previous reconnection attempt.

prefect/events/filters.py

@@ -4,8 +4,10 @@ from uuid import UUID
 import pendulum
 
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
-from prefect.events.schemas import Event, Resource, ResourceSpecification
-from prefect.server.utilities.schemas import DateTimeTZ, PrefectBaseModel
+from prefect._internal.schemas.bases import PrefectBaseModel
+from prefect._internal.schemas.fields import DateTimeTZ
+
+from .schemas.events import Event, Resource, ResourceSpecification
 
 if HAS_PYDANTIC_V2:
     from pydantic.v1 import Field
@@ -13,12 +15,9 @@ else:
     from pydantic import Field
 
 
-class EventDataFilter(PrefectBaseModel):
+class EventDataFilter(PrefectBaseModel, extra="forbid"):
     """A base class for filtering event data."""
 
-    class Config:
-        extra = "forbid"
-
     def get_filters(self) -> List["EventDataFilter"]:
         return [
             filter

prefect/events/related.py

@@ -17,7 +17,7 @@ from uuid import UUID
 import pendulum
 from pendulum.datetime import DateTime
 
-from .schemas import RelatedResource
+from .schemas.events import RelatedResource
 
 if TYPE_CHECKING:
     from prefect._internal.schemas.bases import ObjectBaseModel

prefect/events/schemas/__init__.py

@@ -0,0 +1,5 @@
+# TODO: these are just for backward compatibility, can can be removed in the future
+
+from .deployment_triggers import DeploymentTrigger
+
+__all__ = ["DeploymentTrigger"]

prefect/events/schemas/automations.py

@@ -0,0 +1,303 @@
+import abc
+from datetime import timedelta
+from enum import Enum
+from typing import (
+    Any,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Union,
+)
+from uuid import UUID
+
+from typing_extensions import TypeAlias
+
+from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect._internal.schemas.validators import validate_trigger_within
+
+if HAS_PYDANTIC_V2:
+    from pydantic.v1 import Field, root_validator, validator
+    from pydantic.v1.fields import ModelField
+else:
+    from pydantic import Field, root_validator, validator
+    from pydantic.fields import ModelField
+
+from prefect._internal.schemas.bases import PrefectBaseModel
+from prefect.events.actions import ActionTypes
+from prefect.utilities.collections import AutoEnum
+
+from .events import ResourceSpecification
+
+
+class Posture(AutoEnum):
+    Reactive = "Reactive"
+    Proactive = "Proactive"
+    Metric = "Metric"
+
+
+class Trigger(PrefectBaseModel, abc.ABC, extra="ignore"):
+    """
+    Base class describing a set of criteria that must be satisfied in order to trigger
+    an automation.
+    """
+
+    type: str
+
+
+class ResourceTrigger(Trigger, abc.ABC):
+    """
+    Base class for triggers that may filter by the labels of resources.
+    """
+
+    type: str
+
+    match: ResourceSpecification = Field(
+        default_factory=lambda: ResourceSpecification(__root__={}),
+        description="Labels for resources which this trigger will match.",
+    )
+    match_related: ResourceSpecification = Field(
+        default_factory=lambda: ResourceSpecification(__root__={}),
+        description="Labels for related resources which this trigger will match.",
+    )
+
+
+class EventTrigger(ResourceTrigger):
+    """
+    A trigger that fires based on the presence or absence of events within a given
+    period of time.
+    """
+
+    type: Literal["event"] = "event"
+
+    after: Set[str] = Field(
+        default_factory=set,
+        description=(
+            "The event(s) which must first been seen to fire this trigger.  If "
+            "empty, then fire this trigger immediately.  Events may include "
+            "trailing wildcards, like `prefect.flow-run.*`"
+        ),
+    )
+    expect: Set[str] = Field(
+        default_factory=set,
+        description=(
+            "The event(s) this trigger is expecting to see.  If empty, this "
+            "trigger will match any event.  Events may include trailing wildcards, "
+            "like `prefect.flow-run.*`"
+        ),
+    )
+
+    for_each: Set[str] = Field(
+        default_factory=set,
+        description=(
+            "Evaluate the trigger separately for each distinct value of these labels "
+            "on the resource.  By default, labels refer to the primary resource of the "
+            "triggering event.  You may also refer to labels from related "
+            "resources by specifying `related:<role>:<label>`.  This will use the "
+            "value of that label for the first related resource in that role.  For "
+            'example, `"for_each": ["related:flow:prefect.resource.id"]` would '
+            "evaluate the trigger for each flow."
+        ),
+    )
+    posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]
+        ...,
+        description=(
+            "The posture of this trigger, either Reactive or Proactive.  Reactive "
+            "triggers respond to the _presence_ of the expected events, while "
+            "Proactive triggers respond to the _absence_ of those expected events."
+        ),
+    )
+    threshold: int = Field(
+        1,
+        description=(
+            "The number of events required for this trigger to fire (for "
+            "Reactive triggers), or the number of events expected (for Proactive "
+            "triggers)"
+        ),
+    )
+    within: timedelta = Field(
+        timedelta(0),
+        minimum=0.0,
+        exclusiveMinimum=False,
+        description=(
+            "The time period over which the events must occur.  For Reactive triggers, "
+            "this may be as low as 0 seconds, but must be at least 10 seconds for "
+            "Proactive triggers"
+        ),
+    )
+
+    @validator("within")
+    def enforce_minimum_within(
+        cls, value: timedelta, values, config, field: ModelField
+    ):
+        return validate_trigger_within(value, field)
+
+    @root_validator(skip_on_failure=True)
+    def enforce_minimum_within_for_proactive_triggers(cls, values: Dict[str, Any]):
+        posture: Optional[Posture] = values.get("posture")
+        within: Optional[timedelta] = values.get("within")
+
+        if posture == Posture.Proactive:
+            if not within or within == timedelta(0):
+                values["within"] = timedelta(seconds=10.0)
+            elif within < timedelta(seconds=10.0):
+                raise ValueError(
+                    "The minimum within for Proactive triggers is 10 seconds"
+                )
+
+        return values
+
+
+class MetricTriggerOperator(Enum):
+    LT = "<"
+    LTE = "<="
+    GT = ">"
+    GTE = ">="
+
+
+class PrefectMetric(Enum):
+    lateness = "lateness"
+    duration = "duration"
+    successes = "successes"
+
+
+class MetricTriggerQuery(PrefectBaseModel):
+    """Defines a subset of the Trigger subclass, which is specific
+    to Metric automations, that specify the query configurations
+    and breaching conditions for the Automation"""
+
+    name: PrefectMetric = Field(
+        ...,
+        description="The name of the metric to query.",
+    )
+    threshold: float = Field(
+        ...,
+        description=(
+            "The threshold value against which we'll compare " "the query result."
+        ),
+    )
+    operator: MetricTriggerOperator = Field(
+        ...,
+        description=(
+            "The comparative operator (LT / LTE / GT / GTE) used to compare "
+            "the query result against the threshold value."
+        ),
+    )
+    range: timedelta = Field(
+        timedelta(seconds=300),  # defaults to 5 minutes
+        minimum=300.0,
+        exclusiveMinimum=False,
+        description=(
+            "The lookback duration (seconds) for a metric query. This duration is "
+            "used to determine the time range over which the query will be executed. "
+            "The minimum value is 300 seconds (5 minutes)."
+        ),
+    )
+    firing_for: timedelta = Field(
+        timedelta(seconds=300),  # defaults to 5 minutes
+        minimum=300.0,
+        exclusiveMinimum=False,
+        description=(
+            "The duration (seconds) for which the metric query must breach "
+            "or resolve continuously before the state is updated and the "
+            "automation is triggered. "
+            "The minimum value is 300 seconds (5 minutes)."
+        ),
+    )
+
+
+class MetricTrigger(ResourceTrigger):
+    """
+    A trigger that fires based on the results of a metric query.
+    """
+
+    type: Literal["metric"] = "metric"
+
+    posture: Literal[Posture.Metric] = Field(  # type: ignore[valid-type]
+        Posture.Metric,
+        description="Periodically evaluate the configured metric query.",
+    )
+
+    metric: MetricTriggerQuery = Field(
+        ...,
+        description="The metric query to evaluate for this trigger. ",
+    )
+
+
+class CompositeTrigger(Trigger, abc.ABC):
+    """
+    Requires some number of triggers to have fired within the given time period.
+    """
+
+    type: Literal["compound", "sequence"]
+    triggers: List["TriggerTypes"]
+    within: Optional[timedelta]
+
+
+class CompoundTrigger(CompositeTrigger):
+    """A composite trigger that requires some number of triggers to have
+    fired within the given time period"""
+
+    type: Literal["compound"] = "compound"
+    require: Union[int, Literal["any", "all"]]
+
+    @root_validator
+    def validate_require(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        require = values.get("require")
+
+        if isinstance(require, int):
+            if require < 1:
+                raise ValueError("required must be at least 1")
+            if require > len(values["triggers"]):
+                raise ValueError(
+                    "required must be less than or equal to the number of triggers"
+                )
+
+        return values
+
+
+class SequenceTrigger(CompositeTrigger):
+    """A composite trigger that requires some number of triggers to have fired
+    within the given time period in a specific order"""
+
+    type: Literal["sequence"] = "sequence"
+
+
+TriggerTypes: TypeAlias = Union[
+    EventTrigger, MetricTrigger, CompoundTrigger, SequenceTrigger
+]
+"""The union of all concrete trigger types that a user may actually create"""
+
+CompoundTrigger.update_forward_refs()
+SequenceTrigger.update_forward_refs()
+
+
+class Automation(PrefectBaseModel, extra="ignore"):
+    """Defines an action a user wants to take when a certain number of events
+    do or don't happen to the matching resources"""
+
+    name: str = Field(..., description="The name of this automation")
+    description: str = Field("", description="A longer description of this automation")
+
+    enabled: bool = Field(True, description="Whether this automation will be evaluated")
+
+    trigger: TriggerTypes = Field(
+        ...,
+        description=(
+            "The criteria for which events this Automation covers and how it will "
+            "respond to the presence or absence of those events"
+        ),
+    )
+
+    actions: List[ActionTypes] = Field(
+        ...,
+        description="The actions to perform when this Automation triggers",
+    )
+    owner_resource: Optional[str] = Field(
+        default=None, description="The owning resource of this automation"
+    )
+
+
+class ExistingAutomation(Automation):
+    id: UUID = Field(..., description="The ID of this automation")