prefect-client 3.1.11__py3-none-any.whl → 3.1.13__py3-none-any.whl

prefect/client/orchestration/_flows/client.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from httpx import HTTPStatusError, RequestError
+
+from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
+from prefect.exceptions import ObjectNotFound
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from prefect.client.schemas.filters import (
+        DeploymentFilter,
+        FlowFilter,
+        FlowRunFilter,
+        TaskRunFilter,
+        WorkPoolFilter,
+        WorkQueueFilter,
+    )
+    from prefect.client.schemas.objects import (
+        Flow,
+    )
+    from prefect.client.schemas.sorting import FlowSort
+    from prefect.flows import Flow as FlowObject
+
+
+class FlowClient(BaseClient):
+    def create_flow(self, flow: "FlowObject[Any, Any]") -> "UUID":
+        """
+        Create a flow in the Prefect API.
+
+        Args:
+            flow: a [Flow][prefect.flows.Flow] object
+
+        Raises:
+            httpx.RequestError: if a flow was not created for any reason
+
+        Returns:
+            the ID of the flow in the backend
+        """
+        return self.create_flow_from_name(flow.name)
+
+    def create_flow_from_name(self, flow_name: str) -> "UUID":
+        """
+        Create a flow in the Prefect API.
+
+        Args:
+            flow_name: the name of the new flow
+
+        Raises:
+            httpx.RequestError: if a flow was not created for any reason
+
+        Returns:
+            the ID of the flow in the backend
+        """
+        from prefect.client.schemas.actions import FlowCreate
+
+        flow_data = FlowCreate(name=flow_name)
+        response = self.request(
+            "POST", "/flows/", json=flow_data.model_dump(mode="json")
+        )
+
+        flow_id = response.json().get("id")
+        if not flow_id:
+            raise RequestError(f"Malformed response: {response}")
+
+        # Return the id of the created flow
+        from uuid import UUID
+
+        return UUID(flow_id)
+
+    def read_flow(self, flow_id: "UUID") -> "Flow":
+        """
+        Query the Prefect API for a flow by id.
+
+        Args:
+            flow_id: the flow ID of interest
+
+        Returns:
+            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow
+        """
+        response = self.request("GET", "/flows/{id}", path_params={"id": flow_id})
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate(response.json())
+
+    def delete_flow(self, flow_id: "UUID") -> None:
+        """
+        Delete a flow by UUID.
+
+        Args:
+            flow_id: ID of the flow to be deleted
+        Raises:
+            prefect.exceptions.ObjectNotFound: If request returns 404
+            httpx.RequestError: If requests fail
+        """
+        try:
+            self.request("DELETE", "/flows/{id}", path_params={"id": flow_id})
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+    def read_flows(
+        self,
+        *,
+        flow_filter: "FlowFilter | None" = None,
+        flow_run_filter: "FlowRunFilter | None" = None,
+        task_run_filter: "TaskRunFilter | None" = None,
+        deployment_filter: "DeploymentFilter | None" = None,
+        work_pool_filter: "WorkPoolFilter | None" = None,
+        work_queue_filter: "WorkQueueFilter | None" = None,
+        sort: "FlowSort | None" = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> list["Flow"]:
+        """
+        Query the Prefect API for flows. Only flows matching all criteria will
+        be returned.
+
+        Args:
+            flow_filter: filter criteria for flows
+            flow_run_filter: filter criteria for flow runs
+            task_run_filter: filter criteria for task runs
+            deployment_filter: filter criteria for deployments
+            work_pool_filter: filter criteria for work pools
+            work_queue_filter: filter criteria for work pool queues
+            sort: sort criteria for the flows
+            limit: limit for the flow query
+            offset: offset for the flow query
+
+        Returns:
+            a list of Flow model representations of the flows
+        """
+        body: dict[str, Any] = {
+            "flows": flow_filter.model_dump(mode="json") if flow_filter else None,
+            "flow_runs": (
+                flow_run_filter.model_dump(mode="json", exclude_unset=True)
+                if flow_run_filter
+                else None
+            ),
+            "task_runs": (
+                task_run_filter.model_dump(mode="json") if task_run_filter else None
+            ),
+            "deployments": (
+                deployment_filter.model_dump(mode="json") if deployment_filter else None
+            ),
+            "work_pools": (
+                work_pool_filter.model_dump(mode="json") if work_pool_filter else None
+            ),
+            "work_queues": (
+                work_queue_filter.model_dump(mode="json") if work_queue_filter else None
+            ),
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        response = self.request("POST", "/flows/filter", json=body)
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate_list(response.json())
+
+    def read_flow_by_name(
+        self,
+        flow_name: str,
+    ) -> "Flow":
+        """
+        Query the Prefect API for a flow by name.
+
+        Args:
+            flow_name: the name of a flow
+
+        Returns:
+            a fully hydrated Flow model
+        """
+        response = self.request(
+            "GET", "/flows/name/{name}", path_params={"name": flow_name}
+        )
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate(response.json())
+
+
+class FlowAsyncClient(BaseAsyncClient):
+    async def create_flow(self, flow: "FlowObject[Any, Any]") -> "UUID":
+        """
+        Create a flow in the Prefect API.
+
+        Args:
+            flow: a [Flow][prefect.flows.Flow] object
+
+        Raises:
+            httpx.RequestError: if a flow was not created for any reason
+
+        Returns:
+            the ID of the flow in the backend
+        """
+        return await self.create_flow_from_name(flow.name)
+
+    async def create_flow_from_name(self, flow_name: str) -> "UUID":
+        """
+        Create a flow in the Prefect API.
+
+        Args:
+            flow_name: the name of the new flow
+
+        Raises:
+            httpx.RequestError: if a flow was not created for any reason
+
+        Returns:
+            the ID of the flow in the backend
+        """
+        from prefect.client.schemas.actions import FlowCreate
+
+        flow_data = FlowCreate(name=flow_name)
+        response = await self.request(
+            "POST", "/flows/", json=flow_data.model_dump(mode="json")
+        )
+
+        flow_id = response.json().get("id")
+        if not flow_id:
+            raise RequestError(f"Malformed response: {response}")
+
+        # Return the id of the created flow
+        from uuid import UUID
+
+        return UUID(flow_id)
+
+    async def read_flow(self, flow_id: "UUID") -> "Flow":
+        """
+        Query the Prefect API for a flow by id.
+
+        Args:
+            flow_id: the flow ID of interest
+
+        Returns:
+            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow
+        """
+        response = await self.request("GET", "/flows/{id}", path_params={"id": flow_id})
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate(response.json())
+
+    async def delete_flow(self, flow_id: "UUID") -> None:
+        """
+        Delete a flow by UUID.
+
+        Args:
+            flow_id: ID of the flow to be deleted
+        Raises:
+            prefect.exceptions.ObjectNotFound: If request returns 404
+            httpx.RequestError: If requests fail
+        """
+        try:
+            await self.request("DELETE", "/flows/{id}", path_params={"id": flow_id})
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+    async def read_flows(
+        self,
+        *,
+        flow_filter: "FlowFilter | None" = None,
+        flow_run_filter: "FlowRunFilter | None" = None,
+        task_run_filter: "TaskRunFilter | None" = None,
+        deployment_filter: "DeploymentFilter | None" = None,
+        work_pool_filter: "WorkPoolFilter | None" = None,
+        work_queue_filter: "WorkQueueFilter | None" = None,
+        sort: "FlowSort | None" = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> list["Flow"]:
+        """
+        Query the Prefect API for flows. Only flows matching all criteria will
+        be returned.
+
+        Args:
+            flow_filter: filter criteria for flows
+            flow_run_filter: filter criteria for flow runs
+            task_run_filter: filter criteria for task runs
+            deployment_filter: filter criteria for deployments
+            work_pool_filter: filter criteria for work pools
+            work_queue_filter: filter criteria for work pool queues
+            sort: sort criteria for the flows
+            limit: limit for the flow query
+            offset: offset for the flow query
+
+        Returns:
+            a list of Flow model representations of the flows
+        """
+        body: dict[str, Any] = {
+            "flows": flow_filter.model_dump(mode="json") if flow_filter else None,
+            "flow_runs": (
+                flow_run_filter.model_dump(mode="json", exclude_unset=True)
+                if flow_run_filter
+                else None
+            ),
+            "task_runs": (
+                task_run_filter.model_dump(mode="json") if task_run_filter else None
+            ),
+            "deployments": (
+                deployment_filter.model_dump(mode="json") if deployment_filter else None
+            ),
+            "work_pools": (
+                work_pool_filter.model_dump(mode="json") if work_pool_filter else None
+            ),
+            "work_queues": (
+                work_queue_filter.model_dump(mode="json") if work_queue_filter else None
+            ),
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        response = await self.request("POST", "/flows/filter", json=body)
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate_list(response.json())
+
+    async def read_flow_by_name(
+        self,
+        flow_name: str,
+    ) -> "Flow":
+        """
+        Query the Prefect API for a flow by name.
+
+        Args:
+            flow_name: the name of a flow
+
+        Returns:
+            a fully hydrated Flow model
+        """
+        response = await self.request(
+            "GET", "/flows/name/{name}", path_params={"name": flow_name}
+        )
+        from prefect.client.schemas.objects import Flow
+
+        return Flow.model_validate(response.json())

prefect/client/orchestration/_logs/client.py

@@ -1,11 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Iterable, Optional, Union
+from typing import TYPE_CHECKING, Any, Iterable, Union
 
 from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
-from prefect.client.schemas.sorting import (
-    LogSort,
-)
 
 if TYPE_CHECKING:
     from prefect.client.schemas.actions import (
@@ -17,6 +14,7 @@ if TYPE_CHECKING:
     from prefect.client.schemas.objects import (
         Log,
     )
+    from prefect.client.schemas.sorting import LogSort
 
 
 class LogClient(BaseClient):
@@ -34,19 +32,21 @@ class LogClient(BaseClient):
 
     def read_logs(
         self,
-        log_filter: Optional["LogFilter"] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        sort: "LogSort" = LogSort.TIMESTAMP_ASC,
+        log_filter: "LogFilter | None" = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        sort: "LogSort | None" = None,
     ) -> list["Log"]:
         """
         Read flow and task run logs.
         """
+        from prefect.client.schemas.sorting import LogSort
+
         body: dict[str, Any] = {
             "logs": log_filter.model_dump(mode="json") if log_filter else None,
             "limit": limit,
             "offset": offset,
-            "sort": sort,
+            "sort": sort or LogSort.TIMESTAMP_ASC,
         }
         response = self.request("POST", "/logs/filter", json=body)
         from prefect.client.schemas.objects import Log
@@ -74,19 +74,21 @@ class LogAsyncClient(BaseAsyncClient):
 
     async def read_logs(
         self,
-        log_filter: Optional["LogFilter"] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        sort: "LogSort" = LogSort.TIMESTAMP_ASC,
+        log_filter: "LogFilter | None" = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        sort: "LogSort | None" = None,
     ) -> list[Log]:
         """
         Read flow and task run logs.
         """
+        from prefect.client.schemas.sorting import LogSort
+
         body: dict[str, Any] = {
             "logs": log_filter.model_dump(mode="json") if log_filter else None,
             "limit": limit,
             "offset": offset,
-            "sort": sort,
+            "sort": sort or LogSort.TIMESTAMP_ASC,
         }
 
         response = await self.request("POST", "/logs/filter", json=body)

prefect/client/schemas/__init__.py

@@ -1,32 +1,58 @@
-# Some objects are exported here for backwards compatibility.
-# In general, it is recommended to import schemas from their respective modules.
+import importlib
+import sys
+from typing import Any, TYPE_CHECKING
 
-from .actions import BlockTypeUpdate, StateCreate
-from .objects import (
-    DEFAULT_BLOCK_SCHEMA_VERSION,
-    BlockDocument,
-    BlockSchema,
-    BlockType,
-    FlowRun,
-    FlowRunPolicy,
-    State,
-    StateDetails,
-    StateType,
-    TaskRun,
-    TaskRunInput,
-    TaskRunPolicy,
-    TaskRunResult,
-    Workspace,
-)
-from .responses import (
-    OrchestrationResult,
-    SetStateStatus,
-    StateAbortDetails,
-    StateAcceptDetails,
-    StateRejectDetails,
-)
+if TYPE_CHECKING:
+    from .actions import BlockTypeUpdate, StateCreate
+    from .objects import (
+        DEFAULT_BLOCK_SCHEMA_VERSION,
+        BlockDocument,
+        BlockSchema,
+        BlockType,
+        FlowRun,
+        FlowRunPolicy,
+        State,
+        StateDetails,
+        StateType,
+        TaskRun,
+        TaskRunInput,
+        TaskRunPolicy,
+        TaskRunResult,
+        Workspace,
+    )
+    from .responses import (
+        OrchestrationResult,
+        SetStateStatus,
+        StateAbortDetails,
+        StateAcceptDetails,
+        StateRejectDetails,
+    )
 
-__all__ = (
+_public_api = {
+    "BlockDocument": (__package__, ".objects"),
+    "BlockSchema": (__package__, ".objects"),
+    "BlockType": (__package__, ".objects"),
+    "BlockTypeUpdate": (__package__, ".actions"),
+    "DEFAULT_BLOCK_SCHEMA_VERSION": (__package__, ".objects"),
+    "FlowRun": (__package__, ".objects"),
+    "FlowRunPolicy": (__package__, ".objects"),
+    "OrchestrationResult": (__package__, ".responses"),
+    "SetStateStatus": (__package__, ".responses"),
+    "State": (__package__, ".objects"),
+    "StateAbortDetails": (__package__, ".responses"),
+    "StateAcceptDetails": (__package__, ".responses"),
+    "StateCreate": (__package__, ".actions"),
+    "StateDetails": (__package__, ".objects"),
+    "StateRejectDetails": (__package__, ".responses"),
+    "StateType": (__package__, ".objects"),
+    "TaskRun": (__package__, ".objects"),
+    "TaskRunInput": (__package__, ".objects"),
+    "TaskRunPolicy": (__package__, ".objects"),
+    "TaskRunResult": (__package__, ".objects"),
+    "Workspace": (__package__, ".objects"),
+}
+
+__all__ = [
     "BlockDocument",
     "BlockSchema",
     "BlockType",
@@ -48,4 +74,18 @@ __all__ = (
     "TaskRunPolicy",
     "TaskRunResult",
     "Workspace",
-)
+]
+
+
+def __getattr__(attr_name: str) -> Any:
+    try:
+        if (dynamic_attr := _public_api.get(attr_name)) is None:
+            raise AttributeError(f"module {__name__} has no attribute {attr_name}")
+
+        package, mname = dynamic_attr
+        module = importlib.import_module(mname, package=package)
+        return getattr(module, attr_name)
+    except ModuleNotFoundError as ex:
+        mname, _, attr = (ex.name or "").rpartition(".")
+        ctx = {"name": mname, "obj": attr} if sys.version_info >= (3, 10) else {}
+        raise AttributeError(f"module {mname} has no attribute {attr}", **ctx) from ex

prefect/client/schemas/objects.py

@@ -121,7 +121,7 @@ class WorkPoolStatus(AutoEnum):
     PAUSED = AutoEnum.auto()
 
     @property
-    def display_name(self):
+    def display_name(self) -> str:
         return self.name.replace("_", " ").capitalize()
 
 
@@ -348,7 +348,7 @@ class State(ObjectBaseModel, Generic[R]):
         )
 
         if isinstance(self.data, ResultRecord) and should_persist_result():
-            data = self.data.metadata
+            data = self.data.metadata  # pyright: ignore[reportUnknownMemberType] unable to narrow ResultRecord type
         else:
             data = None
 
@@ -379,7 +379,7 @@ class State(ObjectBaseModel, Generic[R]):
 
     @model_validator(mode="after")
     def set_unpersisted_results_to_none(self) -> Self:
-        if isinstance(self.data, dict) and self.data.get("type") == "unpersisted":
+        if isinstance(self.data, dict) and self.data.get("type") == "unpersisted":  # pyright: ignore[reportUnknownMemberType] unable to narrow dict type
             self.data = None
         return self
 
@@ -524,7 +524,7 @@ class FlowRunPolicy(PrefectBaseModel):
     @classmethod
     def populate_deprecated_fields(cls, values: Any) -> Any:
         if isinstance(values, dict):
-            return set_run_policy_deprecated_fields(values)
+            return set_run_policy_deprecated_fields(values)  # pyright: ignore[reportUnknownVariableType, reportUnknownArgumentType] unable to narrow dict type
         return values
 
 
@@ -1255,7 +1255,7 @@ class BlockDocumentReference(ObjectBaseModel):
     @classmethod
     def validate_parent_and_ref_are_different(cls, values: Any) -> Any:
         if isinstance(values, dict):
-            return validate_parent_and_ref_diff(values)
+            return validate_parent_and_ref_diff(values)  # pyright: ignore[reportUnknownVariableType, reportUnknownArgumentType] unable to narrow dict type
         return values
 
 

prefect/client/utilities.py

@@ -5,7 +5,7 @@ Utilities for working with clients.
 # This module must not import from `prefect.client` when it is imported to avoid
 # circular imports for decorators such as `inject_client` which are widely used.
 
-from collections.abc import Awaitable, Coroutine
+from collections.abc import Coroutine
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 
@@ -61,8 +61,8 @@ def get_or_create_client(
 
 
 def client_injector(
-    func: Callable[Concatenate["PrefectClient", P], Awaitable[R]],
-) -> Callable[P, Awaitable[R]]:
+    func: Callable[Concatenate["PrefectClient", P], Coroutine[Any, Any, R]],
+) -> Callable[P, Coroutine[Any, Any, R]]:
     @wraps(func)
     async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         client, _ = get_or_create_client()

prefect/context.py

@@ -52,7 +52,6 @@ def serialize_context() -> dict[str, Any]:
     """
     Serialize the current context for use in a remote execution environment.
     """
-
     flow_run_context = EngineContext.get()
     task_run_context = TaskRunContext.get()
     tags_context = TagsContext.get()
@@ -71,6 +70,21 @@ def hydrated_context(
     serialized_context: Optional[dict[str, Any]] = None,
     client: Union[PrefectClient, SyncPrefectClient, None] = None,
 ) -> Generator[None, Any, None]:
+    # We need to rebuild the models because we might be hydrating in a remote
+    # environment where the models are not available.
+    # TODO: Remove this once we have fixed our circular imports and we don't need to rebuild models any more.
+    from prefect.flows import Flow
+    from prefect.results import ResultRecordMetadata
+    from prefect.tasks import Task
+
+    _types: dict[str, Any] = dict(
+        Flow=Flow,
+        Task=Task,
+        ResultRecordMetadata=ResultRecordMetadata,
+    )
+    FlowRunContext.model_rebuild(_types_namespace=_types)
+    TaskRunContext.model_rebuild(_types_namespace=_types)
+
     with ExitStack() as stack:
         if serialized_context:
             # Set up settings context

prefect/deployments/base.py

@@ -5,6 +5,8 @@ build system for managing flows and deployments.
 To get started, follow along with [the deloyments tutorial](/tutorials/deployments/).
 """
 
+from __future__ import annotations
+
 import os
 from copy import deepcopy
 from pathlib import Path
@@ -17,6 +19,7 @@ from prefect.client.schemas.actions import DeploymentScheduleCreate
 from prefect.client.schemas.objects import ConcurrencyLimitStrategy
 from prefect.client.schemas.schedules import IntervalSchedule
 from prefect.utilities._git import get_git_branch, get_git_remote_origin_url
+from prefect.utilities.annotations import NotSet
 from prefect.utilities.filesystem import create_default_ignore_file
 from prefect.utilities.templating import apply_values
 
@@ -111,7 +114,9 @@ def create_default_prefect_yaml(
     return True
 
 
-def configure_project_by_recipe(recipe: str, **formatting_kwargs) -> dict:
+def configure_project_by_recipe(
+    recipe: str, **formatting_kwargs: Any
+) -> dict[str, Any] | type[NotSet]:
     """
     Given a recipe name, returns a dictionary representing base configuration options.
 
@@ -129,13 +134,13 @@ def configure_project_by_recipe(recipe: str, **formatting_kwargs) -> dict:
         raise ValueError(f"Unknown recipe {recipe!r} provided.")
 
     with recipe_path.open(mode="r") as f:
-        config = yaml.safe_load(f)
+        config: dict[str, Any] = yaml.safe_load(f)
 
-    config = apply_values(
+    templated_config = apply_values(
         template=config, values=formatting_kwargs, remove_notset=False
     )
 
-    return config
+    return templated_config
 
 
 def initialize_project(
@@ -275,6 +280,7 @@ def _save_deployment_to_prefect_file(
     push_steps: Optional[List[Dict]] = None,
     pull_steps: Optional[List[Dict]] = None,
     triggers: Optional[List[Dict]] = None,
+    sla: Optional[list[dict]] = None,
     prefect_file: Path = Path("prefect.yaml"),
 ):
     """
@@ -319,6 +325,9 @@ def _save_deployment_to_prefect_file(
         if triggers and triggers != parsed_prefect_file_contents.get("triggers"):
             deployment["triggers"] = triggers
 
+        if sla and sla != parsed_prefect_file_contents.get("sla"):
+            deployment["sla"] = sla
+
         deployments = parsed_prefect_file_contents.get("deployments")
         if deployments is None:
             parsed_prefect_file_contents["deployments"] = [deployment]