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

prefect/deployments/runner.py

@@ -57,7 +57,7 @@ from prefect._internal.schemas.validators import (
 )
 from prefect.client.base import ServerType
 from prefect.client.orchestration import PrefectClient, get_client
-from prefect.client.schemas.actions import DeploymentScheduleCreate
+from prefect.client.schemas.actions import DeploymentScheduleCreate, DeploymentUpdate
 from prefect.client.schemas.filters import WorkerFilter, WorkerFilterStatus
 from prefect.client.schemas.objects import (
     ConcurrencyLimitConfig,
@@ -77,6 +77,7 @@ from prefect.exceptions import (
     PrefectHTTPStatusError,
 )
 from prefect.runner.storage import RunnerStorage
+from prefect.schedules import Schedule
 from prefect.settings import (
     PREFECT_DEFAULT_WORK_POOL_NAME,
     PREFECT_UI_URL,
@@ -113,7 +114,7 @@ class RunnerDeployment(BaseModel):
         description: An optional description of the deployment; defaults to the flow's
             description
         tags: An optional list of tags to associate with this deployment; note that tags
-            are used only for organizational purposes. For delegating work to agents,
+            are used only for organizational purposes. For delegating work to workers,
             see `work_queue_name`.
         schedule: A schedule to run this deployment on, once registered
         parameters: A dictionary of parameter values to pass to runs created from this
@@ -229,6 +230,10 @@ class RunnerDeployment(BaseModel):
     def entrypoint_type(self) -> EntrypointType:
         return self._entrypoint_type
 
+    @property
+    def full_name(self) -> str:
+        return f"{self.flow_name}/{self.name}"
+
     @field_validator("name", mode="before")
     @classmethod
     def validate_name(cls, value: str) -> str:
@@ -255,24 +260,9 @@ class RunnerDeployment(BaseModel):
     def reconcile_schedules(cls, values):
         return reconcile_schedules_runner(values)
 
-    @sync_compatible
-    async def apply(
+    async def _create(
         self, work_pool_name: Optional[str] = None, image: Optional[str] = None
     ) -> UUID:
-        """
-        Registers this deployment with the API and returns the deployment's ID.
-
-        Args:
-            work_pool_name: The name of the work pool to use for this
-                deployment.
-            image: The registry, name, and tag of the Docker image to
-                use for this deployment. Only used when the deployment is
-                deployed to a work pool.
-
-        Returns:
-            The ID of the created deployment.
-        """
-
         work_pool_name = work_pool_name or self.work_pool_name
 
         if image and not work_pool_name:
@@ -324,9 +314,14 @@ class RunnerDeployment(BaseModel):
                 if image:
                     create_payload["job_variables"]["image"] = image
                 create_payload["path"] = None if self.storage else self._path
-                create_payload["pull_steps"] = (
-                    [self.storage.to_pull_step()] if self.storage else []
-                )
+                if self.storage:
+                    pull_steps = self.storage.to_pull_step()
+                    if isinstance(pull_steps, list):
+                        create_payload["pull_steps"] = pull_steps
+                    else:
+                        create_payload["pull_steps"] = [pull_steps]
+                else:
+                    create_payload["pull_steps"] = []
 
             try:
                 deployment_id = await client.create_deployment(**create_payload)
@@ -339,25 +334,7 @@ class RunnerDeployment(BaseModel):
                     f"Error while applying deployment: {str(exc)}"
                 ) from exc
 
-            try:
-                # The triggers defined in the deployment spec are, essentially,
-                # anonymous and attempting truly sync them with cloud is not
-                # feasible. Instead, we remove all automations that are owned
-                # by the deployment, meaning that they were created via this
-                # mechanism below, and then recreate them.
-                await client.delete_resource_owned_automations(
-                    f"prefect.deployment.{deployment_id}"
-                )
-            except PrefectHTTPStatusError as e:
-                if e.response.status_code == 404:
-                    # This Prefect server does not support automations, so we can safely
-                    # ignore this 404 and move on.
-                    return deployment_id
-                raise e
-
-            for trigger in self.triggers:
-                trigger.set_deployment_id(deployment_id)
-                await client.create_automation(trigger.as_automation())
+            await self._create_triggers(deployment_id, client)
 
             # We plan to support SLA configuration on the Prefect Server in the future.
             # For now, we only support it on Prefect Cloud.
@@ -370,6 +347,86 @@ class RunnerDeployment(BaseModel):
 
             return deployment_id
 
+    async def _update(self, deployment_id: UUID, client: PrefectClient):
+        parameter_openapi_schema = self._parameter_openapi_schema.model_dump(
+            exclude_unset=True
+        )
+        await client.update_deployment(
+            deployment_id,
+            deployment=DeploymentUpdate(
+                parameter_openapi_schema=parameter_openapi_schema,
+                **self.model_dump(
+                    mode="json",
+                    exclude_unset=True,
+                    exclude={"storage", "name", "flow_name", "triggers"},
+                ),
+            ),
+        )
+
+        await self._create_triggers(deployment_id, client)
+
+        # We plan to support SLA configuration on the Prefect Server in the future.
+        # For now, we only support it on Prefect Cloud.
+
+        # If we're provided with an empty list, we will call the apply endpoint
+        # to remove existing SLAs for the deployment. If the argument is not provided,
+        # we will not call the endpoint.
+        if self._sla or self._sla == []:
+            await self._create_slas(deployment_id, client)
+
+        return deployment_id
+
+    async def _create_triggers(self, deployment_id: UUID, client: PrefectClient):
+        try:
+            # The triggers defined in the deployment spec are, essentially,
+            # anonymous and attempting truly sync them with cloud is not
+            # feasible. Instead, we remove all automations that are owned
+            # by the deployment, meaning that they were created via this
+            # mechanism below, and then recreate them.
+            await client.delete_resource_owned_automations(
+                f"prefect.deployment.{deployment_id}"
+            )
+        except PrefectHTTPStatusError as e:
+            if e.response.status_code == 404:
+                # This Prefect server does not support automations, so we can safely
+                # ignore this 404 and move on.
+                return deployment_id
+            raise e
+
+        for trigger in self.triggers:
+            trigger.set_deployment_id(deployment_id)
+            await client.create_automation(trigger.as_automation())
+
+    @sync_compatible
+    async def apply(
+        self, work_pool_name: Optional[str] = None, image: Optional[str] = None
+    ) -> UUID:
+        """
+        Registers this deployment with the API and returns the deployment's ID.
+
+        Args:
+            work_pool_name: The name of the work pool to use for this
+                deployment.
+            image: The registry, name, and tag of the Docker image to
+                use for this deployment. Only used when the deployment is
+                deployed to a work pool.
+
+        Returns:
+            The ID of the created deployment.
+        """
+
+        async with get_client() as client:
+            try:
+                deployment = await client.read_deployment_by_name(self.full_name)
+            except ObjectNotFound:
+                return await self._create(work_pool_name, image)
+            else:
+                if image:
+                    self.job_variables["image"] = image
+                if work_pool_name:
+                    self.work_pool_name = work_pool_name
+                return await self._update(deployment.id, client)
+
     async def _create_slas(self, deployment_id: UUID, client: PrefectClient):
         if not isinstance(self._sla, list):
             self._sla = [self._sla]
@@ -390,7 +447,7 @@ class RunnerDeployment(BaseModel):
         cron: Optional[Union[Iterable[str], str]] = None,
         rrule: Optional[Union[Iterable[str], str]] = None,
         timezone: Optional[str] = None,
-        schedule: Optional[SCHEDULE_TYPES] = None,
+        schedule: Union[SCHEDULE_TYPES, Schedule, None] = None,
         schedules: Optional["FlexibleScheduleList"] = None,
     ) -> Union[List[DeploymentScheduleCreate], "FlexibleScheduleList"]:
         """
@@ -422,7 +479,6 @@ class RunnerDeployment(BaseModel):
               this list is returned as-is, bypassing other schedule construction
               logic.
         """
-
         num_schedules = sum(
             1
             for entry in (interval, cron, rrule, schedule, schedules)
@@ -430,7 +486,7 @@ class RunnerDeployment(BaseModel):
         )
         if num_schedules > 1:
             raise ValueError(
-                "Only one of interval, cron, rrule, or schedules can be provided."
+                "Only one of interval, cron, rrule, schedule, or schedules can be provided."
             )
         elif num_schedules == 0:
             return []
@@ -483,6 +539,7 @@ class RunnerDeployment(BaseModel):
         cron: Optional[Union[Iterable[str], str]] = None,
         rrule: Optional[Union[Iterable[str], str]] = None,
         paused: Optional[bool] = None,
+        schedule: Optional[Schedule] = None,
         schedules: Optional["FlexibleScheduleList"] = None,
         concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None,
         parameters: Optional[dict[str, Any]] = None,
@@ -508,6 +565,8 @@ class RunnerDeployment(BaseModel):
             cron: A cron schedule of when to execute runs of this flow.
             rrule: An rrule schedule of when to execute runs of this flow.
             paused: Whether or not to set this deployment as paused.
+            schedule: A schedule object defining when to execute runs of this deployment.
+                Used to provide additional scheduling options like `timezone` or `parameters`.
             schedules: A list of schedule objects defining when to execute runs of this deployment.
                 Used to define multiple schedules or additional scheduling options like `timezone`.
             concurrency_limit: The maximum number of concurrent runs this deployment will allow.
@@ -533,6 +592,7 @@ class RunnerDeployment(BaseModel):
             cron=cron,
             rrule=rrule,
             schedules=schedules,
+            schedule=schedule,
         )
 
         job_variables = job_variables or {}
