prefect-client 2.16.8__py3-none-any.whl → 2.17.0__py3-none-any.whl

prefect/events/actions.py

@@ -19,10 +19,17 @@ class Action(PrefectBaseModel):
     type: str
 
 
+class DoNothing(Action):
+    """Do nothing, which may be helpful for testing automations"""
+
+    type: Literal["do-nothing"] = "do-nothing"
+
+
 class RunDeployment(Action):
     """Run the given deployment with the given parameters"""
 
     type: Literal["run-deployment"] = "run-deployment"
+
     source: Literal["selected"] = "selected"
     parameters: Optional[Dict[str, Any]] = Field(
         None,
@@ -32,12 +39,20 @@ class RunDeployment(Action):
         ),
     )
     deployment_id: UUID = Field(..., description="The identifier of the deployment")
+    job_variables: Optional[Dict[str, Any]] = Field(
+        None,
+        description=(
+            "Job variables to pass to the run, or None to use the "
+            "deployment's default job variables"
+        ),
+    )
 
 
 class SendNotification(Action):
     """Send a notification with the given parameters"""
 
     type: Literal["send-notification"] = "send-notification"
+
     block_document_id: UUID = Field(
         ..., description="The identifier of the notification block"
     )
@@ -45,4 +60,4 @@ class SendNotification(Action):
     subject: Optional[str] = Field(None, description="Notification subject")
 
 
-ActionTypes = Union[RunDeployment, SendNotification]
+ActionTypes = Union[DoNothing, RunDeployment, SendNotification]

prefect/events/clients.py

@@ -17,6 +17,7 @@ from uuid import UUID
 import orjson
 import pendulum
 from cachetools import TTLCache
