prefect-client 3.4.7.dev3__py3-none-any.whl → 3.4.7.dev5__py3-none-any.whl

prefect/AGENTS.md

@@ -1,38 +1,28 @@
-# Core Prefect Library
+# Core Prefect SDK
 
-This is the core Prefect library containing the fundamental building blocks for workflow orchestration.
+The foundation for building and executing workflows with Python.
 
-## Core Concepts
+## Key Components
 
-- **Flows**: Top-level workflow containers defined with `@flow` decorator
-- **Tasks**: Individual units of work defined with `@task` decorator  
-- **States**: Represent the status of flow/task runs (Pending, Running, Completed, Failed, etc.)
-- **Context**: Runtime information available during flow/task execution
-- **Results**: Persistence layer for task outputs and artifacts
+- **Flows & Tasks**: Workflow definition with `@flow` and `@task` decorators
+- **States**: Execution status tracking (Pending, Running, Completed, Failed)
+- **Context**: Runtime information and dependency injection
+- **Results**: Task output persistence and retrieval
+- **Deployments**: Packaging flows for scheduled/triggered execution
+- **Blocks**: Reusable configuration for external systems
 
-## Key Modules
+## Main Modules
 
-- `flows.py` - Flow definition, execution, and lifecycle management
-- `tasks.py` - Task definition, execution, and dependency resolution
-- `states.py` - State management and transitions
-- `context.py` - Runtime context and dependency injection
+- `flows.py` - Flow lifecycle and execution
+- `tasks.py` - Task definition and dependency resolution
 - `engine.py` - Core execution engine
-- `client/` - Client interfaces for communicating with Prefect server/cloud
-- `runner/` - Process management for running flows
-- `deployments/` - Deployment creation and management
-- `blocks/` - Reusable configuration and infrastructure components
+- `client/` - Server/Cloud API communication
+- `deployments/` - Deployment management
+- `blocks/` - Infrastructure and storage blocks
 
-## Execution Architecture
+## SDK-Specific Notes
 
-Prefect uses an asynchronous execution model:
-- Flows and tasks are async by default but support sync execution
-- Task dependencies are resolved through return value tracking
-- State management handles retries, caching, and failure policies
-- Results are persisted and retrievable across runs
-
-## Development Patterns
-
-- Prefer composition over inheritance for extensibility
-- Use dependency injection through context for runtime services
-- Maintain backward compatibility in public APIs
-- Task and flow definitions are immutable after creation 
+- Async-first execution model with sync support
+- Immutable flow/task definitions after creation
+- State transitions handle retries and caching
+- Backward compatibility required for public APIs

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.4.7.dev3"
-__build_date__ = "2025-06-17 08:09:28.549090+00:00"
-__git_commit__ = "a40dd41d3b8dc001c893d5a5d778016da797aa82"
+__version__ = "3.4.7.dev5"
+__build_date__ = "2025-06-19 08:09:38.201573+00:00"
+__git_commit__ = "3636ab85f878dffcfcb3a5f9a67055bd0219e63f"
 __dirty__ = False

prefect/_internal/websockets.py