@@ -627,6 +687,7 @@ class RunnerDeployment(BaseModel):
         cron: Optional[Union[Iterable[str], str]] = None,
         rrule: Optional[Union[Iterable[str], str]] = None,
         paused: Optional[bool] = None,
+        schedule: Optional[Schedule] = None,
         schedules: Optional["FlexibleScheduleList"] = None,
         concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None,
         parameters: Optional[dict[str, Any]] = None,
@@ -682,6 +743,7 @@ class RunnerDeployment(BaseModel):
             cron=cron,
             rrule=rrule,
             schedules=schedules,
+            schedule=schedule,
         )
 
         if isinstance(concurrency_limit, ConcurrencyLimitConfig):
@@ -730,6 +792,7 @@ class RunnerDeployment(BaseModel):
         cron: Optional[Union[Iterable[str], str]] = None,
         rrule: Optional[Union[Iterable[str], str]] = None,
         paused: Optional[bool] = None,
+        schedule: Optional[Schedule] = None,
         schedules: Optional["FlexibleScheduleList"] = None,
         concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None,
         parameters: Optional[dict[str, Any]] = None,
@@ -758,6 +821,11 @@ class RunnerDeployment(BaseModel):
                 or a timedelta object. If a number is given, it will be interpreted as seconds.
             cron: A cron schedule of when to execute runs of this flow.
             rrule: An rrule schedule of when to execute runs of this flow.