+from typing_extensions import Self
 from websockets.client import WebSocketClientProtocol, connect
 from websockets.exceptions import (
     ConnectionClosed,
@@ -118,8 +119,8 @@ def _get_api_url_and_key(
     return api_url, api_key
 
 
-class PrefectCloudEventsClient(EventsClient):
-    """A Prefect Events client that streams Events to a Prefect Cloud Workspace"""
+class PrefectEventsClient(EventsClient):
+    """A Prefect Events client that streams events to a Prefect server"""
 
     _websocket: Optional[WebSocketClientProtocol]
     _unconfirmed_events: List[Event]
@@ -127,37 +128,36 @@ class PrefectCloudEventsClient(EventsClient):
     def __init__(
         self,
         api_url: str = None,
-        api_key: str = None,
         reconnection_attempts: int = 10,
         checkpoint_every: int = 20,
     ):
         """
         Args:
-            api_url: The base URL for a Prefect Cloud workspace
-            api_key: The API of an actor with the manage_events scope
+            api_url: The base URL for a Prefect server
             reconnection_attempts: When the client is disconnected, how many times
                 the client should attempt to reconnect
             checkpoint_every: How often the client should sync with the server to
                 confirm receipt of all previously sent events
         """
-        api_url, api_key = _get_api_url_and_key(api_url, api_key)
+        api_url = api_url or PREFECT_API_URL.value()
+        if not api_url:
+            raise ValueError(
+                "api_url must be provided or set in the Prefect configuration"
+            )
 
-        socket_url = (
+        self._events_socket_url = (
             api_url.replace("https://", "wss://")
             .replace("http://", "ws://")
             .rstrip("/")
+            + "/events/in"
         )
-
-        self._connect = connect(
-            socket_url + "/events/in",
-            extra_headers={"Authorization": f"bearer {api_key}"},
-        )
+        self._connect = connect(self._events_socket_url)
         self._websocket = None
         self._reconnection_attempts = reconnection_attempts
         self._unconfirmed_events = []
         self._checkpoint_every = checkpoint_every
 
-    async def __aenter__(self) -> "PrefectCloudEventsClient":
+    async def __aenter__(self) -> Self:
         # Don't handle any errors in the initial connection, because these are most
         # likely a permission or configuration issue that should propagate
         await super().__aenter__()
@@ -238,6 +238,38 @@ class PrefectCloudEventsClient(EventsClient):
                     await asyncio.sleep(1)
 
 
+class PrefectCloudEventsClient(PrefectEventsClient):
+    """A Prefect Events client that streams events to a Prefect Cloud Workspace"""
+
+    def __init__(
+        self,
+        api_url: str = None,
+        api_key: str = None,
+        reconnection_attempts: int = 10,
+        checkpoint_every: int = 20,
+    ):
+        """
+        Args:
+            api_url: The base URL for a Prefect Cloud workspace
+            api_key: The API of an actor with the manage_events scope
+            reconnection_attempts: When the client is disconnected, how many times
+                the client should attempt to reconnect
+            checkpoint_every: How often the client should sync with the server to
+                confirm receipt of all previously sent events
+        """
+        api_url, api_key = _get_api_url_and_key(api_url, api_key)
+        super().__init__(
+            api_url=api_url,
+            reconnection_attempts=reconnection_attempts,
+            checkpoint_every=checkpoint_every,
+        )
+
+        self._connect = connect(
+            self._events_socket_url,
+            extra_headers={"Authorization": f"bearer {api_key}"},
+        )
+
+
 SEEN_EVENTS_SIZE = 500_000
 SEEN_EVENTS_TTL = 120
 

prefect/events/filters.py

@@ -6,18 +6,21 @@ import pendulum
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect._internal.schemas.bases import PrefectBaseModel
 from prefect._internal.schemas.fields import DateTimeTZ
+from prefect.utilities.collections import AutoEnum
 
 from .schemas.events import Event, Resource, ResourceSpecification
 
 if HAS_PYDANTIC_V2:
-    from pydantic.v1 import Field
+    from pydantic.v1 import Field, PrivateAttr
 else:
-    from pydantic import Field
+    from pydantic import Field, PrivateAttr
 
 
 class EventDataFilter(PrefectBaseModel, extra="forbid"):
     """A base class for filtering event data."""
 
+    _top_level_filter: "EventFilter | None" = PrivateAttr(None)
+
     def get_filters(self) -> List["EventDataFilter"]:
         return [
             filter
@@ -103,6 +106,10 @@ class EventResourceFilter(EventDataFilter):
     labels: Optional[ResourceSpecification] = Field(
         None, description="Only include events for resources with these labels"
     )
+    distinct: bool = Field(
+        False,
+        description="Only include events for distinct resources",
+    )
 
     def includes(self, event: Event) -> bool:
         if self.id:
@@ -189,6 +196,11 @@ class EventIDFilter(EventDataFilter):
         return True
 
 
+class EventOrder(AutoEnum):
+    ASC = "ASC"
+    DESC = "DESC"
+
+
 class EventFilter(EventDataFilter):
     occurred: EventOccurredFilter = Field(
         default_factory=EventOccurredFilter,
@@ -211,3 +223,8 @@ class EventFilter(EventDataFilter):
         default_factory=EventIDFilter,
         description="Filter criteria for the events' ID",
     )
+
+    order: EventOrder = Field(
+        EventOrder.DESC,
+        description="The order to return filtered events",
+    )

prefect/events/related.py

@@ -31,8 +31,8 @@ RESOURCE_CACHE: RelatedResourceCache = {}
 
 def tags_as_related_resources(tags: Iterable[str]) -> List[RelatedResource]:
     return [
-        RelatedResource(
-            __root__={
+        RelatedResource.parse_obj(
+            {
                 "prefect.resource.id": f"prefect.tag.{tag}",
                 "prefect.resource.role": "tag",
             }
@@ -44,8 +44,8 @@ def tags_as_related_resources(tags: Iterable[str]) -> List[RelatedResource]:
 def object_as_related_resource(kind: str, role: str, object: Any) -> RelatedResource:
     resource_id = f"prefect.{kind}.{object.id}"
 
-    return RelatedResource(
-        __root__={
+    return RelatedResource.parse_obj(
+        {
             "prefect.resource.id": resource_id,
             "prefect.resource.role": role,
             "prefect.resource.name": object.name,

prefect/events/schemas/automations.py

@@ -54,11 +54,11 @@ class ResourceTrigger(Trigger, abc.ABC):
     type: str
 
     match: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for resources which this trigger will match.",
     )
     match_related: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for related resources which this trigger will match.",
     )
 
@@ -294,6 +294,17 @@ class Automation(PrefectBaseModel, extra="ignore"):
         ...,
         description="The actions to perform when this Automation triggers",
     )
+
+    actions_on_trigger: List[ActionTypes] = Field(
+        default_factory=list,
+        description="The actions to perform when an Automation goes into a triggered state",
+    )
+
+    actions_on_resolve: List[ActionTypes] = Field(
+        default_factory=list,
+        description="The actions to perform when an Automation goes into a resolving state",
+    )
+
     owner_resource: Optional[str] = Field(
         default=None, description="The owning resource of this automation"
     )

prefect/events/schemas/deployment_triggers.py

@@ -11,6 +11,7 @@ create them from YAML.
 
 import abc
 import textwrap
+import warnings
 from datetime import timedelta
 from typing import (
     Any,
@@ -36,8 +37,17 @@ 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 prefect._internal.schemas.bases import PrefectBaseModel
 from prefect.events.actions import RunDeployment
+from prefect.settings import (
+    PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INFRA_OVERRIDES,
+)
 
 from .automations import (
     Automation,
@@ -80,7 +90,13 @@ class BaseDeploymentTrigger(PrefectBaseModel, abc.ABC, extra="ignore"):
             "deployment's default parameters"
         ),
     )
-
+    job_variables: Optional[Dict[str, Any]] = Field(
+        None,
+        description=(
+            "Job variables to pass to the deployment, or None to use the "
+            "deployment's default job variables"
+        ),
+    )
     _deployment_id: Optional[UUID] = PrivateAttr(default=None)
 
     def set_deployment_id(self, deployment_id: UUID):
@@ -90,11 +106,32 @@ class BaseDeploymentTrigger(PrefectBaseModel, abc.ABC, extra="ignore"):
         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,
             )
         ]
 
@@ -124,11 +161,11 @@ class DeploymentResourceTrigger(BaseDeploymentTrigger, abc.ABC):
     type: str
 
     match: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for resources which this trigger will match.",
     )
     match_related: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for related resources which this trigger will match.",
     )
 
@@ -254,6 +291,7 @@ class DeploymentMetricTrigger(DeploymentResourceTrigger):
             match_related=self.match_related,
             posture=self.posture,
             metric=self.metric,
+            job_variables=self.job_variables,
         )
 
 
@@ -293,6 +331,7 @@ class DeploymentCompoundTrigger(DeploymentCompositeTrigger):
             require=self.require,
             triggers=self.triggers,
             within=self.within,
+            job_variables=self.job_variables,
         )
 
 
@@ -306,6 +345,7 @@ class DeploymentSequenceTrigger(DeploymentCompositeTrigger):
         return SequenceTrigger(
             triggers=self.triggers,
             within=self.within,
+            job_variables=self.job_variables,
         )
 
 
@@ -343,15 +383,22 @@ class DeploymentTrigger(PrefectBaseModel):
     )
     description: str = Field("", description="A longer description of this automation")
     enabled: bool = Field(True, description="Whether this automation will be evaluated")
+    job_variables: Optional[Dict[str, Any]] = Field(
+        None,
+        description=(
+            "Job variables to pass to the run, or None to use the "
+            "deployment's default job variables"
+        ),
+    )
 
     # from ResourceTrigger
 
     match: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for resources which this trigger will match.",
     )
     match_related: ResourceSpecification = Field(
-        default_factory=lambda: ResourceSpecification(__root__={}),
+        default_factory=lambda: ResourceSpecification.parse_obj({}),
         description="Labels for related resources which this trigger will match.",
     )
 
@@ -472,10 +519,31 @@ class DeploymentTrigger(PrefectBaseModel):
         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,
             )
         ]

