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

prefect/blocks/system.py

@@ -1,7 +1,5 @@
 from typing import Any
 
-import pendulum
-
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 
 if HAS_PYDANTIC_V2:
@@ -9,6 +7,7 @@ if HAS_PYDANTIC_V2:
 else:
     from pydantic import Field, SecretStr
 
+from prefect._internal.schemas.fields import DateTimeTZ
 from prefect.blocks.core import Block
 
 
@@ -76,7 +75,7 @@ class DateTime(Block):
     _logo_url = "https://cdn.sanity.io/images/3ugk85nk/production/8b3da9a6621e92108b8e6a75b82e15374e170ff7-48x48.png"
     _documentation_url = "https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.DateTime"
 
-    value: pendulum.DateTime = Field(
+    value: DateTimeTZ = Field(
         default=...,
         description="An ISO 8601-compatible datetime value.",
     )

prefect/client/base.py

@@ -193,11 +193,18 @@ class PrefectHttpxClient(httpx.AsyncClient):
     [Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)
     """
 
-    def __init__(self, *args, enable_csrf_support: bool = False, **kwargs):
+    def __init__(
+        self,
+        *args,
+        enable_csrf_support: bool = False,
+        raise_on_all_errors: bool = True,
+        **kwargs,
+    ):
         self.enable_csrf_support: bool = enable_csrf_support
         self.csrf_token: Optional[str] = None
         self.csrf_token_expiration: Optional[datetime] = None
         self.csrf_client_id: uuid.UUID = uuid.uuid4()
+        self.raise_on_all_errors: bool = raise_on_all_errors
 
         super().__init__(*args, **kwargs)
 
@@ -345,10 +352,8 @@ class PrefectHttpxClient(httpx.AsyncClient):
         # Convert to a Prefect response to add nicer errors messages
         response = PrefectResponse.from_httpx_response(response)
 
-        # Always raise bad responses
-        # NOTE: We may want to remove this and handle responses per route in the
-        #       `PrefectClient`
-        response.raise_for_status()
+        if self.raise_on_all_errors:
+            response.raise_for_status()
 
         return response
 

prefect/client/orchestration.py

@@ -8,9 +8,11 @@ from typing import (
     Dict,
     Iterable,
     List,
+    NoReturn,
     Optional,
     Set,
     Tuple,
+    TypeVar,
     Union,
 )
 from uuid import UUID, uuid4
@@ -19,20 +21,19 @@ import certifi
 import httpcore
 import httpx
 import pendulum
+from typing_extensions import ParamSpec
 
 from prefect._internal.compatibility.deprecated import (
     handle_deprecated_infra_overrides_parameter,
 )
-from prefect._internal.compatibility.experimental import (
-    EXPERIMENTAL_WARNING,
-    ExperimentalFeature,
-    experiment_enabled,
-)
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect.client.schemas import sorting
+from prefect.events import filters
 from prefect.settings import (
-    PREFECT_EXPERIMENTAL_WARN,
-    PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INFRA_OVERRIDES,
+    PREFECT_API_SERVICES_TRIGGERS_ENABLED,
+    PREFECT_EXPERIMENTAL_EVENTS,
 )
+from prefect.utilities.asyncutils import run_sync
 
 if HAS_PYDANTIC_V2:
     import pydantic.v1 as pydantic
@@ -133,7 +134,7 @@ from prefect.client.schemas.sorting import (
     TaskRunSort,
 )
 from prefect.deprecated.data_documents import DataDocument
-from prefect.events.schemas.automations import Automation, ExistingAutomation
+from prefect.events.schemas.automations import Automation, AutomationCore
 from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_DATABASE_CONNECTION_URL,
@@ -155,14 +156,25 @@ if TYPE_CHECKING:
 
 from prefect.client.base import ASGIApp, PrefectHttpxClient, app_lifespan_context
 
+P = ParamSpec("P")
+R = TypeVar("R")
+
 
 class ServerType(AutoEnum):
     EPHEMERAL = AutoEnum.auto()
     SERVER = AutoEnum.auto()
     CLOUD = AutoEnum.auto()
 
+    def supports_automations(self) -> bool:
+        if self == ServerType.CLOUD:
+            return True
+
+        return PREFECT_EXPERIMENTAL_EVENTS and PREFECT_API_SERVICES_TRIGGERS_ENABLED
+
 
-def get_client(httpx_settings: Optional[dict] = None) -> "PrefectClient":
+def get_client(
+    httpx_settings: Optional[Dict[str, Any]] = None, sync_client: bool = False
+) -> "PrefectClient":
     """
     Retrieve a HTTP client for communicating with the Prefect REST API.
 
@@ -172,6 +184,13 @@ def get_client(httpx_settings: Optional[dict] = None) -> "PrefectClient":
     async with get_client() as client:
         await client.hello()
     ```
+
+    To return a synchronous client, pass sync_client=True:
+
+    ```python
+    with get_client(sync_client=True) as client:
+        client.hello()
+    ```
     """
     ctx = prefect.context.get_settings_context()
     api = PREFECT_API_URL.value()
@@ -182,11 +201,18 @@ def get_client(httpx_settings: Optional[dict] = None) -> "PrefectClient":
 
         api = create_app(ctx.settings, ephemeral=True)
 
-    return PrefectClient(
-        api,
-        api_key=PREFECT_API_KEY.value(),
-        httpx_settings=httpx_settings,
-    )
+    if sync_client:
+        return SyncPrefectClient(
+            api,
+            api_key=PREFECT_API_KEY.value(),
+            httpx_settings=httpx_settings,
+        )
+    else:
+        return PrefectClient(
+            api,
+            api_key=PREFECT_API_KEY.value(),
+            httpx_settings=httpx_settings,
+        )
 
 
 class PrefectClient:
@@ -568,21 +594,6 @@ class PrefectClient:
         Returns:
             The flow run model
         """
-        if 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,
-                )
-
         parameters = parameters or {}
         context = context or {}
         state = state or prefect.states.Scheduled()
@@ -703,21 +714,6 @@ class PrefectClient:
         Returns:
             an `httpx.Response` object from the PATCH request
         """
-        if 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,
-                )
-
         params = {}
         if flow_version is not None:
             params["flow_version"] = flow_version
@@ -2164,21 +2160,23 @@ class PrefectClient:
 
     async def create_task_run(
         self,
-        task: "TaskObject",
+        task: "TaskObject[P, R]",
         flow_run_id: Optional[UUID],
         dynamic_key: str,
-        name: str = None,
-        extra_tags: Iterable[str] = None,
-        state: prefect.states.State = None,
-        task_inputs: Dict[
-            str,
-            List[
-                Union[
-                    TaskRunResult,
-                    Parameter,
-                    Constant,
-                ]
-            ],
+        name: Optional[str] = None,
+        extra_tags: Optional[Iterable[str]] = None,
+        state: Optional[prefect.states.State[R]] = None,
+        task_inputs: Optional[
+            Dict[
+                str,
+                List[
+                    Union[
+                        TaskRunResult,
+                        Parameter,
+                        Constant,
+                    ]
+                ],
+            ]
         ] = None,
     ) -> TaskRun:
         """
@@ -2998,34 +2996,6 @@ class PrefectClient:
         response.raise_for_status()
         return response.json()
 
-    async def create_automation(self, automation: Automation) -> UUID:
-        """Creates an automation in Prefect Cloud."""
-        if self.server_type != ServerType.CLOUD:
-            raise RuntimeError("Automations are only supported for Prefect Cloud.")
-
-        response = await self._client.post(
-            "/automations/",
-            json=automation.dict(json_compatible=True),
-        )
-
-        return UUID(response.json()["id"])
-
-    async def read_resource_related_automations(
-        self, resource_id: str
-    ) -> List[ExistingAutomation]:
-        if self.server_type != ServerType.CLOUD:
-            raise RuntimeError("Automations are only supported for Prefect Cloud.")
-
-        response = await self._client.get(f"/automations/related-to/{resource_id}")
-        response.raise_for_status()
-        return pydantic.parse_obj_as(List[ExistingAutomation], response.json())
-
-    async def delete_resource_owned_automations(self, resource_id: str):
-        if self.server_type != ServerType.CLOUD:
-            raise RuntimeError("Automations are only supported for Prefect Cloud.")
-
-        await self._client.delete(f"/automations/owned-by/{resource_id}")
-
     async def increment_concurrency_slots(
         self, names: List[str], slots: int, mode: str
     ) -> httpx.Response:
@@ -3165,6 +3135,147 @@ class PrefectClient:
         response = await self._client.delete(f"/flow_runs/{flow_run_id}/input/{key}")
         response.raise_for_status()
 
+    def _raise_for_unsupported_automations(self) -> NoReturn:
+        if not PREFECT_EXPERIMENTAL_EVENTS:
+            raise RuntimeError(
+                "The current server and client configuration does not support "
+                "events.  Enable experimental events support with the "
+                "PREFECT_EXPERIMENTAL_EVENTS setting."
+            )
+        else:
+            raise RuntimeError(
+                "The current server and client configuration does not support "
+                "automations.  Enable experimental automations with the "
+                "PREFECT_API_SERVICES_TRIGGERS_ENABLED setting."
+            )
+
+    async def create_automation(self, automation: AutomationCore) -> UUID:
+        """Creates an automation in Prefect Cloud."""
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.post(
+            "/automations/",
+            json=automation.dict(json_compatible=True),
+        )
+
+        return UUID(response.json()["id"])
+
+    async def read_automations(self) -> List[Automation]:
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.post("/automations/filter")
+        response.raise_for_status()
+        return pydantic.parse_obj_as(List[Automation], response.json())
+
+    async def find_automation(self, id_or_name: str) -> Optional[Automation]:
+        try:
+            id = UUID(id_or_name)
+        except ValueError:
+            id = None
+
+        if id:
+            automation = await self.read_automation(id)
+            if automation:
+                return automation
+
+        automations = await self.read_automations()
+
+        # Look for it by an exact name
+        for automation in automations:
+            if automation.name == id_or_name:
+                return automation
+
+        # Look for it by a case-insensitive name
+        for automation in automations:
+            if automation.name.lower() == id_or_name.lower():
+                return automation
+
+        return None
+
+    async def read_automation(self, automation_id: UUID) -> Optional[Automation]:
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.get(f"/automations/{automation_id}")
+        if response.status_code == 404:
+            return None
+        response.raise_for_status()
+        return Automation.parse_obj(response.json())
+
+    async def read_automations_by_name(self, name: str) -> List[Automation]:
+        """
+        Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.
+
+        Args:
+            name: the name of the automation to query
+
+        Returns:
+            a list of Automation model representations of the automations
+        """
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+        automation_filter = filters.AutomationFilter(name=dict(any_=[name]))
+
+        response = await self._client.post(
+            "/automations/filter",
+            json={
+                "sort": sorting.AutomationSort.UPDATED_DESC,
+                "automations": automation_filter.dict(json_compatible=True)
+                if automation_filter
+                else None,
+            },
+        )
+
+        response.raise_for_status()
+
+        return pydantic.parse_obj_as(List[Automation], response.json())
+
+    async def pause_automation(self, automation_id: UUID):
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.patch(
+            f"/automations/{automation_id}", json={"enabled": False}
+        )
+        response.raise_for_status()
+
+    async def resume_automation(self, automation_id: UUID):
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.patch(
+            f"/automations/{automation_id}", json={"enabled": True}
+        )
+        response.raise_for_status()
+
+    async def delete_automation(self, automation_id: UUID):
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.delete(f"/automations/{automation_id}")
+        if response.status_code == 404:
+            return
+
+        response.raise_for_status()
+
+    async def read_resource_related_automations(
+        self, resource_id: str
+    ) -> List[Automation]:
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        response = await self._client.get(f"/automations/related-to/{resource_id}")
+        response.raise_for_status()
+        return pydantic.parse_obj_as(List[Automation], response.json())
+
+    async def delete_resource_owned_automations(self, resource_id: str):
+        if not self.server_type.supports_automations():
+            self._raise_for_unsupported_automations()
+
+        await self._client.delete(f"/automations/owned-by/{resource_id}")
+
     async def __aenter__(self):
         """
         Start the client.
@@ -3225,3 +3336,212 @@ class PrefectClient:
 
     def __exit__(self, *_):
         assert False, "This should never be called but must be defined for __enter__"
+
+
+class SyncPrefectClient:
+    """
+    A synchronous client for interacting with the [Prefect REST API](/api-ref/rest-api/).
+
+    Args:
+        api: the REST API URL or FastAPI application to connect to
+        api_key: An optional API key for authentication.
+        api_version: The API version this client is compatible with.
+        httpx_settings: An optional dictionary of settings to pass to the underlying
+            `httpx.AsyncClient`
+
+    Examples:
+
+        Say hello to a Prefect REST API
+
+        <div class="terminal">
+        ```
+        >>> with get_client(sync_client=True) as client:
+        >>>     response = client.hello()
+        >>>
+        >>> print(response.json())
+        👋
+        ```
+        </div>
+    """
+
+    def __init__(
+        self,
+        api: Union[str, ASGIApp],
+        *,
+        api_key: Optional[str] = None,
+        api_version: Optional[str] = None,
+        httpx_settings: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self._prefect_client = PrefectClient(
+            api=api,
+            api_key=api_key,
+            api_version=api_version,
+            httpx_settings=httpx_settings,
+        )
+
+    def __enter__(self):
+        run_sync(self._prefect_client.__aenter__())
+        return self
+
+    def __exit__(self, *exc_info):
+        return run_sync(self._prefect_client.__aexit__(*exc_info))
+
+    async def __aenter__(self):
+        raise RuntimeError(
+            "The `SyncPrefectClient` must be entered with a sync context. Use '"
+            "with SyncPrefectClient(...)' not 'async with SyncPrefectClient(...)'"
+        )
+
+    async def __aexit__(self, *_):
+        assert False, "This should never be called but must be defined for __aenter__"
+
+    def hello(self) -> httpx.Response:
+        """
+        Send a GET request to /hello for testing purposes.
+        """
+        return run_sync(self._prefect_client.hello())
+
+    def create_task_run(
+        self,
+        task: "TaskObject[P, R]",
+        flow_run_id: Optional[UUID],
+        dynamic_key: str,
+        name: Optional[str] = None,
+        extra_tags: Optional[Iterable[str]] = None,
+        state: Optional[prefect.states.State[R]] = None,
+        task_inputs: Optional[
+            Dict[
+                str,
+                List[
+                    Union[
+                        TaskRunResult,
+                        Parameter,
+                        Constant,
+                    ]
+                ],
+            ]
+        ] = None,
+    ) -> TaskRun:
+        """
+        Create a task run
+
+        Args:
+            task: The Task to run
+            flow_run_id: The flow run id with which to associate the task run
+            dynamic_key: A key unique to this particular run of a Task within the flow
+            name: An optional name for the task run
+            extra_tags: an optional list of extra tags to apply to the task run in
+                addition to `task.tags`
+            state: The initial state for the run. If not provided, defaults to
+                `Pending` for now. Should always be a `Scheduled` type.
+            task_inputs: the set of inputs passed to the task
+
+        Returns:
+            The created task run.
+        """
+        return run_sync(
+            self._prefect_client.create_task_run(
+                task=task,
+                flow_run_id=flow_run_id,
+                dynamic_key=dynamic_key,
+                name=name,
+                extra_tags=extra_tags,
+                state=state,
+                task_inputs=task_inputs,
+            )
+        )
+
+    def set_task_run_state(
+        self,
+        task_run_id: UUID,
+        state: prefect.states.State,
+        force: bool = False,
+    ) -> OrchestrationResult:
+        """
+        Set the state of a task run.
+
+        Args:
+            task_run_id: the id of the task run
+            state: the state to set
+            force: if True, disregard orchestration logic when setting the state,
+                forcing the Prefect API to accept the state
+
+        Returns:
+            an OrchestrationResult model representation of state orchestration output
+        """
+        return run_sync(
+            self._prefect_client.set_task_run_state(
+                task_run_id=task_run_id,
+                state=state,
+                force=force,
+            )
+        )
+
+    def create_flow_run(
+        self,
+        flow_id: UUID,
+        parameters: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+        scheduled_start_time: Optional[datetime.datetime] = None,
+        run_name: Optional[str] = None,
+        labels: Optional[List[str]] = None,
+        parameters_json: Optional[str] = None,
+        run_config: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> FlowRunResponse:
+        """
+        Create a new flow run.
+
+        Args:
+            - flow_id (UUID): the ID of the flow to create a run for
+            - parameters (Optional[Dict[str, Any]]): a dictionary of parameter values to pass to the flow
+            - context (Optional[Dict[str, Any]]): a dictionary of context values to pass to the flow
+            - scheduled_start_time (Optional[datetime.datetime]): the scheduled start time for the flow run
+            - run_name (Optional[str]): a name to assign to the flow run
+            - labels (Optional[List[str]]): a list of labels to assign to the flow run
+            - parameters_json (Optional[str]): a JSON string of parameter values to pass to the flow
+            - run_config (Optional[Dict[str, Any]]): a dictionary of run configuration options
+            - idempotency_key (Optional[str]): a key to ensure idempotency when creating the flow run
+
+        Returns:
+            - FlowRunResponse: the created flow run
+        """
+        return run_sync(
+            self._prefect_client.create_flow_run(
+                flow_id=flow_id,
+                parameters=parameters,
+                context=context,
+                scheduled_start_time=scheduled_start_time,
+                run_name=run_name,
+                labels=labels,
+                parameters_json=parameters_json,
+                run_config=run_config,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def set_flow_run_state(
+        self,
+        flow_run_id: UUID,
+        state: "prefect.states.State",
+        force: bool = False,
+    ) -> OrchestrationResult:
+        """
+        Set the state of a flow run.
+
+        Args:
+            flow_run_id: the id of the flow run
+            state: the state to set
+            force: if True, disregard orchestration logic when setting the state,
+                forcing the Prefect API to accept the state
+
+        Returns:
+            an OrchestrationResult model representation of state orchestration output
+        """
+        return run_sync(
+            self._prefect_client.set_flow_run_state(
+                flow_run_id=flow_run_id,
+                state=state,
+                force=force,
+            )
+        )

prefect/client/schemas/actions.py

@@ -8,9 +8,9 @@ from prefect._internal.compatibility.deprecated import DeprecatedInfraOverridesF
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 
 if HAS_PYDANTIC_V2:
-    from pydantic.v1 import Field, conint, root_validator, validator
+    from pydantic.v1 import Field, root_validator, validator
 else:
-    from pydantic import Field, conint, root_validator, validator
+    from pydantic import Field, root_validator, validator
 
 import prefect.client.schemas.objects as objects
 from prefect._internal.schemas.bases import ActionBaseModel
@@ -26,6 +26,7 @@ from prefect._internal.schemas.validators import (
 )
 from prefect.client.schemas.objects import StateDetails, StateType
 from prefect.client.schemas.schedules import SCHEDULE_TYPES
+from prefect.types import NonNegativeInteger
 from prefect.utilities.collections import listrepr
 from prefect.utilities.pydantic import get_class_fields_only
 
@@ -525,7 +526,7 @@ class WorkPoolCreate(ActionBaseModel):
         default=False,
         description="Whether the work pool is paused.",
     )
-    concurrency_limit: Optional[conint(ge=0)] = Field(
+    concurrency_limit: Optional[NonNegativeInteger] = Field(
         default=None, description="A concurrency limit for the work pool."
     )