prefect-client 2.17.1__py3-none-any.whl → 2.18.1__py3-none-any.whl

prefect/events/schemas/automations.py

@@ -1,4 +1,5 @@
 import abc
+import textwrap
 from datetime import timedelta
 from enum import Enum
 from typing import (
@@ -9,23 +10,24 @@ from typing import (
     Optional,
     Set,
     Union,
+    cast,
 )
 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 import Field, PrivateAttr, root_validator, validator
     from pydantic.v1.fields import ModelField
 else:
-    from pydantic import Field, root_validator, validator
-    from pydantic.fields import ModelField
+    from pydantic import Field, PrivateAttr, root_validator, validator  # type: ignore
+    from pydantic.fields import ModelField  # type: ignore
 
 from prefect._internal.schemas.bases import PrefectBaseModel
-from prefect.events.actions import ActionTypes
+from prefect._internal.schemas.validators import validate_trigger_within
+from prefect.events.actions import ActionTypes, RunDeployment
 from prefect.utilities.collections import AutoEnum
 
 from .events import ResourceSpecification
@@ -45,6 +47,54 @@ class Trigger(PrefectBaseModel, abc.ABC, extra="ignore"):
 
     type: str
 
+    @abc.abstractmethod
+    def describe_for_cli(self, indent: int = 0) -> str:
+        """Return a human-readable description of this trigger for the CLI"""
+
+    # The following allows the regular Trigger class to be used when serving or
+    # deploying flows, analogous to how the Deployment*Trigger classes work
+
+    _deployment_id: Optional[UUID] = PrivateAttr(default=None)
+
+    def set_deployment_id(self, deployment_id: UUID):
+        self._deployment_id = deployment_id
+
+    def owner_resource(self) -> Optional[str]:
+        return f"prefect.deployment.{self._deployment_id}"
+
+    def actions(self) -> List[ActionTypes]:
+        assert self._deployment_id
+        return [
+            RunDeployment(
+                source="selected",
+                deployment_id=self._deployment_id,
+                parameters=getattr(self, "parameters", None),
+                job_variables=getattr(self, "job_variables", None),
+            )
+        ]
+
+    def as_automation(self) -> "AutomationCore":
+        assert self._deployment_id
+
+        trigger: TriggerTypes = cast(TriggerTypes, self)
+
+        # This is one of the Deployment*Trigger classes, so translate it over to a
+        # plain Trigger
+        if hasattr(self, "trigger_type"):
+            trigger = self.trigger_type(**self.dict())
+
+        return AutomationCore(
+            name=(
+                getattr(self, "name", None)
+                or f"Automation for deployment {self._deployment_id}"
+            ),
+            description="",
+            enabled=getattr(self, "enabled", True),
+            trigger=trigger,
+            actions=self.actions(),
+            owner_resource=self.owner_resource(),
+        )
+
 
 class ResourceTrigger(Trigger, abc.ABC):
     """
@@ -101,7 +151,7 @@ class EventTrigger(ResourceTrigger):
         ),
     )
     posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]
-        ...,
+        Posture.Reactive,
         description=(
             "The posture of this trigger, either Reactive or Proactive.  Reactive "
             "triggers respond to the _presence_ of the expected events, while "
@@ -148,6 +198,28 @@ class EventTrigger(ResourceTrigger):
 
         return values
 
+    def describe_for_cli(self, indent: int = 0) -> str:
+        """Return a human-readable description of this trigger for the CLI"""
+        if self.posture == Posture.Reactive:
+            return textwrap.indent(
+                "\n".join(
+                    [
+                        f"Reactive: expecting {self.threshold} of {self.expect}",
+                    ],
+                ),
+                prefix="  " * indent,
+            )
+        else:
+            return textwrap.indent(
+                "\n".join(
+                    [
+                        f"Proactive: expecting {self.threshold} {self.expect} event "
+                        f"within {self.within}",
+                    ],
+                ),
+                prefix="  " * indent,
+            )
+
 
 class MetricTriggerOperator(Enum):
     LT = "<"
@@ -224,6 +296,18 @@ class MetricTrigger(ResourceTrigger):
         description="The metric query to evaluate for this trigger. ",
     )
 
+    def describe_for_cli(self, indent: int = 0) -> str:
+        """Return a human-readable description of this trigger for the CLI"""
+        m = self.metric
+        return textwrap.indent(
+            "\n".join(
+                [
+                    f"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}",
+                ]
+            ),
+            prefix="  " * indent,
+        )
+
 
 class CompositeTrigger(Trigger, abc.ABC):
     """
@@ -256,6 +340,23 @@ class CompoundTrigger(CompositeTrigger):
 
         return values
 
+    def describe_for_cli(self, indent: int = 0) -> str:
+        """Return a human-readable description of this trigger for the CLI"""
+        return textwrap.indent(
+            "\n".join(
+                [
+                    f"{str(self.require).capitalize()} of:",
+                    "\n".join(
+                        [
+                            trigger.describe_for_cli(indent=indent + 1)
+                            for trigger in self.triggers
+                        ]
+                    ),
+                ]
+            ),
+            prefix="  " * indent,
+        )
+
 
 class SequenceTrigger(CompositeTrigger):
     """A composite trigger that requires some number of triggers to have fired
@@ -263,6 +364,23 @@ class SequenceTrigger(CompositeTrigger):
 
     type: Literal["sequence"] = "sequence"
 
+    def describe_for_cli(self, indent: int = 0) -> str:
+        """Return a human-readable description of this trigger for the CLI"""
+        return textwrap.indent(
+            "\n".join(
+                [
+                    "In this order:",
+                    "\n".join(
+                        [
+                            trigger.describe_for_cli(indent=indent + 1)
+                            for trigger in self.triggers
+                        ]
+                    ),
+                ]
+            ),
+            prefix="  " * indent,
+        )
+
 
 TriggerTypes: TypeAlias = Union[
     EventTrigger, MetricTrigger, CompoundTrigger, SequenceTrigger
@@ -273,7 +391,7 @@ CompoundTrigger.update_forward_refs()
 SequenceTrigger.update_forward_refs()
 
 
-class Automation(PrefectBaseModel, extra="ignore"):
+class AutomationCore(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"""
 
@@ -310,5 +428,5 @@ class Automation(PrefectBaseModel, extra="ignore"):
     )
 
 