+            paused: Whether or not the deployment is paused.
+            schedule: A schedule object defining when to execute runs of this deployment.
+                Used to provide additional scheduling options like `timezone` or `parameters`.
+            schedules: A list of schedule objects defining when to execute runs of this deployment.
+                Used to provide additional scheduling options like `timezone` or `parameters`.
             triggers: A list of triggers that should kick of a run of this flow.
             parameters: A dictionary of default parameter values to pass to runs of this flow.
             description: A description for the created deployment. Defaults to the flow's
@@ -782,6 +850,7 @@ class RunnerDeployment(BaseModel):
             cron=cron,
             rrule=rrule,
             schedules=schedules,
+            schedule=schedule,
         )
 
         if isinstance(concurrency_limit, ConcurrencyLimitConfig):
@@ -845,6 +914,7 @@ class RunnerDeployment(BaseModel):
         cron: Optional[Union[Iterable[str], str]] = None,
         rrule: Optional[Union[Iterable[str], str]] = None,
         paused: Optional[bool] = None,
+        schedule: Optional[Schedule] = None,
         schedules: Optional["FlexibleScheduleList"] = None,
         concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None,
         parameters: Optional[dict[str, Any]] = None,
@@ -873,6 +943,11 @@ class RunnerDeployment(BaseModel):
                 or a timedelta object. If a number is given, it will be interpreted as seconds.
             cron: A cron schedule of when to execute runs of this flow.
             rrule: An rrule schedule of when to execute runs of this flow.