@@ -0,0 +1,106 @@
+"""
+Internal WebSocket proxy utilities for Prefect client connections.
+
+This module provides shared WebSocket proxy connection logic and SSL configuration
+to avoid duplication between events and logs clients.
+"""
+
+import os
+import ssl
+from typing import Any, Generator, Optional
+from urllib.parse import urlparse
+from urllib.request import proxy_bypass
+
+import certifi
+from python_socks.async_.asyncio import Proxy
+from typing_extensions import Self
+from websockets.asyncio.client import ClientConnection, connect
+
+from prefect.settings import get_current_settings
+
+
+def create_ssl_context_for_websocket(uri: str) -> Optional[ssl.SSLContext]:
+    """Create SSL context for WebSocket connections based on URI scheme."""
+    u = urlparse(uri)
+
+    if u.scheme != "wss":
+        return None
+
+    if get_current_settings().api.tls_insecure_skip_verify:
+        # Create an unverified context for insecure connections
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        return ctx
+    else:
+        # Create a verified context with the certificate file
+        cert_file = get_current_settings().api.ssl_cert_file
+        if not cert_file:
+            cert_file = certifi.where()
+        return ssl.create_default_context(cafile=cert_file)
+
+
+class WebsocketProxyConnect(connect):
+    """
+    WebSocket connection class with proxy and SSL support.
+
+    Extends the websockets.asyncio.client.connect class to add HTTP/HTTPS
+    proxy support via environment variables, proxy bypass logic, and SSL
+    certificate verification.
+    """
+
+    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
+
+        # Configure SSL context for HTTPS connections
+        ssl_context = create_ssl_context_for_websocket(uri)
+        if ssl_context:
+            self._kwargs.setdefault("ssl", ssl_context)
+
+    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:
+    """Create a WebSocket connection with proxy and SSL support."""
+    return WebsocketProxyConnect(uri, **kwargs)

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,
@@ -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,

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/logging/clients.py