-class ExistingAutomation(Automation):
+class Automation(AutomationCore):
     id: UUID = Field(..., description="The ID of this automation")

prefect/events/schemas/deployment_triggers.py

@@ -11,13 +11,11 @@ create them from YAML.
 
 import abc
 import textwrap
-import warnings
 from datetime import timedelta
 from typing import (
     Any,
     Dict,
     List,
-    Literal,
     Optional,
     Set,
     Union,
@@ -26,38 +24,25 @@ from uuid import UUID
 
 from typing_extensions import TypeAlias
 
-from prefect._internal.compatibility.deprecated import deprecated_class
 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, PrivateAttr, root_validator, validator
-    from pydantic.v1.fields import ModelField
+    from pydantic.v1 import Field, PrivateAttr
 else:
-    from pydantic import Field, PrivateAttr, root_validator, validator
-    from pydantic.fields import ModelField
-
-from prefect._internal.compatibility.experimental import (
-    EXPERIMENTAL_WARNING,
-    PREFECT_EXPERIMENTAL_WARN,
-    ExperimentalFeature,
-    experiment_enabled,
-)
+    from pydantic import Field, PrivateAttr  # type: ignore
+
+from prefect._internal.compatibility.deprecated import deprecated_class
 from prefect._internal.schemas.bases import PrefectBaseModel
-from prefect.events.actions import RunDeployment
-from prefect.settings import (
-    PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INFRA_OVERRIDES,
-)
+from prefect.events.actions import ActionTypes, RunDeployment
 
 from .automations import (
-    Automation,
+    AutomationCore,
     CompoundTrigger,
     EventTrigger,
     MetricTrigger,
     MetricTriggerQuery,
     Posture,
     SequenceTrigger,
-    Trigger,
     TriggerTypes,
 )
 from .events import ResourceSpecification
@@ -77,11 +62,7 @@ class BaseDeploymentTrigger(PrefectBaseModel, abc.ABC, extra="ignore"):
     description: str = Field("", description="A longer description of this automation")
     enabled: bool = Field(True, description="Whether this automation will be evaluated")
 
-    # Fields from Trigger
-
-    type: str
-
-    # Fields from Deployment
+    # Fields from the RunDeployment action
 
     parameters: Optional[Dict[str, Any]] = Field(
         None,
@@ -97,256 +78,37 @@ class BaseDeploymentTrigger(PrefectBaseModel, abc.ABC, extra="ignore"):
             "deployment's default job variables"
         ),
     )
