prefect-client 3.1.10__py3-none-any.whl → 3.1.12__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

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable, Union
+
+from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
+
+if TYPE_CHECKING:
+    from prefect.client.schemas.actions import (
+        LogCreate,
+    )
+    from prefect.client.schemas.filters import (
+        LogFilter,
+    )
+    from prefect.client.schemas.objects import (
+        Log,
+    )
+    from prefect.client.schemas.sorting import LogSort
+
+
+class LogClient(BaseClient):
+    def create_logs(self, logs: Iterable[Union["LogCreate", dict[str, Any]]]) -> None:
+        """
+        Create logs for a flow or task run
+        """
+        from prefect.client.schemas.actions import LogCreate
+
+        serialized_logs = [
+            log.model_dump(mode="json") if isinstance(log, LogCreate) else log
+            for log in logs
+        ]
+        self.request("POST", "/logs/", json=serialized_logs)
+
+    def read_logs(
+        self,
+        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 or LogSort.TIMESTAMP_ASC,
+        }
+        response = self.request("POST", "/logs/filter", json=body)
+        from prefect.client.schemas.objects import Log
+
+        return Log.model_validate_list(response.json())
+
+
+class LogAsyncClient(BaseAsyncClient):
+    async def create_logs(
+        self, logs: Iterable[Union["LogCreate", dict[str, Any]]]
+    ) -> None:
+        """
+        Create logs for a flow or task run
+
+        Args:
+            logs: An iterable of `LogCreate` objects or already json-compatible dicts
+        """
+        from prefect.client.schemas.actions import LogCreate
+
+        serialized_logs = [
+            log.model_dump(mode="json") if isinstance(log, LogCreate) else log
+            for log in logs
+        ]
+        await self.request("POST", "/logs/", json=serialized_logs)
+
+    async def read_logs(
+        self,
+        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 or LogSort.TIMESTAMP_ASC,
+        }
+
+        response = await self.request("POST", "/logs/filter", json=body)
+        from prefect.client.schemas.objects import Log
+
+        return Log.model_validate_list(response.json())

prefect/client/orchestration/_variables/client.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
+from prefect.exceptions import ObjectNotFound
+
+if TYPE_CHECKING:
+    from prefect.client.schemas.actions import (
+        VariableCreate,
+        VariableUpdate,
+    )
+    from prefect.client.schemas.objects import (
+        Variable,
+    )
+
+
+class VariableClient(BaseClient):
+    def create_variable(self, variable: "VariableCreate") -> "Variable":
+        """
+        Creates an variable with the provided configuration.
+
+        Args:
+            variable: Desired configuration for the new variable.
+        Returns:
+            Information about the newly created variable.
+        """
+        response = self._client.post(
+            "/variables/",
+            json=variable.model_dump(mode="json", exclude_unset=True),
+        )
+        from prefect.client.schemas.objects import Variable
+
+        return Variable.model_validate(response.json())
+
+    def read_variable_by_name(self, name: str) -> "Variable | None":
+        """Reads a variable by name. Returns None if no variable is found."""
+        try:
+            response = self.request(
+                "GET", "/variables/name/{name}", path_params={"name": name}
+            )
+            from prefect.client.schemas.objects import Variable
+
+            return Variable(**response.json())
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return None
+            else:
+                raise
+
+    def read_variables(self, limit: int | None = None) -> list["Variable"]:
+        """Reads all variables."""
+        response = self.request("POST", "/variables/filter", json={"limit": limit})
+        from prefect.client.schemas.objects import Variable
+
+        return Variable.model_validate_list(response.json())
+
+    def update_variable(self, variable: "VariableUpdate") -> None:
+        """
+        Updates a variable with the provided configuration.
+
+        Args:
+            variable: Desired configuration for the updated variable.
+        Returns:
+            Information about the updated variable.
+        """
+        self._client.patch(
+            f"/variables/name/{variable.name}",
+            json=variable.model_dump(mode="json", exclude_unset=True),
+        )
+        return None
+
+    def delete_variable_by_name(self, name: str) -> None:
+        """Deletes a variable by name."""
+        try:
+            self.request(
+                "DELETE",
+                "/variables/name/{name}",
+                path_params={"name": name},
+            )
+            return None
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+
+class VariableAsyncClient(BaseAsyncClient):
+    async def create_variable(self, variable: "VariableCreate") -> "Variable":
+        """Creates a variable with the provided configuration."""
+        response = await self._client.post(
+            "/variables/",
+            json=variable.model_dump(mode="json", exclude_unset=True),
+        )
+        from prefect.client.schemas.objects import Variable
+
+        return Variable.model_validate(response.json())
+
+    async def read_variable_by_name(self, name: str) -> "Variable | None":
+        """Reads a variable by name. Returns None if no variable is found."""
+        try:
+            response = await self.request(
+                "GET",
+                "/variables/name/{name}",
+                path_params={"name": name},
+            )
+            from prefect.client.schemas.objects import Variable
+
+            return Variable.model_validate(response.json())
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return None
+            else:
+                raise
+
+    async def read_variables(self, limit: int | None = None) -> list["Variable"]:
+        """Reads all variables."""
+        response = await self.request(
+            "POST", "/variables/filter", json={"limit": limit}
+        )
+        from prefect.client.schemas.objects import Variable
+
+        return Variable.model_validate_list(response.json())
+
+    async def update_variable(self, variable: "VariableUpdate") -> None:
+        """
+        Updates a variable with the provided configuration.
+
+        Args:
+            variable: Desired configuration for the updated variable.
+        Returns:
+            Information about the updated variable.
+        """
+        await self.request(
+            "PATCH",
+            "/variables/name/{name}",
+            path_params={"name": variable.name},
+            json=variable.model_dump(mode="json", exclude_unset=True),
+        )
+        return None
+
+    async def delete_variable_by_name(self, name: str) -> None:
+        """Deletes a variable by name."""
+        try:
+            await self.request(
+                "DELETE",
+                "/variables/name/{name}",
+                path_params={"name": name},
+            )
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise

prefect/client/orchestration/base.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from typing_extensions import TypeAlias
+
+if TYPE_CHECKING:
+    from httpx import AsyncClient, Client, Response
+
+    from prefect.client.orchestration.routes import ServerRoutes
+
+HTTP_METHODS: TypeAlias = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
+
+
+class BaseClient:
+    def __init__(self, client: "Client"):
+        self._client = client
+
+    def request(
+        self,
+        method: HTTP_METHODS,
+        path: "ServerRoutes",
+        params: dict[str, Any] | None = None,
+        path_params: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> "Response":
+        if path_params:
+            path = path.format(**path_params)  # type: ignore
+        return self._client.request(method, path, params=params, **kwargs)
+
+
+class BaseAsyncClient:
+    def __init__(self, client: "AsyncClient"):
+        self._client = client
+
+    async def request(
+        self,
+        method: HTTP_METHODS,
+        path: "ServerRoutes",
+        params: dict[str, Any] | None = None,
+        path_params: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> "Response":
+        if path_params:
+            path = path.format(**path_params)  # type: ignore
+        return await self._client.request(method, path, params=params, **kwargs)