@@ -0,0 +1,347 @@
+import asyncio
+from datetime import timedelta
+from types import TracebackType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    MutableMapping,
+    Optional,
+    Tuple,
+    Type,
+    cast,
+)
+from uuid import UUID
+
+import orjson
+from cachetools import TTLCache
+from prometheus_client import Counter
+from typing_extensions import Self
+from websockets import Subprotocol
+from websockets.asyncio.client import ClientConnection
+from websockets.exceptions import (
+    ConnectionClosed,
+    ConnectionClosedError,
+    ConnectionClosedOK,
+)
+
+from prefect._internal.websockets import (
+    create_ssl_context_for_websocket,
+    websocket_connect,
+)
+from prefect.client.schemas.objects import Log
+from prefect.logging import get_logger
+from prefect.settings import (
+    PREFECT_API_AUTH_STRING,
+    PREFECT_API_KEY,
+    PREFECT_API_URL,
+    PREFECT_CLOUD_API_URL,
+    PREFECT_SERVER_ALLOW_EPHEMERAL_MODE,
+)
+from prefect.types._datetime import now
+
+if TYPE_CHECKING:
+    import logging
+
+    from prefect.client.schemas.filters import LogFilter
+
+logger: "logging.Logger" = get_logger(__name__)
+
+LOGS_OBSERVED = Counter(
+    "prefect_logs_observed",
+    "The number of logs observed by Prefect log subscribers",
+    labelnames=["client"],
+)
+LOG_WEBSOCKET_CONNECTIONS = Counter(
+    "prefect_log_websocket_connections",
+    (
+        "The number of times Prefect log clients have connected to a log stream, "
+        "broken down by direction (in/out) and connection (initial/reconnect)"
+    ),
+    labelnames=["client", "direction", "connection"],
+)
+
+SEEN_LOGS_SIZE = 500_000
+SEEN_LOGS_TTL = 120
+
+
+def http_to_ws(url: str) -> str:
+    return url.replace("https://", "wss://").replace("http://", "ws://").rstrip("/")
+
+
+def logs_out_socket_from_api_url(url: str) -> str:
+    return http_to_ws(url) + "/logs/out"
+
+
+def _get_api_url_and_key(
+    api_url: Optional[str], api_key: Optional[str]
+) -> Tuple[str, str]:
+    api_url = api_url or PREFECT_API_URL.value()
+    api_key = api_key or PREFECT_API_KEY.value()
+
+    if not api_url or not api_key:
+        raise ValueError(
+            "api_url and api_key must be provided or set in the Prefect configuration"
+        )
+
+    return api_url, api_key
+
+
+def get_logs_subscriber(
+    filter: Optional["LogFilter"] = None,
+    reconnection_attempts: int = 10,
+) -> "PrefectLogsSubscriber":
+    """
+    Get a logs subscriber based on the current Prefect configuration.
+
+    Similar to get_events_subscriber, this automatically detects whether
+    you're using Prefect Cloud or OSS and returns the appropriate subscriber.
+    """
+    api_url = PREFECT_API_URL.value()
+
+    if isinstance(api_url, str) and api_url.startswith(PREFECT_CLOUD_API_URL.value()):
+        return PrefectCloudLogsSubscriber(
+            filter=filter, reconnection_attempts=reconnection_attempts
+        )
+    elif api_url:
+        return PrefectLogsSubscriber(
+            api_url=api_url,
+            filter=filter,
+            reconnection_attempts=reconnection_attempts,
+        )
+    elif PREFECT_SERVER_ALLOW_EPHEMERAL_MODE:
+        from prefect.server.api.server import SubprocessASGIServer
+
+        server = SubprocessASGIServer()
+        server.start()
+        return PrefectLogsSubscriber(
+            api_url=server.api_url,
+            filter=filter,
+            reconnection_attempts=reconnection_attempts,
+        )
+    else:
+        raise ValueError(
+            "No Prefect API URL provided. Please set PREFECT_API_URL to the address of a running Prefect server."
+        )
+
+
+class PrefectLogsSubscriber:
+    """
+    Subscribes to a Prefect logs stream, yielding logs as they occur.
+
+    Example:
+
+        from prefect.logging.clients import PrefectLogsSubscriber
+        from prefect.client.schemas.filters import LogFilter, LogFilterLevel
+        import logging
+
+        filter = LogFilter(level=LogFilterLevel(ge_=logging.INFO))
+
+        async with PrefectLogsSubscriber(filter=filter) as subscriber:
+            async for log in subscriber:
+                print(log.timestamp, log.level, log.message)
+
+    """
+
+    _websocket: Optional[ClientConnection]
+    _filter: "LogFilter"
+    _seen_logs: MutableMapping[UUID, bool]
+
+    _api_key: Optional[str]
+    _auth_token: Optional[str]
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        filter: Optional["LogFilter"] = None,
+        reconnection_attempts: int = 10,
+    ):
+        """
+        Args:
+            api_url: The base URL for a Prefect workspace
+            filter: Log filter to apply
+            reconnection_attempts: When the client is disconnected, how many times
+                the client should attempt to reconnect
+        """
+        self._api_key = None
+        self._auth_token = PREFECT_API_AUTH_STRING.value()
+
+        if not api_url:
+            api_url = cast(str, PREFECT_API_URL.value())
+
+        from prefect.client.schemas.filters import LogFilter
+
+        self._filter = filter or LogFilter()  # type: ignore[call-arg]
+        self._seen_logs = TTLCache(maxsize=SEEN_LOGS_SIZE, ttl=SEEN_LOGS_TTL)
+
+        socket_url = logs_out_socket_from_api_url(api_url)
+
+        logger.debug("Connecting to %s", socket_url)
+
+        # Configure SSL context for the connection
+        ssl_context = create_ssl_context_for_websocket(socket_url)
+        connect_kwargs: dict[str, Any] = {"subprotocols": [Subprotocol("prefect")]}
+        if ssl_context:
+            connect_kwargs["ssl"] = ssl_context
+
+        self._connect = websocket_connect(socket_url, **connect_kwargs)
+        self._websocket = None
+        self._reconnection_attempts = reconnection_attempts
+        if self._reconnection_attempts < 0:
+            raise ValueError("reconnection_attempts must be a non-negative integer")
+
+    @property
+    def client_name(self) -> str:
+        return self.__class__.__name__
+
+    async def __aenter__(self) -> Self:
+        # Don't handle any errors in the initial connection, because these are most
+        # likely a permission or configuration issue that should propagate
+        try:
+            await self._reconnect()
+        finally:
+            LOG_WEBSOCKET_CONNECTIONS.labels(self.client_name, "out", "initial").inc()
+        return self
+
+    async def _reconnect(self) -> None:
+        logger.debug("Reconnecting...")
+        if self._websocket:
+            self._websocket = None
+            await self._connect.__aexit__(None, None, None)
+
+        self._websocket = await self._connect.__aenter__()
+
+        # make sure we have actually connected
+        logger.debug("  pinging...")
+        pong = await self._websocket.ping()
+        await pong
+
+        # Send authentication message - logs WebSocket requires auth handshake
+        auth_token = self._api_key or self._auth_token
+        auth_message = {"type": "auth", "token": auth_token}
+        logger.debug("  authenticating...")
+        await self._websocket.send(orjson.dumps(auth_message).decode())
+
+        # Wait for auth response
+        try:
+            message = orjson.loads(await self._websocket.recv())
+            logger.debug("  auth result %s", message)
+            assert message["type"] == "auth_success", message.get("reason", "")
+        except AssertionError as e:
+            raise Exception(
+                "Unable to authenticate to the log stream. Please ensure the "
+                "provided api_key or auth_token you are using is valid for this environment. "
+                f"Reason: {e.args[0]}"
+            )
+        except ConnectionClosedError as e:
+            reason = getattr(e.rcvd, "reason", None)
+            msg = "Unable to authenticate to the log stream. Please ensure the "
+            msg += "provided api_key or auth_token you are using is valid for this environment. "
+            msg += f"Reason: {reason}" if reason else ""
+            raise Exception(msg) from e
+
+        from prefect.client.schemas.filters import LogFilterTimestamp
+
+        current_time = now("UTC")
+        self._filter.timestamp = LogFilterTimestamp(
+            after_=current_time - timedelta(minutes=1),  # type: ignore[arg-type]
+            before_=current_time + timedelta(days=365),  # type: ignore[arg-type]
+        )
+
+        logger.debug("  filtering logs since %s...", self._filter.timestamp.after_)
+        filter_message = {
+            "type": "filter",
+            "filter": self._filter.model_dump(mode="json"),
+        }
+        await self._websocket.send(orjson.dumps(filter_message).decode())
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        self._websocket = None
+        await self._connect.__aexit__(exc_type, exc_val, exc_tb)
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> Log:
+        assert self._reconnection_attempts >= 0
+        for i in range(self._reconnection_attempts + 1):  # pragma: no branch
+            try:
+                # If we're here and the websocket is None, then we've had a failure in a
+                # previous reconnection attempt.
+                #
+                # Otherwise, after the first time through this loop, we're recovering
+                # from a ConnectionClosed, so reconnect now.
+                if not self._websocket or i > 0:
+                    try:
+                        await self._reconnect()
+                    finally:
+                        LOG_WEBSOCKET_CONNECTIONS.labels(
+                            self.client_name, "out", "reconnect"
+                        ).inc()
+                    assert self._websocket
+
+                while True:
+                    message = orjson.loads(await self._websocket.recv())
+                    log: Log = Log.model_validate(message["log"])
+
+                    if log.id in self._seen_logs:
+                        continue
+                    self._seen_logs[log.id] = True
+
+                    try:
+                        return log
+                    finally:
+                        LOGS_OBSERVED.labels(self.client_name).inc()
+
+            except ConnectionClosedOK:
+                logger.debug('Connection closed with "OK" status')
+                raise StopAsyncIteration
+            except ConnectionClosed:
+                logger.debug(
+                    "Connection closed with %s/%s attempts",
+                    i + 1,
+                    self._reconnection_attempts,
+                )
+                if i == self._reconnection_attempts:
+                    # this was our final chance, raise the most recent error
+                    raise
+
+                if i > 2:
+                    # let the first two attempts happen quickly in case this is just
+                    # a standard load balancer timeout, but after that, just take a
+                    # beat to let things come back around.
+                    await asyncio.sleep(1)
+        raise StopAsyncIteration
+
+
+class PrefectCloudLogsSubscriber(PrefectLogsSubscriber):
+    """Logs subscriber for Prefect Cloud"""
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        filter: Optional["LogFilter"] = None,
+        reconnection_attempts: int = 10,
+    ):
+        """
+        Args:
+            api_url: The base URL for a Prefect Cloud workspace
+            api_key: The API key of an actor with the see_flows scope
+            filter: Log filter to apply
+            reconnection_attempts: When the client is disconnected, how many times
+                the client should attempt to reconnect
+        """
+        api_url, api_key = _get_api_url_and_key(api_url, api_key)
+
+        super().__init__(
+            api_url=api_url,
+            filter=filter,
+            reconnection_attempts=reconnection_attempts,
+        )
+
+        self._api_key = api_key