-    _deployment_id: Optional[UUID] = PrivateAttr(default=None)
-
-    def set_deployment_id(self, deployment_id: UUID):
-        self._deployment_id = deployment_id
-
-    def owner_resource(self) -> Optional[str]:
-        return f"prefect.deployment.{self._deployment_id}"
-
-    def actions(self) -> List[RunDeployment]:
-        if self.job_variables is not None and experiment_enabled(
-            "flow_run_infra_overrides"
-        ):
-            if (
-                PREFECT_EXPERIMENTAL_WARN
-                and PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INFRA_OVERRIDES
-            ):
-                warnings.warn(
-                    EXPERIMENTAL_WARNING.format(
-                        feature="Flow run job variables",
-                        group="flow_run_infra_overrides",
-                        help="To use this feature, update your workers to Prefect 2.16.4 or later. ",
-                    ),
-                    ExperimentalFeature,
-                    stacklevel=3,
-                )
-        if not experiment_enabled("flow_run_infra_overrides"):
-            # nullify job_variables if the flag is disabled
-            self.job_variables = None
-
-        assert self._deployment_id
-        return [
-            RunDeployment(
-                parameters=self.parameters,
-                deployment_id=self._deployment_id,
-                job_variables=self.job_variables,
-            )
-        ]
-
-    def as_automation(self) -> Automation:
-        if not self.name:
-            raise ValueError("name is required")
-
-        return Automation(
-            name=self.name,
-            description=self.description,
-            enabled=self.enabled,
-            trigger=self.as_trigger(),
-            actions=self.actions(),
-            owner_resource=self.owner_resource(),
-        )
-
-    @abc.abstractmethod
-    def as_trigger(self) -> Trigger:
-        ...
-
-
-class DeploymentResourceTrigger(BaseDeploymentTrigger, abc.ABC):
-    """
-    Base class for triggers that may filter by the labels of resources.
-    """
-
-    type: str
-
-    match: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification.parse_obj({}),
-        description="Labels for resources which this trigger will match.",
-    )
-    match_related: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification.parse_obj({}),
-        description="Labels for related resources which this trigger will match.",
-    )
 
 
-class DeploymentEventTrigger(DeploymentResourceTrigger):
+class DeploymentEventTrigger(BaseDeploymentTrigger, EventTrigger):
     """
     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]
-        Posture.Reactive,
-        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
-
-    def as_trigger(self) -> Trigger:
-        return EventTrigger(
-            match=self.match,
-            match_related=self.match_related,
-            after=self.after,
-            expect=self.expect,
-            for_each=self.for_each,
-            posture=self.posture,
-            threshold=self.threshold,
-            within=self.within,
-        )
+    trigger_type = EventTrigger
 
 
-class DeploymentMetricTrigger(DeploymentResourceTrigger):
+class DeploymentMetricTrigger(BaseDeploymentTrigger, MetricTrigger):
     """
     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. ",
-    )
-
-    def as_trigger(self) -> Trigger:
-        return MetricTrigger(
-            match=self.match,
-            match_related=self.match_related,
-            posture=self.posture,
-            metric=self.metric,
-            job_variables=self.job_variables,
-        )
-
-
-class DeploymentCompositeTrigger(BaseDeploymentTrigger, 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]
+    trigger_type = MetricTrigger
 
 
-class DeploymentCompoundTrigger(DeploymentCompositeTrigger):
+class DeploymentCompoundTrigger(BaseDeploymentTrigger, CompoundTrigger):
     """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
-
-    def as_trigger(self) -> Trigger:
-        return CompoundTrigger(
-            require=self.require,
-            triggers=self.triggers,
-            within=self.within,
-            job_variables=self.job_variables,
-        )
+    trigger_type = CompoundTrigger
 
 
-class DeploymentSequenceTrigger(DeploymentCompositeTrigger):
+class DeploymentSequenceTrigger(BaseDeploymentTrigger, SequenceTrigger):
     """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"