+            paused: Whether or not the deployment is paused.
+            schedule: A schedule object defining when to execute runs of this deployment.
+                Used to provide additional scheduling options like `timezone` or `parameters`.
+            schedules: A list of schedule objects defining when to execute runs of this deployment.
+                Used to provide additional scheduling options like `timezone` or `parameters`.
             triggers: A list of triggers that should kick of a run of this flow.
             parameters: A dictionary of default parameter values to pass to runs of this flow.
             description: A description for the created deployment. Defaults to the flow's
@@ -897,6 +972,7 @@ class RunnerDeployment(BaseModel):
             cron=cron,
             rrule=rrule,
             schedules=schedules,
+            schedule=schedule,
         )
 
         if isinstance(concurrency_limit, ConcurrencyLimitConfig):

prefect/deployments/schedules.py

@@ -2,6 +2,7 @@ from typing import TYPE_CHECKING, Any, List, Optional, Sequence, Union
 
 from prefect.client.schemas.actions import DeploymentScheduleCreate
 from prefect.client.schemas.schedules import is_schedule_type
+from prefect.schedules import Schedule
 
 if TYPE_CHECKING:
     from prefect.client.schemas.schedules import SCHEDULE_TYPES
@@ -12,10 +13,13 @@ FlexibleScheduleList = Sequence[
 
 
 def create_deployment_schedule_create(
-    schedule: "SCHEDULE_TYPES",
+    schedule: Union["SCHEDULE_TYPES", "Schedule"],
     active: Optional[bool] = True,
 ) -> DeploymentScheduleCreate:
     """Create a DeploymentScheduleCreate object from common schedule parameters."""
+
+    if isinstance(schedule, Schedule):
+        return DeploymentScheduleCreate.from_schedule(schedule)
     return DeploymentScheduleCreate(
         schedule=schedule,
         active=active if active is not None else True,
@@ -30,6 +34,8 @@ def normalize_to_deployment_schedule_create(
         for obj in schedules:
             if is_schedule_type(obj):
                 normalized.append(create_deployment_schedule_create(obj))
+            elif isinstance(obj, Schedule):
+                normalized.append(create_deployment_schedule_create(obj))
             elif isinstance(obj, dict):
                 normalized.append(create_deployment_schedule_create(**obj))
             elif isinstance(obj, DeploymentScheduleCreate):

prefect/engine.py

@@ -62,18 +62,13 @@ if __name__ == "__main__":
         else:
             run_flow(flow, flow_run=flow_run, error_logger=run_logger)
 
-    except Abort as abort_signal:
-        abort_signal: Abort
+    except Abort:
         engine_logger.info(
-            f"Engine execution of flow run '{flow_run_id}' aborted by orchestrator:"
-            f" {abort_signal}"
+            "Engine execution of flow run '{flow_run_id}' aborted by orchestrator."
         )
         exit(0)
-    except Pause as pause_signal:
-        pause_signal: Pause
-        engine_logger.info(
-            f"Engine execution of flow run '{flow_run_id}' is paused: {pause_signal}"
-        )
+    except Pause:
+        engine_logger.info(f"Engine execution of flow run '{flow_run_id}' is paused.")
         exit(0)
     except Exception:
         engine_logger.error(

prefect/events/schemas/automations.py

@@ -198,7 +198,9 @@ class EventTrigger(ResourceTrigger):
                     "10 seconds"
                 )
 
-        return data | {"within": within} if within else data
+        if within:
+            data = {**data, "within": within}
+        return data
 
     def describe_for_cli(self, indent: int = 0) -> str:
         """Return a human-readable description of this trigger for the CLI"""
@@ -248,7 +250,7 @@ class MetricTriggerQuery(PrefectBaseModel):
     threshold: float = Field(
         ...,
         description=(
-            "The threshold value against which we'll compare " "the query result."
+            "The threshold value against which we'll compare the query result."
         ),
     )
     operator: MetricTriggerOperator = Field(

prefect/events/utilities.py

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
 from datetime import timedelta
-from typing import Any, Dict, List, Optional, Union
+from typing import Any
 from uuid import UUID
 
-import pendulum
+from prefect.types import DateTime
 
 from .clients import (
     AssertingEventsClient,
@@ -18,16 +20,16 @@ TIGHT_TIMING = timedelta(minutes=5)
 
 def emit_event(
     event: str,
-    resource: Dict[str, str],
-    occurred: Optional[pendulum.DateTime] = None,
-    related: Optional[Union[List[Dict[str, str]], List[RelatedResource]]] = None,
-    payload: Optional[Dict[str, Any]] = None,
-    id: Optional[UUID] = None,
-    follows: Optional[Event] = None,
-    **kwargs: Optional[Dict[str, Any]],
-) -> Optional[Event]:
+    resource: dict[str, str],
+    occurred: DateTime | None = None,
+    related: list[dict[str, str]] | list[RelatedResource] | None = None,
+    payload: dict[str, Any] | None = None,
+    id: UUID | None = None,
+    follows: Event | None = None,
+    **kwargs: dict[str, Any] | None,
+) -> Event | None:
     """
-    Send an event to Prefect Cloud.
+    Send an event to Prefect.
 
     Args:
         event: The name of the event that happened.
@@ -60,14 +62,14 @@ def emit_event(
     if worker_instance.client_type not in operational_clients:
         return None
 
-    event_kwargs: Dict[str, Any] = {
+    event_kwargs: dict[str, Any] = {
         "event": event,
         "resource": resource,
         **kwargs,
     }
 
     if occurred is None:
-        occurred = pendulum.now("UTC")
+        occurred = DateTime.now("UTC")
     event_kwargs["occurred"] = occurred
 
     if related is not None:

prefect/exceptions.py

@@ -161,7 +161,7 @@ class ParameterTypeError(PrefectException):
     @classmethod
     def from_validation_error(cls, exc: ValidationError) -> Self:
         bad_params = [
-            f'{".".join(str(item) for item in err["loc"])}: {err["msg"]}'
+            f"{'.'.join(str(item) for item in err['loc'])}: {err['msg']}"
             for err in exc.errors()
         ]
         msg = "Flow run received invalid parameters:\n - " + "\n - ".join(bad_params)

prefect/flow_engine.py

@@ -1518,6 +1518,8 @@ def run_flow(
             ret_val = run_flow_async(**kwargs)
         else:
             ret_val = run_flow_sync(**kwargs)
+    except (Abort, Pause):
+        raise
     except:
         if error_logger:
             error_logger.error(
@@ -1597,20 +1599,18 @@ def run_flow_in_subprocess(
                     # This is running in a brand new process, so there won't be an existing
                     # event loop.
                     asyncio.run(maybe_coro)
-            except Abort as abort_signal:
-                abort_signal: Abort
+            except Abort:
                 if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' aborted by orchestrator: {abort_signal}"
+                    msg = f"Execution of flow run '{flow_run.id}' aborted by orchestrator."
                 else:
-                    msg = f"Execution aborted by orchestrator: {abort_signal}"
+                    msg = "Execution aborted by orchestrator."
                 engine_logger.info(msg)
                 exit(0)
-            except Pause as pause_signal:
-                pause_signal: Pause
+            except Pause:
                 if flow_run:
-                    msg = f"Execution of flow run '{flow_run.id}' is paused: {pause_signal}"
+                    msg = f"Execution of flow run '{flow_run.id}' is paused."
                 else:
-                    msg = f"Execution is paused: {pause_signal}"
+                    msg = "Execution is paused."
                 engine_logger.info(msg)
                 exit(0)
             except Exception:

prefect/flow_runs.py

@@ -139,8 +139,7 @@ async def pause_flow_run(
     timeout: int = 3600,
     poll_interval: int = 10,
     key: Optional[str] = None,
-) -> None:
-    ...
+) -> None: ...
 
 
 @overload
@@ -149,8 +148,7 @@ async def pause_flow_run(
     timeout: int = 3600,
     poll_interval: int = 10,
     key: Optional[str] = None,
-) -> T:
-    ...
+) -> T: ...
 
 
 @sync_compatible
@@ -308,8 +306,7 @@ async def suspend_flow_run(
     timeout: Optional[int] = 3600,
     key: Optional[str] = None,
     client: Optional[PrefectClient] = None,
-) -> None:
-    ...
+) -> None: ...
 
 
 @overload
@@ -319,8 +316,7 @@ async def suspend_flow_run(
     timeout: Optional[int] = 3600,
     key: Optional[str] = None,
     client: Optional[PrefectClient] = None,
-) -> T:
-    ...
+) -> T: ...
 
 
 @sync_compatible