prefect/runner/runner.py

@@ -945,7 +945,7 @@ class Runner:
         """
         self._logger.info("Pausing all deployments...")
         for deployment_id in self._deployment_ids:
-            await self._client.set_deployment_paused_state(deployment_id, True)
+            await self._client.pause_deployment(deployment_id)
             self._logger.debug(f"Paused deployment '{deployment_id}'")
 
         self._logger.info("All deployments have been paused!")

prefect/server/api/logs.py

@@ -2,16 +2,20 @@
 Routes for interacting with log objects.
 """
 
-from typing import List
+from typing import Optional, Sequence
 
 from fastapi import Body, Depends, WebSocket, status
+from pydantic import TypeAdapter
 from starlette.status import WS_1002_PROTOCOL_ERROR
 
 import prefect.server.api.dependencies as dependencies
 import prefect.server.models as models
-import prefect.server.schemas as schemas
 from prefect.server.database import PrefectDBInterface, provide_database_interface
 from prefect.server.logs import stream
+from prefect.server.schemas.actions import LogCreate
+from prefect.server.schemas.core import Log
+from prefect.server.schemas.filters import LogFilter
+from prefect.server.schemas.sorting import LogSort
 from prefect.server.utilities import subscriptions
 from prefect.server.utilities.server import PrefectRouter
 