-
-    def as_trigger(self) -> Trigger:
-        return SequenceTrigger(
-            triggers=self.triggers,
-            within=self.within,
-            job_variables=self.job_variables,
-        )
+    trigger_type = SequenceTrigger
 
 
 # Concrete deployment trigger types
@@ -480,10 +242,13 @@ class DeploymentTrigger(PrefectBaseModel):
         ),
     )
 
-    def as_automation(self) -> Automation:
+    def as_automation(self) -> AutomationCore:
         assert self.name
 
+        trigger: TriggerTypes
+
         if self.posture == Posture.Metric:
+            assert self.metric
             trigger = MetricTrigger(
                 type="metric",
                 match=self.match,
@@ -503,7 +268,7 @@ class DeploymentTrigger(PrefectBaseModel):
                 within=self.within,
             )
 
-        return Automation(
+        return AutomationCore(
             name=self.name,
             description=self.description,
             enabled=self.enabled,
@@ -518,32 +283,13 @@ class DeploymentTrigger(PrefectBaseModel):
     def owner_resource(self) -> Optional[str]:
         return f"prefect.deployment.{self._deployment_id}"
 
-    def actions(self) -> List[RunDeployment]:
-        if self.job_variables is not None and experiment_enabled(
-            "flow_run_infra_overrides"
-        ):
-            if (
-                PREFECT_EXPERIMENTAL_WARN
-                and PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INFRA_OVERRIDES
-            ):
-                warnings.warn(
-                    EXPERIMENTAL_WARNING.format(
-                        feature="Flow run job variables",
-                        group="flow_run_infra_overrides",
-                        help="To use this feature, update your workers to Prefect 2.16.4 or later. ",
-                    ),
-                    ExperimentalFeature,
-                    stacklevel=3,
-                )
-        if not experiment_enabled("flow_run_infra_overrides"):
-            # nullify job_variables if the flag is disabled
-            self.job_variables = None
-
+    def actions(self) -> List[ActionTypes]:
         assert self._deployment_id
         return [
             RunDeployment(
-                parameters=self.parameters,
+                source="selected",
                 deployment_id=self._deployment_id,
+                parameters=self.parameters,
                 job_variables=self.job_variables,
             )
         ]

prefect/events/schemas/events.py

@@ -15,9 +15,14 @@ from typing import (
 from uuid import UUID, uuid4
 
 import pendulum
-from pydantic import Field, root_validator, validator
 
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
+
+if HAS_PYDANTIC_V2:
+    from pydantic.v1 import Field, root_validator, validator
+else:
+    from pydantic import Field, root_validator, validator  # type: ignore
+
 from prefect._internal.schemas.bases import PrefectBaseModel
 from prefect._internal.schemas.fields import DateTimeTZ
 from prefect.logging import get_logger
@@ -26,11 +31,6 @@ from prefect.settings import (
     PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES,
 )
 
-if HAS_PYDANTIC_V2:
-    from pydantic.v1 import Field, root_validator, validator
-else:
-    from pydantic import Field, root_validator, validator
-
 from .labelling import Labelled
 
 logger = get_logger(__name__)
@@ -128,7 +128,7 @@ class Event(PrefectBaseModel):
         description="The client-provided identifier of this event",
     )
     follows: Optional[UUID] = Field(
-        None,
+        default=None,
         description=(
             "The ID of an event that is known to have occurred prior to this one. "
             "If set, this may be used to establish a more precise ordering of causally-"

prefect/events/utilities.py

@@ -9,6 +9,7 @@ from prefect._internal.schemas.fields import DateTimeTZ
 from .clients import (
     AssertingEventsClient,
     PrefectCloudEventsClient,
+    PrefectEphemeralEventsClient,
     PrefectEventsClient,
 )
 from .schemas.events import Event, RelatedResource
@@ -53,13 +54,14 @@ def emit_event(
         AssertingEventsClient,
         PrefectCloudEventsClient,
         PrefectEventsClient,
+        PrefectEphemeralEventsClient,
     ]
     worker_instance = EventsWorker.instance()
 
     if worker_instance.client_type not in operational_clients:
         return None
 
-    event_kwargs = {
+    event_kwargs: Dict[str, Any] = {
         "event": event,
         "resource": resource,
     }