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

prefect/AGENTS.md

@@ -0,0 +1,28 @@
+# Core Prefect SDK
+
+The foundation for building and executing workflows with Python.
+
+## Key Components
+
+- **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
+
+## Main Modules
+
+- `flows.py` - Flow lifecycle and execution
+- `tasks.py` - Task definition and dependency resolution
+- `engine.py` - Core execution engine
+- `client/` - Server/Cloud API communication
+- `deployments/` - Deployment management
+- `blocks/` - Infrastructure and storage blocks
+
+## SDK-Specific Notes
+
+- 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.6.dev2"
-__build_date__ = "2025-06-11 08:09:26.576114+00:00"
-__git_commit__ = "4e82c8d6b8d529a8d8804a58781a68023465c7d4"
+__version__ = "3.4.7"
+__build_date__ = "2025-06-26 21:16:06.964232+00:00"
+__git_commit__ = "cd81d15a41aece3a78ae7664b59a2ad841aef1f8"
 __dirty__ = False

prefect/_internal/websockets.py

@@ -0,0 +1,109 @@
+"""
+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
+            )
+
+        # Store proxy URL for deferred creation. Creating the proxy object here
+        # can bind asyncio futures to the wrong event loop when multiple WebSocket
+        # connections are initialized at different times (e.g., events + logs clients).
+        self._proxy_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_url:
+            # Create proxy in the current event loop context
+            proxy = Proxy.from_url(self._proxy_url)
+            sock = await 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/artifacts.py

@@ -55,7 +55,7 @@ class Artifact(ArtifactRequest):
             client: The PrefectClient
 
         Returns:
-            - The created artifact.
+            The created artifact.
         """
 
         local_client_context = asyncnullcontext(client) if client else get_client()
@@ -93,7 +93,7 @@ class Artifact(ArtifactRequest):
             client: The PrefectClient
 
         Returns:
