prefect-client 3.4.6.dev1__py3-none-any.whl → 3.4.7__py3-none-any.whl

prefect/client/orchestration/_deployments/client.py

@@ -6,6 +6,7 @@ from uuid import UUID
 
 from httpx import HTTPStatusError, RequestError
 
+from prefect._internal.compatibility.deprecated import deprecated_callable
 from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
 from prefect.exceptions import ObjectNotFound
 
@@ -167,7 +168,7 @@ class DeploymentClient(BaseClient):
 
         return UUID(deployment_id)
 
-    def set_deployment_paused_state(self, deployment_id: UUID, paused: bool) -> None:
+    def _set_deployment_paused_state(self, deployment_id: UUID, paused: bool) -> None:
         self.request(
             "PATCH",
             "/deployments/{id}",
@@ -175,6 +176,72 @@ class DeploymentClient(BaseClient):
             json={"paused": paused},
         )
 
+    @deprecated_callable(
+        start_date="Jun 2025",
+        help="Use pause_deployment or resume_deployment instead.",
+    )
+    def set_deployment_paused_state(self, deployment_id: UUID, paused: bool) -> None:
+        """
+        DEPRECATED: Use pause_deployment or resume_deployment instead.
+
+        Set the paused state of a deployment.
+
+        Args:
+            deployment_id: the deployment ID to update
+            paused: whether the deployment should be paused
+        """
+        self._set_deployment_paused_state(deployment_id, paused)
+
+    def pause_deployment(self, deployment_id: Union[UUID, str]) -> None:
+        """
+        Pause a deployment by ID.
+
+        Args:
+            deployment_id: The deployment ID of interest (can be a UUID or a string).
+
+        Raises:
+            ObjectNotFound: If request returns 404
+            RequestError: If request fails
+        """
+        if not isinstance(deployment_id, UUID):
+            try:
+                deployment_id = UUID(deployment_id)
+            except ValueError:
+                raise ValueError(f"Invalid deployment ID: {deployment_id}")
+
+        try:
+            self._set_deployment_paused_state(deployment_id, paused=True)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+    def resume_deployment(self, deployment_id: Union[UUID, str]) -> None:
+        """
+        Resume (unpause) a deployment by ID.
+
+        Args:
+            deployment_id: The deployment ID of interest (can be a UUID or a string).
+
+        Raises:
+            ObjectNotFound: If request returns 404
+            RequestError: If request fails
+        """
+        if not isinstance(deployment_id, UUID):
+            try:
+                deployment_id = UUID(deployment_id)
+            except ValueError:
+                raise ValueError(f"Invalid deployment ID: {deployment_id}")
+
+        try:
+            self._set_deployment_paused_state(deployment_id, paused=False)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
     def update_deployment(
         self,
         deployment_id: UUID,
@@ -230,7 +297,7 @@ class DeploymentClient(BaseClient):
             deployment_id: the deployment ID of interest
 
         Returns:
-            a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment
+            a Deployment model representation of the deployment
         """
 
         from prefect.client.schemas.responses import DeploymentResponse
@@ -760,7 +827,7 @@ class DeploymentAsyncClient(BaseAsyncClient):
 
         return UUID(deployment_id)
 
-    async def set_deployment_paused_state(
+    async def _set_deployment_paused_state(
         self, deployment_id: UUID, paused: bool
     ) -> None:
         await self.request(
@@ -770,6 +837,74 @@ class DeploymentAsyncClient(BaseAsyncClient):
             json={"paused": paused},
         )
 
+    @deprecated_callable(
+        start_date="Jun 2025",
+        help="Use pause_deployment or resume_deployment instead.",
+    )
+    async def set_deployment_paused_state(
+        self, deployment_id: UUID, paused: bool
+    ) -> None:
+        """
+        DEPRECATED: Use pause_deployment or resume_deployment instead.
+
+        Set the paused state of a deployment.
+
+        Args:
+            deployment_id: the deployment ID to update
+            paused: whether the deployment should be paused
+        """
+        await self._set_deployment_paused_state(deployment_id, paused)
+
+    async def pause_deployment(self, deployment_id: Union[UUID, str]) -> None:
+        """
+        Pause a deployment by ID.
+
+        Args:
+            deployment_id: The deployment ID of interest (can be a UUID or a string).
+
+        Raises:
+            ObjectNotFound: If request returns 404
+            RequestError: If request fails
+        """
+        if not isinstance(deployment_id, UUID):
+            try:
+                deployment_id = UUID(deployment_id)
+            except ValueError:
+                raise ValueError(f"Invalid deployment ID: {deployment_id}")
+
+        try:
+            await self._set_deployment_paused_state(deployment_id, paused=True)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+    async def resume_deployment(self, deployment_id: Union[UUID, str]) -> None:
+        """
+        Resume (unpause) a deployment by ID.
+
+        Args:
+            deployment_id: The deployment ID of interest (can be a UUID or a string).
+
+        Raises:
+            ObjectNotFound: If request returns 404
+            RequestError: If request fails
+        """
+        if not isinstance(deployment_id, UUID):
+            try:
+                deployment_id = UUID(deployment_id)
+            except ValueError:
+                raise ValueError(f"Invalid deployment ID: {deployment_id}")
+
+        try:
+            await self._set_deployment_paused_state(deployment_id, paused=False)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
     async def update_deployment(
         self,
         deployment_id: UUID,
@@ -826,7 +961,7 @@ class DeploymentAsyncClient(BaseAsyncClient):
             deployment_id: the deployment ID of interest
 
         Returns:
-            a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment
+            a Deployment model representation of the deployment
         """
 
         from prefect.client.schemas.responses import DeploymentResponse

prefect/client/orchestration/_flows/client.py

@@ -31,7 +31,7 @@ class FlowClient(BaseClient):
         Create a flow in the Prefect API.
 
         Args:
-            flow: a [Flow][prefect.flows.Flow] object
+            flow: a `Flow` object
 
         Raises:
             httpx.RequestError: if a flow was not created for any reason
@@ -78,7 +78,7 @@ class FlowClient(BaseClient):
             flow_id: the flow ID of interest
 
         Returns:
-            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow
+            a Flow model representation of the flow
         """
         response = self.request("GET", "/flows/{id}", path_params={"id": flow_id})
         from prefect.client.schemas.objects import Flow
@@ -190,7 +190,7 @@ class FlowAsyncClient(BaseAsyncClient):
         Create a flow in the Prefect API.
 
         Args:
-            flow: a [Flow][prefect.flows.Flow] object
+            flow: a `Flow` object
 
         Raises:
             httpx.RequestError: if a flow was not created for any reason
@@ -237,7 +237,7 @@ class FlowAsyncClient(BaseAsyncClient):
             flow_id: the flow ID of interest
 
         Returns:
-            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow
+            a Flow model representation of the flow
         """
         response = await self.request("GET", "/flows/{id}", path_params={"id": flow_id})
         from prefect.client.schemas.objects import Flow

prefect/client/schemas/__init__.py

@@ -11,11 +11,12 @@ if TYPE_CHECKING:
         BlockType,
         FlowRun,
         FlowRunPolicy,
+        FlowRunResult,
         State,
         StateDetails,
         StateType,
         TaskRun,
-        TaskRunInput,
+        RunInput,
         TaskRunPolicy,
         TaskRunResult,
         Workspace,
@@ -36,6 +37,7 @@ _public_api = {
     "DEFAULT_BLOCK_SCHEMA_VERSION": (__package__, ".objects"),
     "FlowRun": (__package__, ".objects"),
     "FlowRunPolicy": (__package__, ".objects"),
+    "FlowRunResult": (__package__, ".objects"),
     "OrchestrationResult": (__package__, ".responses"),
     "SetStateStatus": (__package__, ".responses"),
     "State": (__package__, ".objects"),
@@ -60,6 +62,7 @@ __all__ = [
     "DEFAULT_BLOCK_SCHEMA_VERSION",
     "FlowRun",
     "FlowRunPolicy",
+    "FlowRunResult",
     "OrchestrationResult",
     "SetStateStatus",
     "State",
@@ -70,7 +73,7 @@ __all__ = [
     "StateRejectDetails",
     "StateType",
     "TaskRun",
-    "TaskRunInput",
+    "RunInput",
     "TaskRunPolicy",
     "TaskRunResult",
     "Workspace",

prefect/client/schemas/actions.py

@@ -443,6 +443,7 @@ class TaskRunCreate(ActionBaseModel):
         list[
             Union[
                 objects.TaskRunResult,
+                objects.FlowRunResult,
                 objects.Parameter,
                 objects.Constant,
             ]

prefect/client/schemas/filters.py

@@ -462,6 +462,9 @@ class DeploymentFilterId(PrefectBaseModel):
     any_: Optional[List[UUID]] = Field(
         default=None, description="A list of deployment ids to include"
     )
+    not_any_: Optional[List[UUID]] = Field(
+        default=None, description="A list of deployment ids to exclude"
+    )
 
 
 class DeploymentFilterName(PrefectBaseModel):

prefect/client/schemas/objects.py

@@ -81,6 +81,11 @@ DEFAULT_BLOCK_SCHEMA_VERSION: Literal["non-versioned"] = "non-versioned"
 DEFAULT_AGENT_WORK_POOL_NAME: Literal["default-agent-pool"] = "default-agent-pool"
 
 
+class RunType(AutoEnum):
+    FLOW_RUN = "flow_run"
+    TASK_RUN = "task_run"
+
+
 class StateType(AutoEnum):
     """Enumeration of state types."""
 
@@ -164,7 +169,6 @@ class ConcurrencyLimitConfig(PrefectBaseModel):
 class StateDetails(PrefectBaseModel):
     flow_run_id: Optional[UUID] = None
     task_run_id: Optional[UUID] = None
-    # for task runs that represent subflows, the subflow's run ID
     child_flow_run_id: Optional[UUID] = None
     scheduled_time: Optional[DateTime] = None
     cache_key: Optional[str] = None
@@ -182,6 +186,16 @@ class StateDetails(PrefectBaseModel):
     # Captures the trace_id and span_id of the span where this state was created
     traceparent: Optional[str] = None
 
+    def to_run_result(
+        self, run_type: RunType
+    ) -> Optional[Union[FlowRunResult, TaskRunResult]]:
+        if run_type == run_type.FLOW_RUN and self.flow_run_id:
+            return FlowRunResult(id=self.flow_run_id)
+        elif run_type == run_type.TASK_RUN and self.task_run_id:
+            return TaskRunResult(id=self.task_run_id)
+        else:
+            return None
+
 
 def data_discriminator(x: Any) -> str:
     if isinstance(x, dict) and "storage_key" in x:
@@ -279,10 +293,6 @@ class State(TimeSeriesBaseModel, ObjectBaseModel, Generic[R]):
                 if the state is of type `FAILED` and the underlying data is an exception. When flow
                 was run in a different memory space (using `run_deployment`), this will only raise
                 if `fetch` is `True`.
-            fetch: a boolean specifying whether to resolve references to persisted
-                results into data. For synchronous users, this defaults to `True`.
-                For asynchronous users, this defaults to `False` for backwards
-                compatibility.
             retry_result_failure: a boolean specifying whether to retry on failures to
                 load the result from result storage
 
@@ -738,7 +748,7 @@ class TaskRunPolicy(PrefectBaseModel):
         return validate_not_negative(v)
 
 
-class TaskRunInput(PrefectBaseModel):
+class RunInput(PrefectBaseModel):
     """
     Base class for classes that represent inputs to task runs, which
     could include, constants, parameters, or other task runs.
@@ -751,21 +761,26 @@ class TaskRunInput(PrefectBaseModel):
         input_type: str
 
 
-class TaskRunResult(TaskRunInput):
+class TaskRunResult(RunInput):
     """Represents a task run result input to another task run."""
 
     input_type: Literal["task_run"] = "task_run"
     id: UUID
 
 
-class Parameter(TaskRunInput):
+class FlowRunResult(RunInput):
+    input_type: Literal["flow_run"] = "flow_run"
+    id: UUID
+
+
+class Parameter(RunInput):
     """Represents a parameter input to a task run."""
 
     input_type: Literal["parameter"] = "parameter"
     name: str
 
 
-class Constant(TaskRunInput):
+class Constant(RunInput):
     """Represents constant input value to a task run."""
 
     input_type: Literal["constant"] = "constant"
@@ -815,7 +830,9 @@ class TaskRun(TimeSeriesBaseModel, ObjectBaseModel):
     state_id: Optional[UUID] = Field(
         default=None, description="The id of the current task run state."
     )
-    task_inputs: dict[str, list[Union[TaskRunResult, Parameter, Constant]]] = Field(
+    task_inputs: dict[
+        str, list[Union[TaskRunResult, FlowRunResult, Parameter, Constant]]
+    ] = Field(
         default_factory=dict,
         description=(
             "Tracks the source of inputs to a task run. Used for internal bookkeeping. "

prefect/context.py

@@ -34,6 +34,7 @@ from prefect._internal.compatibility.migration import getattr_migration
 from prefect.assets import Asset
 from prefect.client.orchestration import PrefectClient, SyncPrefectClient, get_client
 from prefect.client.schemas import FlowRun, TaskRun
+from prefect.client.schemas.objects import RunType
 from prefect.events.worker import EventsWorker
 from prefect.exceptions import MissingContextError
 from prefect.results import (
@@ -363,7 +364,7 @@ class EngineContext(RunContext):
         flow: The flow instance associated with the run
         flow_run: The API metadata for the flow run
         task_runner: The task runner instance being used for the flow run
-        task_run_results: A mapping of result ids to task run states for this flow run
+        run_results: A mapping of result ids to run states for this flow run
         log_prints: Whether to log print statements from the flow run
         parameters: The parameters passed to the flow run
         detached: Flag indicating if context has been serialized and sent to remote infrastructure
@@ -394,9 +395,10 @@ class EngineContext(RunContext):
     # Counter for flow pauses
     observed_flow_pauses: dict[str, int] = Field(default_factory=dict)
 
-    # Tracking for result from task runs in this flow run for dependency tracking
-    # Holds the ID of the object returned by the task run and task run state
-    task_run_results: dict[int, State] = Field(default_factory=dict)
+    # Tracking for result from task runs and sub flows in this flow run for
+    # dependency tracking. Holds the ID of the object returned by
+    # the run and state
+    run_results: dict[int, tuple[State, RunType]] = Field(default_factory=dict)
 
     # Tracking information needed to track asset linage between
     # tasks and materialization
@@ -492,6 +494,7 @@ class AssetContext(ContextModel):
     materialized_by: Optional[str] = None
     task_run_id: Optional[UUID] = None
     materialization_metadata: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    copy_to_child_ctx: bool = False
 
     __var__: ClassVar[ContextVar[Self]] = ContextVar("asset_context")
 
@@ -501,6 +504,7 @@ class AssetContext(ContextModel):
         task: "Task[Any, Any]",
         task_run_id: UUID,
         task_inputs: Optional[dict[str, set[Any]]] = None,
+        copy_to_child_ctx: bool = False,
     ) -> "AssetContext":
         """
         Create an AssetContext from a task and its resolved inputs.
@@ -509,6 +513,7 @@ class AssetContext(ContextModel):
             task: The task instance
             task_run_id: The task run ID
             task_inputs: The resolved task inputs (TaskRunResult objects)
+            copy_to_child_ctx: Whether this context should be copied on a child AssetContext
 
         Returns:
             Configured AssetContext
@@ -518,13 +523,16 @@ class AssetContext(ContextModel):
 
         upstream_assets: set[Asset] = set()
 
-        # Get upstream assets from engine context instead of TaskRunResult.assets
         flow_ctx = FlowRunContext.get()
         if task_inputs and flow_ctx:
-            for inputs in task_inputs.values():
+            for name, inputs in task_inputs.items():
+                # Parent task runs are not dependencies
+                # that we want to track
+                if name == "__parents__":
+                    continue
+
                 for task_input in inputs:
                     if isinstance(task_input, TaskRunResult):
-                        # Look up assets in the engine context
                         task_assets = flow_ctx.task_run_assets.get(task_input.id)
                         if task_assets:
                             upstream_assets.update(task_assets)
@@ -541,6 +549,7 @@ class AssetContext(ContextModel):
             if isinstance(task, MaterializingTask)
             else None,
             task_run_id=task_run_id,
+            copy_to_child_ctx=copy_to_child_ctx,
         )
         ctx.update_tracked_assets()
 

prefect/events/clients.py

@@ -1,7 +1,5 @@
 import abc
 import asyncio
-import os
-import ssl
 from datetime import timedelta
 from types import TracebackType
 from typing import (
@@ -9,7 +7,6 @@ from typing import (
     Any,
     ClassVar,
     Dict,
-    Generator,
     List,
     MutableMapping,
     Optional,
@@ -17,18 +14,14 @@ from typing import (
     Type,
     cast,
 )
-from urllib.parse import urlparse
-from urllib.request import proxy_bypass
 from uuid import UUID
 
-import certifi
 import orjson
 from cachetools import TTLCache
 from prometheus_client import Counter
-from python_socks.async_.asyncio import Proxy
 from typing_extensions import Self
 from websockets import Subprotocol
-from websockets.asyncio.client import ClientConnection, connect
+from websockets.asyncio.client import ClientConnection
 from websockets.exceptions import (
     ConnectionClosed,
     ConnectionClosedError,
@@ -36,13 +29,12 @@ from websockets.exceptions import (
 )
 
 import prefect.types._datetime
+from prefect._internal.websockets import websocket_connect
 from prefect.events import Event
 from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_AUTH_STRING,
     PREFECT_API_KEY,
-    PREFECT_API_SSL_CERT_FILE,
-    PREFECT_API_TLS_INSECURE_SKIP_VERIFY,
     PREFECT_API_URL,
     PREFECT_CLOUD_API_URL,
     PREFECT_DEBUG_MODE,
@@ -94,72 +86,6 @@ def events_out_socket_from_api_url(url: str) -> str:
     return http_to_ws(url) + "/events/out"
 
 
-class WebsocketProxyConnect(connect):
-    def __init__(self: Self, uri: str, **kwargs: Any):
-        # super() is intentionally deferred to the _proxy_connect method
-        # to allow for the socket to be established first
-
-        self.uri = uri
-        self._kwargs = kwargs
-
-        u = urlparse(uri)
-        host = u.hostname
-
-        if not host:
-            raise ValueError(f"Invalid URI {uri}, no hostname found")
-
-        if u.scheme == "ws":
-            port = u.port or 80
-            proxy_url = os.environ.get("HTTP_PROXY")
-        elif u.scheme == "wss":
-            port = u.port or 443
-            proxy_url = os.environ.get("HTTPS_PROXY")
-            kwargs["server_hostname"] = host
-        else:
-            raise ValueError(
-                "Unsupported scheme %s. Expected 'ws' or 'wss'. " % u.scheme
-            )
-
-        self._proxy = (
-            Proxy.from_url(proxy_url) if proxy_url and not proxy_bypass(host) else None
-        )
-        self._host = host
-        self._port = port
-
-        if PREFECT_API_TLS_INSECURE_SKIP_VERIFY and u.scheme == "wss":
-            # Create an unverified context for insecure connections
-            ctx = ssl.create_default_context()
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE
-            self._kwargs.setdefault("ssl", ctx)
-        elif u.scheme == "wss":
-            cert_file = PREFECT_API_SSL_CERT_FILE.value()
-            if not cert_file:
-                cert_file = certifi.where()
-            # Create a verified context with the certificate file
-            ctx = ssl.create_default_context(cafile=cert_file)
-            self._kwargs.setdefault("ssl", ctx)
-
-    async def _proxy_connect(self: Self) -> ClientConnection:
-        if self._proxy:
-            sock = await self._proxy.connect(
-                dest_host=self._host,
-                dest_port=self._port,
-            )
-            self._kwargs["sock"] = sock
-
-        super().__init__(self.uri, **self._kwargs)
-        proto = await self.__await_impl__()
-        return proto
-
-    def __await__(self: Self) -> Generator[Any, None, ClientConnection]:
-        return self._proxy_connect().__await__()
-
-
-def websocket_connect(uri: str, **kwargs: Any) -> WebsocketProxyConnect:
-    return WebsocketProxyConnect(uri, **kwargs)
-
-
 def get_events_client(
     reconnection_attempts: int = 10,
     checkpoint_every: int = 700,

prefect/events/schemas/automations.py

@@ -416,6 +416,10 @@ class AutomationCore(PrefectBaseModel, extra="ignore"):  # type: ignore[call-arg
     enabled: bool = Field(
         default=True, description="Whether this automation will be evaluated"
     )
+    tags: List[str] = Field(
+        default_factory=list,
+        description="A list of tags associated with this automation",
+    )
 
     trigger: TriggerTypes = Field(
         default=...,

prefect/events/schemas/labelling.py

@@ -8,6 +8,7 @@ class LabelDiver:
     presenting the labels as a graph of objects that may be accessed by attribute.  For
     example:
 
+        ```python
         diver = LabelDiver({
             'hello.world': 'foo',
             'hello.world.again': 'bar'
@@ -15,6 +16,7 @@ class LabelDiver:
 
         assert str(diver.hello.world) == 'foo'
         assert str(diver.hello.world.again) == 'bar'
+        ```
 
     """
 

prefect/flow_engine.py

@@ -105,7 +105,7 @@ from prefect.utilities.callables import (
 from prefect.utilities.collections import visit_collection
 from prefect.utilities.engine import (
     capture_sigterm,
-    link_state_to_result,
+    link_state_to_flow_run_result,
     propose_state,
     propose_state_sync,
     resolve_to_final_result,
@@ -338,6 +338,7 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             self._return_value, State
         ):
             _result = self._return_value
+            link_state_to_flow_run_result(self.state, _result)
 
             if asyncio.iscoroutine(_result):
                 # getting the value for a BaseResult may return an awaitable
@@ -373,6 +374,7 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
         self.set_state(terminal_state)
         self._return_value = resolved_result
 
+        link_state_to_flow_run_result(terminal_state, resolved_result)
         self._telemetry.end_span_on_success()
 
         return result
@@ -903,6 +905,7 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             self._return_value, State
         ):
             _result = self._return_value
+            link_state_to_flow_run_result(self.state, _result)
 
             if asyncio.iscoroutine(_result):
                 # getting the value for a BaseResult may return an awaitable
@@ -1426,7 +1429,7 @@ def run_generator_flow_sync(
                     while True:
                         gen_result = next(gen)
                         # link the current state to the result for dependency tracking
-                        link_state_to_result(engine.state, gen_result)
+                        link_state_to_flow_run_result(engine.state, gen_result)
                         yield gen_result
                 except StopIteration as exc:
                     engine.handle_success(exc.value)
@@ -1468,7 +1471,7 @@ async def run_generator_flow_async(
                         # can't use anext in Python < 3.10
                         gen_result = await gen.__anext__()
                         # link the current state to the result for dependency tracking
-                        link_state_to_result(engine.state, gen_result)
+                        link_state_to_flow_run_result(engine.state, gen_result)
                         yield gen_result
                 except (StopAsyncIteration, GeneratorExit) as exc:
                     await engine.handle_success(None)