prefect/events/schemas/events.py

@@ -282,4 +282,4 @@ class ResourceSpecification(PrefectBaseModel):
         return len(self.__root__)
 
     def deepcopy(self) -> "ResourceSpecification":
-        return ResourceSpecification(__root__=copy.deepcopy(self.__root__))
+        return ResourceSpecification.parse_obj(copy.deepcopy(self.__root__))

prefect/events/utilities.py

@@ -6,9 +6,13 @@ import pendulum
 
 from prefect._internal.schemas.fields import DateTimeTZ
 
-from .clients import AssertingEventsClient, PrefectCloudEventsClient
+from .clients import (
+    AssertingEventsClient,
+    PrefectCloudEventsClient,
+    PrefectEventsClient,
+)
 from .schemas.events import Event, RelatedResource
-from .worker import EventsWorker, emit_events_to_cloud
+from .worker import EventsWorker, should_emit_events
 
 TIGHT_TIMING = timedelta(minutes=5)
 
@@ -42,10 +46,14 @@ def emit_event(
         The event that was emitted if worker is using a client that emit
         events, otherwise None
     """
-    if not emit_events_to_cloud():
+    if not should_emit_events():
         return None
 
-    operational_clients = [AssertingEventsClient, PrefectCloudEventsClient]
+    operational_clients = [
+        AssertingEventsClient,
+        PrefectCloudEventsClient,
+        PrefectEventsClient,
+    ]
     worker_instance = EventsWorker.instance()
 
     if worker_instance.client_type not in operational_clients:

prefect/events/worker.py

@@ -4,25 +4,41 @@ from typing import Any, Optional, Tuple, Type
 
 from typing_extensions import Self
 
-from prefect._internal.compatibility.experimental import experiment_enabled
 from prefect._internal.concurrency.services import QueueService
-from prefect.settings import PREFECT_API_KEY, PREFECT_API_URL, PREFECT_CLOUD_API_URL
+from prefect.settings import (
+    PREFECT_API_KEY,
+    PREFECT_API_URL,
+    PREFECT_CLOUD_API_URL,
+    PREFECT_EXPERIMENTAL_EVENTS,
+)
 from prefect.utilities.context import temporary_context
 
-from .clients import EventsClient, NullEventsClient, PrefectCloudEventsClient
+from .clients import (
+    EventsClient,
+    NullEventsClient,
+    PrefectCloudEventsClient,
+    PrefectEventsClient,
+)
 from .related import related_resources_from_run_context
 from .schemas.events import Event
 
 
+def should_emit_events() -> bool:
+    return emit_events_to_cloud() or should_emit_events_to_running_server()
+
+
 def emit_events_to_cloud() -> bool:
-    api = PREFECT_API_URL.value()
-    return (
-        experiment_enabled("events_client")
-        and api
-        and api.startswith(PREFECT_CLOUD_API_URL.value())
+    api_url = PREFECT_API_URL.value()
+    return isinstance(api_url, str) and api_url.startswith(
+        PREFECT_CLOUD_API_URL.value()
     )
 
 
+def should_emit_events_to_running_server() -> bool:
+    api_url = PREFECT_API_URL.value()
+    return isinstance(api_url, str) and PREFECT_EXPERIMENTAL_EVENTS
+
+
 class EventsWorker(QueueService[Event]):
     def __init__(
         self, client_type: Type[EventsClient], client_options: Tuple[Tuple[str, Any]]
@@ -67,6 +83,8 @@ class EventsWorker(QueueService[Event]):
                     "api_url": PREFECT_API_URL.value(),
                     "api_key": PREFECT_API_KEY.value(),
                 }
+            elif should_emit_events_to_running_server():
+                client_type = PrefectEventsClient
 
             else:
                 client_type = NullEventsClient

prefect/exceptions.py

@@ -1,19 +1,14 @@
 """
 Prefect-specific exceptions.
 """
+
 import inspect
 import traceback
 from types import ModuleType, TracebackType
 from typing import Callable, Dict, Iterable, List, Optional, Type
 
-from prefect._internal.pydantic import HAS_PYDANTIC_V2
-
-if HAS_PYDANTIC_V2:
-    import pydantic.v1 as pydantic
-else:
-    import pydantic
-
 from httpx._exceptions import HTTPStatusError
+from pydantic import ValidationError
 from rich.traceback import Traceback
 from typing_extensions import Self
 
@@ -182,7 +177,7 @@ class ParameterTypeError(PrefectException):
         super().__init__(msg)
 
     @classmethod
-    def from_validation_error(cls, exc: pydantic.ValidationError) -> Self:
+    def from_validation_error(cls, exc: ValidationError) -> Self:
         bad_params = [f'{err["loc"][0]}: {err["msg"]}' for err in exc.errors()]
         msg = "Flow run received invalid parameters:\n - " + "\n - ".join(bad_params)
         return cls(msg)

prefect/filesystems.py

@@ -270,7 +270,7 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
     basepath: str = Field(
         default=...,
         description="Default path for this block to write to.",
-        example="s3://my-bucket/my-folder/",
+        examples=["s3://my-bucket/my-folder/"],
     )
     settings: Dict[str, Any] = Field(
         default_factory=dict,
@@ -451,19 +451,19 @@ class S3(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="An S3 bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     aws_access_key_id: Optional[SecretStr] = Field(
         default=None,
         title="AWS Access Key ID",
         description="Equivalent to the AWS_ACCESS_KEY_ID environment variable.",
-        example="AKIAIOSFODNN7EXAMPLE",
+        examples=["AKIAIOSFODNN7EXAMPLE"],
     )
     aws_secret_access_key: Optional[SecretStr] = Field(
         default=None,
         title="AWS Secret Access Key",
         description="Equivalent to the AWS_SECRET_ACCESS_KEY environment variable.",
-        example="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+        examples=["wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"],
     )
 
     _remote_file_system: RemoteFileSystem = None
@@ -549,7 +549,7 @@ class GCS(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="A GCS bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     service_account_info: Optional[SecretStr] = Field(
         default=None,
@@ -653,7 +653,7 @@ class Azure(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="An Azure storage bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     azure_storage_connection_string: Optional[SecretStr] = Field(
         default=None,
@@ -804,7 +804,7 @@ class SMB(WritableFileSystem, WritableDeploymentStorage):
     share_path: str = Field(
         default=...,
         description="SMB target (requires <SHARE>, followed by <PATH>).",
-        example="/SHARE/dir/subdir",
+        examples=["/SHARE/dir/subdir"],
     )
     smb_username: Optional[SecretStr] = Field(
         default=None,

prefect/flows.py

@@ -590,13 +590,13 @@ class Flow(Generic[P, R]):
     @sync_compatible
     @deprecated_parameter(
         "schedule",
-        start_date="Mar 2023",
+        start_date="Mar 2024",
         when=lambda p: p is not None,
         help="Use `schedules` instead.",
     )
     @deprecated_parameter(
         "is_schedule_active",
-        start_date="Mar 2023",
+        start_date="Mar 2024",
         when=lambda p: p is not None,
         help="Use `paused` instead.",
     )
@@ -970,6 +970,7 @@ class Flow(Generic[P, R]):
         enforce_parameter_schema: bool = False,
         entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,
         print_next_steps: bool = True,
+        ignore_warnings: bool = False,
     ) -> UUID:
         """
         Deploys a flow to run on dynamic infrastructure via a work pool.
@@ -1024,6 +1025,7 @@ class Flow(Generic[P, R]):
                 entrypoint, ensure that the module will be importable in the execution environment.
             print_next_steps_message: Whether or not to print a message with next steps
                 after deploying the deployments.
+            ignore_warnings: Whether or not to ignore warnings about the work pool type.
 
         Returns:
             The ID of the created/updated deployment.
@@ -1100,6 +1102,7 @@ class Flow(Generic[P, R]):
             build=build,
             push=push,
             print_next_steps_message=False,
+            ignore_warnings=ignore_warnings,
         )
 
         if print_next_steps:
@@ -1122,10 +1125,11 @@ class Flow(Generic[P, R]):
                 style="blue",
             )
             if PREFECT_UI_URL:
-                console.print(
+                message = (
                     "\nYou can also run your flow via the Prefect UI:"
                     f" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\n"
                 )
+                console.print(message, soft_wrap=True)
 
         return deployment_ids[0]
 

prefect/infrastructure/provisioners/ecs.py

@@ -397,6 +397,7 @@ class AuthenticationResource:
                         "ecs:RegisterTaskDefinition",
                         "ecs:RunTask",
                         "ecs:StopTask",
+                        "ecs:TagResource",
                         "logs:CreateLogStream",
                         "logs:PutLogEvents",
                         "logs:DescribeLogGroups",