-            - The created artifact.
+            The created artifact.
         """
 
         # Create sync client since this is a sync method.
@@ -417,6 +417,23 @@ def create_link_artifact(
 
     Returns:
         The table artifact ID.
+
+    Example:
+        ```python
+        from prefect import flow
+        from prefect.artifacts import create_link_artifact
+
+        @flow
+        def my_flow():
+            create_link_artifact(
+                link="https://www.prefect.io",
+                link_text="Prefect",
+                key="prefect-link",
+                description="This is a link to the Prefect website",
+            )
+
+        my_flow()
+        ```
     """
     new_artifact = LinkArtifact(
         key=key,
@@ -475,6 +492,22 @@ def create_markdown_artifact(
 
     Returns:
         The table artifact ID.
+
+    Example:
+        ```python
+        from prefect import flow
+        from prefect.artifacts import create_markdown_artifact
+
+        @flow
+        def my_flow():
+            create_markdown_artifact(
+                markdown="## Prefect",
+                key="prefect-markdown",
+                description="This is a markdown artifact",
+            )
+
+        my_flow()
+        ```
     """
     new_artifact = MarkdownArtifact(
         key=key,
@@ -533,6 +566,22 @@ def create_table_artifact(
 
     Returns:
         The table artifact ID.
+
+    Example:
+        ```python
+        from prefect import flow
+        from prefect.artifacts import create_table_artifact
+
+        @flow
+        def my_flow():
+            create_table_artifact(
+                table=[{"name": "John", "age": 30}, {"name": "Jane", "age": 25}],
+                key="prefect-table",
+                description="This is a table artifact",
+            )
+
+        my_flow()
+        ```
     """
 
     new_artifact = TableArtifact(

prefect/assets/core.py

@@ -5,7 +5,7 @@ from typing import Any, ClassVar, Optional
 from pydantic import ConfigDict, Field
 
 from prefect._internal.schemas.bases import PrefectBaseModel
-from prefect.types import URILike
+from prefect.types import ValidAssetKey
 
 
 class AssetProperties(PrefectBaseModel):
@@ -37,7 +37,7 @@ class Asset(PrefectBaseModel):
 
     model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True)
 
-    key: URILike
+    key: ValidAssetKey
     properties: Optional[AssetProperties] = Field(
         default=None,
         description="Properties of the asset. "

prefect/blocks/core.py

@@ -175,11 +175,29 @@ def _collect_secret_fields(
                 )
         return
 
-    if type_ in (SecretStr, SecretBytes) or (
+    # Check if this is a pydantic Secret type (including generic Secret[T])
+    is_pydantic_secret = False
+
+    # Direct check for SecretStr, SecretBytes
+    if type_ in (SecretStr, SecretBytes):
+        is_pydantic_secret = True
+    # Check for base Secret class
+    elif (
         isinstance(type_, type)  # type: ignore[unnecessaryIsInstance]
         and getattr(type_, "__module__", None) == "pydantic.types"
         and getattr(type_, "__name__", None) == "Secret"
     ):
+        is_pydantic_secret = True
+    # Check for generic Secret[T] (e.g., Secret[str], Secret[int])
+    elif get_origin(type_) is not None:
+        origin = get_origin(type_)
+        if (
+            getattr(origin, "__module__", None) == "pydantic.types"
+            and getattr(origin, "__name__", None) == "Secret"
+        ):
+            is_pydantic_secret = True
+
+    if is_pydantic_secret:
         secrets.append(name)
     elif type_ == SecretDict:
         # Append .* to field name to signify that all values under a given key are secret and should be obfuscated.
@@ -370,16 +388,27 @@ class Block(BaseModel, ABC):
     ) -> Any:
         jsonable_self = handler(self)
         if (ctx := info.context) and ctx.get("include_secrets") is True:
-            jsonable_self.update(
-                {
-                    field_name: visit_collection(
-                        expr=getattr(self, field_name),
-                        visit_fn=partial(handle_secret_render, context=ctx),
-                        return_data=True,
-                    )
-                    for field_name in type(self).model_fields
-                }
-            )
+            # Add serialization mode to context so handle_secret_render knows how to process nested models
+            ctx["serialization_mode"] = info.mode
+
+            for field_name in type(self).model_fields:
+                field_value = getattr(self, field_name)
+
+                # In JSON mode, skip fields that don't contain secrets
+                # as they're already properly serialized by the handler
+                if (
+                    info.mode == "json"
+                    and field_name in jsonable_self
+                    and not self._field_has_secrets(field_name)
+                ):
+                    continue
+
+                # For all other fields, use visit_collection with handle_secret_render
+                jsonable_self[field_name] = visit_collection(
+                    expr=field_value,
+                    visit_fn=partial(handle_secret_render, context=ctx),
+                    return_data=True,
+                )
         extra_fields = {
             "block_type_slug": self.get_block_type_slug(),
             "_block_document_id": self._block_document_id,
@@ -477,6 +506,25 @@ class Block(BaseModel, ABC):
         else:
             return f"sha256:{checksum}"
 
+    def _field_has_secrets(self, field_name: str) -> bool:
+        """Check if a field contains secrets based on the schema's secret_fields."""
+        secret_fields = self.model_json_schema().get("secret_fields", [])
+
+        # Check if field_name matches any secret field pattern
+        for secret_field in secret_fields:
+            if secret_field == field_name:
+                return True
+            elif secret_field.startswith(f"{field_name}."):
+                # This field contains nested secrets
+                return True
+            elif secret_field.endswith(".*"):
+                # Handle wildcard patterns like "field.*"
+                prefix = secret_field[:-2]  # Remove .*
+                if field_name == prefix:
+                    return True
+
+        return False
+
     def _to_block_document(
         self,
         name: Optional[str] = None,
@@ -530,6 +578,29 @@ class Block(BaseModel, ABC):
             context={"include_secrets": include_secrets},
         )
 
+        # Ensure non-secret fields are JSON-serializable to avoid issues with types
+        # like SemanticVersion when the BlockDocument is later serialized
+        try:
+            json_data = self.model_dump(
+                mode="json",
+                by_alias=True,
+                include=data_keys,
+                context={"include_secrets": include_secrets},
+            )
+            # Replace non-secret, non-Block fields with their JSON representation
+            # We need to check the original field to determine if it's a secret or Block
+            for key in data_keys:
+                if key in block_document_data and key in json_data:
+                    field_value = getattr(self, key)
+                    # Only replace if the field doesn't contain secrets and is not a Block
+                    if not self._field_has_secrets(key) and not isinstance(
+                        field_value, Block
+                    ):
+                        block_document_data[key] = json_data[key]
+        except Exception:
+            # If JSON serialization fails, we'll handle it later
+            pass
+
         # Iterate through and find blocks that already have saved block documents to
         # create references to those saved block documents.
         for key in data_keys:

prefect/client/cloud.py

@@ -24,6 +24,16 @@ from prefect.settings import (
 
 PARSE_API_URL_REGEX = re.compile(r"accounts/(.{36})/workspaces/(.{36})")
 
+# Cache for TypeAdapter instances to avoid repeated instantiation
+_TYPE_ADAPTER_CACHE: dict[type, pydantic.TypeAdapter[Any]] = {}
+
+
+def _get_type_adapter(type_: type) -> pydantic.TypeAdapter[Any]:
+    """Get or create a cached TypeAdapter for the given type."""
+    if type_ not in _TYPE_ADAPTER_CACHE:
+        _TYPE_ADAPTER_CACHE[type_] = pydantic.TypeAdapter(type_)
+    return _TYPE_ADAPTER_CACHE[type_]
+
 
 def get_cloud_client(
     host: Optional[str] = None,
@@ -112,7 +122,7 @@ class CloudClient:
             await self.read_workspaces()
 
     async def read_workspaces(self) -> list[Workspace]:
-        workspaces = pydantic.TypeAdapter(list[Workspace]).validate_python(
+        workspaces = _get_type_adapter(list[Workspace]).validate_python(
             await self.get("/me/workspaces")
         )
         return workspaces

prefect/client/orchestration/__init__.py

@@ -101,10 +101,11 @@ from prefect.client.schemas.filters import (
     WorkQueueFilterName,
 )
 from prefect.client.schemas.objects import (
-    Constant,
+    TaskRunResult,
+    FlowRunResult,
     Parameter,
+    Constant,
     TaskRunPolicy,
-    TaskRunResult,
     WorkQueue,
     WorkQueueStatusDetail,
 )
@@ -144,6 +145,16 @@ P = ParamSpec("P")
 R = TypeVar("R", infer_variance=True)
 T = TypeVar("T")
 
+# Cache for TypeAdapter instances to avoid repeated instantiation
+_TYPE_ADAPTER_CACHE: dict[type, pydantic.TypeAdapter[Any]] = {}
+
+
+def _get_type_adapter(type_: type) -> pydantic.TypeAdapter[Any]:
+    """Get or create a cached TypeAdapter for the given type."""
+    if type_ not in _TYPE_ADAPTER_CACHE:
+        _TYPE_ADAPTER_CACHE[type_] = pydantic.TypeAdapter(type_)
+    return _TYPE_ADAPTER_CACHE[type_]
+
 
 @overload
 def get_client(
@@ -635,7 +646,7 @@ class PrefectClient(
                 raise prefect.exceptions.ObjectNotFound(http_exc=e) from e
             else:
                 raise
-        return pydantic.TypeAdapter(list[FlowRun]).validate_python(response.json())
+        return _get_type_adapter(list[FlowRun]).validate_python(response.json())
 
     async def read_work_queue(
         self,
@@ -768,13 +779,7 @@ class PrefectClient(
         task_inputs: Optional[
             dict[
                 str,
-                list[
-                    Union[
-                        TaskRunResult,
-                        Parameter,
-                        Constant,
-                    ]
-                ],
+                list[Union[TaskRunResult, FlowRunResult, Parameter, Constant]],
             ]
         ] = None,
     ) -> TaskRun:
@@ -894,7 +899,7 @@ class PrefectClient(
             "offset": offset,
         }
         response = await self._client.post("/task_runs/filter", json=body)
-        return pydantic.TypeAdapter(list[TaskRun]).validate_python(response.json())
+        return _get_type_adapter(list[TaskRun]).validate_python(response.json())
 
     async def delete_task_run(self, task_run_id: UUID) -> None:
         """
@@ -958,7 +963,7 @@ class PrefectClient(
         response = await self._client.get(
             "/task_run_states/", params=dict(task_run_id=str(task_run_id))
         )
-        return pydantic.TypeAdapter(list[prefect.states.State]).validate_python(
+        return _get_type_adapter(list[prefect.states.State]).validate_python(
             response.json()
         )
 
@@ -1005,7 +1010,7 @@ class PrefectClient(
         else:
             response = await self._client.post("/work_queues/filter", json=json)
 
-        return pydantic.TypeAdapter(list[WorkQueue]).validate_python(response.json())
+        return _get_type_adapter(list[WorkQueue]).validate_python(response.json())
 
     async def read_worker_metadata(self) -> dict[str, Any]:
         """Reads worker metadata stored in Prefect collection registry."""
@@ -1430,6 +1435,7 @@ class SyncPrefectClient(
                 list[
                     Union[
                         TaskRunResult,
+                        FlowRunResult,
                         Parameter,
                         Constant,
                     ]
@@ -1554,7 +1560,7 @@ class SyncPrefectClient(
             "offset": offset,
         }
         response = self._client.post("/task_runs/filter", json=body)
-        return pydantic.TypeAdapter(list[TaskRun]).validate_python(response.json())
+        return _get_type_adapter(list[TaskRun]).validate_python(response.json())
 
     def set_task_run_state(
         self,
@@ -1598,6 +1604,6 @@ class SyncPrefectClient(
         response = self._client.get(
             "/task_run_states/", params=dict(task_run_id=str(task_run_id))
         )
-        return pydantic.TypeAdapter(list[prefect.states.State]).validate_python(
+        return _get_type_adapter(list[prefect.states.State]).validate_python(
             response.json()
         )