@@ -20,7 +24,7 @@ router: PrefectRouter = PrefectRouter(prefix="/logs", tags=["Logs"])
 
 @router.post("/", status_code=status.HTTP_201_CREATED)
 async def create_logs(
-    logs: List[schemas.actions.LogCreate],
+    logs: Sequence[LogCreate],
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> None:
     """
@@ -33,31 +37,32 @@ async def create_logs(
             await models.logs.create_logs(session=session, logs=batch)
 
 
+logs_adapter: TypeAdapter[Sequence[Log]] = TypeAdapter(Sequence[Log])
+
+
 @router.post("/filter")
 async def read_logs(
     limit: int = dependencies.LimitBody(),
     offset: int = Body(0, ge=0),
-    logs: schemas.filters.LogFilter = None,
-    sort: schemas.sorting.LogSort = Body(schemas.sorting.LogSort.TIMESTAMP_ASC),
+    logs: Optional[LogFilter] = None,
+    sort: LogSort = Body(LogSort.TIMESTAMP_ASC),
     db: PrefectDBInterface = Depends(provide_database_interface),
-) -> List[schemas.core.Log]:
+) -> Sequence[Log]:
     """
     Query for logs.
     """
     async with db.session_context() as session:
-        return await models.logs.read_logs(
-            session=session, log_filter=logs, offset=offset, limit=limit, sort=sort
+        return logs_adapter.validate_python(
+            await models.logs.read_logs(
+                session=session, log_filter=logs, offset=offset, limit=limit, sort=sort
+            )
         )
 
 
 @router.websocket("/out")
-async def stream_logs_out(
-    websocket: WebSocket,
-) -> None:
+async def stream_logs_out(websocket: WebSocket) -> None:
     """Serve a WebSocket to stream live logs"""
-    websocket = await subscriptions.accept_prefect_socket(
-        websocket,
-    )
+    websocket = await subscriptions.accept_prefect_socket(websocket)
     if not websocket:
         return
 
@@ -72,7 +77,7 @@ async def stream_logs_out(
             )
 
         try:
-            filter = schemas.filters.LogFilter.model_validate(message["filter"])
+            filter = LogFilter.model_validate(message["filter"])
         except Exception as e:
             return await websocket.close(
                 WS_1002_PROTOCOL_ERROR, reason=f"Invalid filter: {e}"

{prefect_client-3.4.7.dev3.dist-info → prefect_client-3.4.7.dev5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.4.7.dev3
+Version: 3.4.7.dev5
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect_client-3.4.7.dev3.dist-info → prefect_client-3.4.7.dev5.dist-info}/RECORD

@@ -1,8 +1,8 @@
 prefect/.prefectignore,sha256=awSprvKT0vI8a64mEOLrMxhxqcO-b0ERQeYpA2rNKVQ,390
-prefect/AGENTS.md,sha256=y9wvcT-AJ7zaP58Vj6IPoGEL82Fhw9X15UlnvGGoD0k,1645
+prefect/AGENTS.md,sha256=qmCZAuKIF9jQyp5TrW_T8bsM_97-QaiCoQp71A_b2Lg,1008
 prefect/__init__.py,sha256=iCdcC5ZmeewikCdnPEP6YBAjPNV5dvfxpYCTpw30Hkw,3685
 prefect/__main__.py,sha256=WFjw3kaYJY6pOTA7WDOgqjsz8zUEUZHCcj3P5wyVa-g,66
-prefect/_build_info.py,sha256=8xVqpc5-nJMEr7cLce8MxOqYg18OrvFqwHYf_UbNSpY,185
+prefect/_build_info.py,sha256=j5vWqNJWh9LFc4M6XTXV72BgaN0wiTsLUGw4b6gVmco,185
 prefect/_result_records.py,sha256=S6QmsODkehGVSzbMm6ig022PYbI6gNKz671p_8kBYx4,7789
 prefect/_versioning.py,sha256=YqR5cxXrY4P6LM1Pmhd8iMo7v_G2KJpGNdsf4EvDFQ0,14132
 prefect/_waiters.py,sha256=Ia2ITaXdHzevtyWIgJoOg95lrEXQqNEOquHvw3T33UQ,9026
@@ -45,6 +45,7 @@ prefect/_internal/integrations.py,sha256=U4cZMDbnilzZSKaMxvzZcSL27a1tzRMjDoTfr2u
 prefect/_internal/pytz.py,sha256=Sy_cD-Hkmo_Yrhx2Jucy7DgTRhvO8ZD0whW1ywbSg_U,13765
 prefect/_internal/retries.py,sha256=pMHofrTQPDSxbVWclDwXbfhFKaDC6sxe1DkUOWugV6k,3040
 prefect/_internal/uuid7.py,sha256=yvndhibNDrqnYrG-qUncas4XQp8bKVbmM8XfF7JrjJI,4203
+prefect/_internal/websockets.py,sha256=CloIdusf2Bbefdit46pT91cVDudeYtztPI-MmqSnuLI,3466
 prefect/_internal/compatibility/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 prefect/_internal/compatibility/async_dispatch.py,sha256=cUXOqSeseMUaje9oYUzasVPtNttyiHvrqfJl0zK66XI,2949
 prefect/_internal/compatibility/blocks.py,sha256=SSZXoWVuCMYu1EzjqmTa4lKjDCyxvOFK47XMj6s4hsk,984
@@ -106,7 +107,7 @@ prefect/client/orchestration/_blocks_types/client.py,sha256=alA4xD-yp3mycAbzMyRu
 prefect/client/orchestration/_concurrency_limits/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 prefect/client/orchestration/_concurrency_limits/client.py,sha256=r_oyY7hQbgyG1rntwe7WWcsraQHBKhk6MOPFUAHWiVc,23678
 prefect/client/orchestration/_deployments/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-prefect/client/orchestration/_deployments/client.py,sha256=a_sUmznQC3lBLxXfu4hIIbszbUc28sWXtCioQoNgZPk,43876
+prefect/client/orchestration/_deployments/client.py,sha256=KMA_ldpBiUVqvV2-FSOgARyb3objs8MAAe1uD-RXcaE,48477
 prefect/client/orchestration/_flow_runs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 prefect/client/orchestration/_flow_runs/client.py,sha256=fjh5J-LG8tsny7BGYEvynbuGuHDAudYHpx-PamL0GYQ,32220
 prefect/client/orchestration/_flows/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -154,7 +155,7 @@ prefect/docker/__init__.py,sha256=z6wdc6UFfiBG2jb9Jk64uCWVM04JKVWeVyDWwuuon8M,52
 prefect/docker/docker_image.py,sha256=bR_pEq5-FDxlwTj8CP_7nwZ_MiGK6KxIi8v7DRjy1Kg,3138
 prefect/events/__init__.py,sha256=GtKl2bE--pJduTxelH2xy7SadlLJmmis8WR1EYixhuA,2094
 prefect/events/actions.py,sha256=A7jS8bo4zWGnrt3QfSoQs0uYC1xfKXio3IfU0XtTb5s,9129
-prefect/events/clients.py,sha256=r_C3ZevVYUzIW53CpmFbEtR2DwhYeYB4budtB3GaYl0,27625
+prefect/events/clients.py,sha256=pvCbvPcehDhaFEJfeu1DzUP6RhBhacKU7L5Z4XPSvIE,25132
 prefect/events/filters.py,sha256=tnAbA4Z0Npem8Jbin-qqe38K_4a-4YdpU-Oc4u8Y95Q,8697
 prefect/events/related.py,sha256=CTeexYUmmA93V4gsR33GIFmw-SS-X_ouOpRg-oeq-BU,6672
 prefect/events/utilities.py,sha256=ww34bTMENCNwcp6RhhgzG0KgXOvKGe0MKmBdSJ8NpZY,3043
@@ -182,6 +183,7 @@ prefect/locking/filesystem.py,sha256=PxC9ndDbo59-gBEx9jtKad4T-Jav0srJSM9vYGzvQwE
 prefect/locking/memory.py,sha256=EFQnhAO94jEy4TyS880DbsJ42CHT5WNuNc6Wj8dYrKc,7842
 prefect/locking/protocol.py,sha256=RsfvlaHTTEJ0YvYWSqFGoZuT2w4FPPxyQlHqjoyNGuE,4240
 prefect/logging/__init__.py,sha256=DpRZzZeWeiDHFlMDEQdknRzbxpL0ObFh5IqqS9iaZwQ,170
+prefect/logging/clients.py,sha256=nKEv-Xfzy5QwtFmZvNirBI8G5YraZ9YzuIkKHb4XVXM,11825
 prefect/logging/configuration.py,sha256=go9lA4W5HMpK6azDz_ez2YqgQ2b3aCFXxJH-AopoHy8,3404
 prefect/logging/filters.py,sha256=NnRYubh9dMmWcCAjuW32cIVQ37rLxdn8ci26wTtQMyU,1136
 prefect/logging/formatters.py,sha256=Sum42BmYZ7mns64jSOy4OA_K8KudEZjeG2h7SZcY9mA,4167
@@ -191,7 +193,7 @@ prefect/logging/loggers.py,sha256=rwFJv0i3dhdKr25XX-xUkQy4Vv4dy18bTy366jrC0OQ,12
 prefect/logging/logging.yml,sha256=G5hFJ57Vawz40_w8tDdhqq00dp103OvVDVmWrSQeQcQ,3285
 prefect/runner/__init__.py,sha256=pQBd9wVrUVUDUFJlgiweKSnbahoBZwqnd2O2jkhrULY,158
 prefect/runner/_observers.py,sha256=PpyXQL5bjp86AnDFEzcFPS5ayL6ExqcYgyuBMMQCO9Q,2183
-prefect/runner/runner.py,sha256=q_3l2awvZATTTgVW3MYiElWHRWw5_ZIliUN9Ltt9d9M,59591
+prefect/runner/runner.py,sha256=bucchmFv7g4lYaxDyPtkRXZgyaBmyRpS23maMUT0AQg,59574
 prefect/runner/server.py,sha256=5vMIJcgunjiDVzJEig09yOP8EbhcW6s-9zNUt101b44,11994
 prefect/runner/storage.py,sha256=n-65YoEf7KNVInnmMPeP5TVFJOa2zOS8w9en9MHi6uo,31328
 prefect/runner/submit.py,sha256=b5n1M12DFQsxo6FazZnDbblRcIE7H3xrpecDMb4CjJY,9512
@@ -219,7 +221,7 @@ prefect/server/api/events.py,sha256=mUTv5ZNxiRsEOpzq8fpfCkLpPasjt-ROUAowA5eFbDE,
 prefect/server/api/flow_run_states.py,sha256=lIdxVE9CqLgtDCuH9bTaKkzHNL81FPrr11liPzvONrw,1661
 prefect/server/api/flow_runs.py,sha256=Lmb165fLbN4DioxjxgDYaAJ5Qxj771iRYaqn-hYq9KM,33744
 prefect/server/api/flows.py,sha256=Bz0ISh-9oY0W1X3mqA631_8678pQ6tuRGMpSgWAfxOc,7018
-prefect/server/api/logs.py,sha256=10Xsjg_cj1qY9spRe0I6lFskSEFX1RyPU0-650_gMKY,3284
+prefect/server/api/logs.py,sha256=O0W9jomHQuWF7XPMPOhW2p5Uidss6ssMqmKKwMGiv7Y,3526
 prefect/server/api/middleware.py,sha256=WkyuyeJIfo9Q0GAIVU5gO6yIGNVwoHwuBah5AB5oUyw,2733
 prefect/server/api/root.py,sha256=CeumFYIM_BDvPicJH9ry5PO_02PZTLeMqbLMGGTh90o,942
 prefect/server/api/run_history.py,sha256=EW-GTPxZAQ5zXiAqHzmS-iAN_Bn6ZSgVQksDT-ZTsyc,5995
@@ -327,7 +329,7 @@ prefect/workers/cloud.py,sha256=dPvG1jDGD5HSH7aM2utwtk6RaJ9qg13XjkA0lAIgQmY,287
 prefect/workers/process.py,sha256=Yi5D0U5AQ51wHT86GdwtImXSefe0gJf3LGq4r4z9zwM,11090
 prefect/workers/server.py,sha256=2pmVeJZiVbEK02SO6BEZaBIvHMsn6G8LzjW8BXyiTtk,1952
 prefect/workers/utilities.py,sha256=VfPfAlGtTuDj0-Kb8WlMgAuOfgXCdrGAnKMapPSBrwc,2483
-prefect_client-3.4.7.dev3.dist-info/METADATA,sha256=I7zZWLn2BwTOehFSIbkXwLGRffJwBHXUV1_Ticj2-5g,7517
-prefect_client-3.4.7.dev3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-prefect_client-3.4.7.dev3.dist-info/licenses/LICENSE,sha256=MCxsn8osAkzfxKC4CC_dLcUkU8DZLkyihZ8mGs3Ah3Q,11357
-prefect_client-3.4.7.dev3.dist-info/RECORD,,
+prefect_client-3.4.7.dev5.dist-info/METADATA,sha256=2MOLNYyWyvWP14kqrkU6eHZOXb2soCwenx0Oy3ie_zI,7517
+prefect_client-3.4.7.dev5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+prefect_client-3.4.7.dev5.dist-info/licenses/LICENSE,sha256=MCxsn8osAkzfxKC4CC_dLcUkU8DZLkyihZ8mGs3Ah3Q,11357
+prefect_client-3.4.7.dev5.dist-info/RECORD,,