prefect-client 3.0.0rc12__tar.gz → 3.0.0rc14__tar.gz

{prefect-client-3.0.0rc12/src/prefect_client.egg-info → prefect-client-3.0.0rc14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: prefect-client
-Version: 3.0.0rc12
+Version: 3.0.0rc14
 Summary: Workflow orchestration and management.
 Home-page: https://www.prefect.io
 Author: Prefect Technologies, Inc.

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/requirements-client.txt

@@ -19,6 +19,7 @@ orjson >= 3.7, < 4.0
 packaging >= 21.3, < 24.3
 pathspec >= 0.8.0
 pendulum >= 3.0.0, <4
+prometheus-client >= 0.20.0
 pydantic >= 2.7, < 3.0.0
 pydantic_core >= 2.12.0, < 3.0.0
 pydantic_extra_types >= 2.8.2, < 3.0.0

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/src/prefect/blocks/core.py

@@ -2,6 +2,7 @@ import hashlib
 import html
 import inspect
 import sys
+import uuid
 import warnings
 from abc import ABC
 from functools import partial
@@ -790,6 +791,33 @@ class Block(BaseModel, ABC):
 
         return block_document, block_document_name
 
+    @classmethod
+    @sync_compatible
+    @inject_client
+    async def _get_block_document_by_id(
+        cls,
+        block_document_id: Union[str, uuid.UUID],
+        client: Optional["PrefectClient"] = None,
+    ):
+        if isinstance(block_document_id, str):
+            try:
+                block_document_id = UUID(block_document_id)
+            except ValueError:
+                raise ValueError(
+                    f"Block document ID {block_document_id!r} is not a valid UUID"
+                )
+
+        try:
+            block_document = await client.read_block_document(
+                block_document_id=block_document_id
+            )
+        except prefect.exceptions.ObjectNotFound:
+            raise ValueError(
+                f"Unable to find block document with ID {block_document_id!r}"
+            )
+
+        return block_document, block_document.name
+
     @classmethod
     @sync_compatible
     @inject_client
@@ -874,8 +902,108 @@ class Block(BaseModel, ABC):
             loaded_block.save("my-custom-message", overwrite=True)
             ```
         """
-        block_document, block_document_name = await cls._get_block_document(name)
+        block_document, block_document_name = await cls._get_block_document(
+            name, client=client
+        )
+
+        return cls._load_from_block_document(block_document, validate=validate)
+
+    @classmethod
+    @sync_compatible
+    @inject_client
+    async def load_from_ref(
+        cls,
+        ref: Union[str, UUID, Dict[str, Any]],
+        validate: bool = True,
+        client: Optional["PrefectClient"] = None,
+    ) -> "Self":
+        """
+        Retrieves data from the block document by given reference for the block type
+        that corresponds with the current class and returns an instantiated version of
+        the current class with the data stored in the block document.
+
+        Provided reference can be a block document ID, or a reference data in dictionary format.
+        Supported dictionary reference formats are:
+        - {"block_document_id": <block_document_id>}
+        - {"block_document_slug": <block_document_slug>}
+
+        If a block document for a given block type is saved with a different schema
+        than the current class calling `load`, a warning will be raised.
 
+        If the current class schema is a subset of the block document schema, the block
+        can be loaded as normal using the default `validate = True`.
+
+        If the current class schema is a superset of the block document schema, `load`
+        must be called with `validate` set to False to prevent a validation error. In
+        this case, the block attributes will default to `None` and must be set manually
+        and saved to a new block document before the block can be used as expected.
+
+        Args:
+            ref: The reference to the block document. This can be a block document ID,
+                or one of supported dictionary reference formats.
+            validate: If False, the block document will be loaded without Pydantic
+                validating the block schema. This is useful if the block schema has
+                changed client-side since the block document referred to by `name` was saved.
+            client: The client to use to load the block document. If not provided, the
+                default client will be injected.
+
+        Raises:
+            ValueError: If invalid reference format is provided.
+            ValueError: If the requested block document is not found.
+
+        Returns:
+            An instance of the current class hydrated with the data stored in the
+            block document with the specified name.
+
+        """
+        block_document = None
+        if isinstance(ref, (str, UUID)):
+            block_document, _ = await cls._get_block_document_by_id(ref)
+        elif isinstance(ref, dict):
+            if block_document_id := ref.get("block_document_id"):
+                block_document, _ = await cls._get_block_document_by_id(
+                    block_document_id
+                )
+            elif block_document_slug := ref.get("block_document_slug"):
+                block_document, _ = await cls._get_block_document(block_document_slug)
+
+        if not block_document:
+            raise ValueError(f"Invalid reference format {ref!r}.")
+
+        return cls._load_from_block_document(block_document, validate=validate)
+
+    @classmethod
+    def _load_from_block_document(
+        cls, block_document: BlockDocument, validate: bool = True
+    ) -> "Self":
+        """
+        Loads a block from a given block document.
+
+        If a block document for a given block type is saved with a different schema
+        than the current class calling `load`, a warning will be raised.
+
+        If the current class schema is a subset of the block document schema, the block
+        can be loaded as normal using the default `validate = True`.
+
+        If the current class schema is a superset of the block document schema, `load`
+        must be called with `validate` set to False to prevent a validation error. In
+        this case, the block attributes will default to `None` and must be set manually
+        and saved to a new block document before the block can be used as expected.
+
+        Args:
+            block_document: The block document used to instantiate a block.
+            validate: If False, the block document will be loaded without Pydantic
+                validating the block schema. This is useful if the block schema has
+                changed client-side since the block document referred to by `name` was saved.
+
+        Raises:
+            ValueError: If the requested block document is not found.
+
+        Returns:
+            An instance of the current class hydrated with the data stored in the
+            block document with the specified name.
+
+        """
         try:
             return cls._from_block_document(block_document)
         except ValidationError as e:
@@ -883,18 +1011,18 @@ class Block(BaseModel, ABC):
                 missing_fields = tuple(err["loc"][0] for err in e.errors())
                 missing_block_data = {field: None for field in missing_fields}
                 warnings.warn(
-                    f"Could not fully load {block_document_name!r} of block type"
+                    f"Could not fully load {block_document.name!r} of block type"
                     f" {cls.get_block_type_slug()!r} - this is likely because one or more"
                     " required fields were added to the schema for"
                     f" {cls.__name__!r} that did not exist on the class when this block"
                     " was last saved. Please specify values for new field(s):"
                     f" {listrepr(missing_fields)}, then run"
-                    f' `{cls.__name__}.save("{block_document_name}", overwrite=True)`,'
+                    f' `{cls.__name__}.save("{block_document.name}", overwrite=True)`,'
                     " and load this block again before attempting to use it."
                 )
                 return cls.model_construct(**block_document.data, **missing_block_data)
             raise RuntimeError(
-                f"Unable to load {block_document_name!r} of block type"
+                f"Unable to load {block_document.name!r} of block type"
                 f" {cls.get_block_type_slug()!r} due to failed validation. To load without"
                 " validation, try loading again with `validate=False`."
             ) from e

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/src/prefect/blocks/notifications.py

@@ -129,14 +129,37 @@ class MicrosoftTeamsWebhook(AppriseNotificationBlock):
     _documentation_url = "https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook"
 
     url: SecretStr = Field(
-        ...,
+        default=...,
         title="Webhook URL",
-        description="The Teams incoming webhook URL used to send notifications.",
+        description="The Microsoft Power Automate (Workflows) URL used to send notifications to Teams.",
         examples=[
-            "https://your-org.webhook.office.com/webhookb2/XXX/IncomingWebhook/YYY/ZZZ"
+            "https://prod-NO.LOCATION.logic.azure.com:443/workflows/WFID/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE"
         ],
     )
 
+    include_image: bool = Field(
+        default=True,
+        description="Include an image with the notification.",
+    )
+
+    wrap: bool = Field(
+        default=True,
+        description="Wrap the notification text.",
+    )
+
+    def block_initialization(self) -> None:
+        """see https://github.com/caronc/apprise/pull/1172"""
+        from apprise.plugins.workflows import NotifyWorkflows
+
+        if not (
+            parsed_url := NotifyWorkflows.parse_native_url(self.url.get_secret_value())
+        ):
+            raise ValueError("Invalid Microsoft Teams Workflow URL provided.")
+
+        parsed_url |= {"include_image": self.include_image, "wrap": self.wrap}
+
+        self._start_apprise_client(SecretStr(NotifyWorkflows(**parsed_url).url()))
+
 
 class PagerDutyWebHook(AbstractAppriseNotificationBlock):
     """

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/src/prefect/client/base.py

@@ -26,7 +26,6 @@ import httpx
 from asgi_lifespan import LifespanManager
 from httpx import HTTPStatusError, Request, Response
 from starlette import status
-from starlette.testclient import TestClient
 from typing_extensions import Self
 
 import prefect
@@ -35,10 +34,14 @@ from prefect.client.schemas.objects import CsrfToken
 from prefect.exceptions import PrefectHTTPStatusError
 from prefect.logging import get_logger
 from prefect.settings import (
+    PREFECT_API_URL,
     PREFECT_CLIENT_MAX_RETRIES,
     PREFECT_CLIENT_RETRY_EXTRA_CODES,
     PREFECT_CLIENT_RETRY_JITTER_FACTOR,
+    PREFECT_CLOUD_API_URL,
+    PREFECT_SERVER_ALLOW_EPHEMERAL_MODE,
 )
+from prefect.utilities.collections import AutoEnum
 from prefect.utilities.math import bounded_poisson_interval, clamped_poisson_interval
 
 # Datastores for lifespan management, keys should be a tuple of thread and app
@@ -612,28 +615,31 @@ class PrefectHttpxSyncClient(httpx.Client):
         request.headers["Prefect-Csrf-Client"] = str(self.csrf_client_id)
 
 
-class PrefectHttpxSyncEphemeralClient(TestClient, PrefectHttpxSyncClient):
-    """
-    This client is a synchronous httpx client that can be used to talk directly
-    to an ASGI app, such as an ephemeral Prefect API.
-
-    It is a subclass of both Starlette's `TestClient` and Prefect's
-    `PrefectHttpxSyncClient`, so it combines the synchronous testing
-    capabilities of `TestClient` with the Prefect-specific behaviors of
-    `PrefectHttpxSyncClient`.
-    """
+class ServerType(AutoEnum):
+    EPHEMERAL = AutoEnum.auto()
+    SERVER = AutoEnum.auto()
+    CLOUD = AutoEnum.auto()
+    UNCONFIGURED = AutoEnum.auto()
 
-    def __init__(
-        self,
-        *args,
-        # override TestClient default
-        raise_server_exceptions=False,
-        **kwargs,
-    ):
-        super().__init__(
-            *args,
-            raise_server_exceptions=raise_server_exceptions,
-            **kwargs,
-        )
 
-    pass
+def determine_server_type() -> ServerType:
+    """
+    Determine the server type based on the current settings.
+
+    Returns:
+        - `ServerType.EPHEMERAL` if the ephemeral server is enabled
+        - `ServerType.SERVER` if a API URL is configured and it is not a cloud URL
+        - `ServerType.CLOUD` if an API URL is configured and it is a cloud URL
+        - `ServerType.UNCONFIGURED` if no API URL is configured and ephemeral mode is
+            not enabled
+    """
+    api_url = PREFECT_API_URL.value()
+    if api_url is None:
+        if PREFECT_SERVER_ALLOW_EPHEMERAL_MODE.value():
+            return ServerType.EPHEMERAL
+        else:
+            return ServerType.UNCONFIGURED
+    if api_url.startswith(PREFECT_CLOUD_API_URL.value()):
+        return ServerType.CLOUD
+    else:
+        return ServerType.SERVER

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/src/prefect/client/orchestration.py

@@ -132,9 +132,9 @@ from prefect.settings import (
     PREFECT_API_URL,
     PREFECT_CLIENT_CSRF_SUPPORT_ENABLED,
     PREFECT_CLOUD_API_URL,
+    PREFECT_SERVER_ALLOW_EPHEMERAL_MODE,
     PREFECT_UNIT_TEST_MODE,
 )
-from prefect.utilities.collections import AutoEnum
 
 if TYPE_CHECKING:
     from prefect.flows import Flow as FlowObject
@@ -144,7 +144,7 @@ from prefect.client.base import (
     ASGIApp,
     PrefectHttpxAsyncClient,
     PrefectHttpxSyncClient,
-    PrefectHttpxSyncEphemeralClient,
+    ServerType,
     app_lifespan_context,
 )
 
@@ -152,12 +152,6 @@ P = ParamSpec("P")
 R = TypeVar("R")
 
 
-class ServerType(AutoEnum):
-    EPHEMERAL = AutoEnum.auto()
-    SERVER = AutoEnum.auto()
-    CLOUD = AutoEnum.auto()
-
-
 @overload
 def get_client(
     httpx_settings: Optional[Dict[str, Any]] = None, sync_client: Literal[False] = False
@@ -194,8 +188,6 @@ def get_client(
     """
     import prefect.context
 
-    settings_ctx = prefect.context.get_settings_context()
-
     # try to load clients from a client context, if possible
     # only load clients that match the provided config / loop
     try:
@@ -203,40 +195,50 @@ def get_client(
     except RuntimeError:
         loop = None
 
-    if client_ctx := prefect.context.ClientContext.get():
-        if (
-            sync_client
-            and client_ctx.sync_client
-            and client_ctx._httpx_settings == httpx_settings
-        ):
-            return client_ctx.sync_client
-        elif (
-            not sync_client
-            and client_ctx.async_client
-            and client_ctx._httpx_settings == httpx_settings
-            and loop in (client_ctx.async_client._loop, None)
-        ):
-            return client_ctx.async_client
+    if sync_client:
+        if client_ctx := prefect.context.SyncClientContext.get():
+            if client_ctx.client and client_ctx._httpx_settings == httpx_settings:
+                return client_ctx.client
+    else:
+        if client_ctx := prefect.context.AsyncClientContext.get():
+            if (
+                client_ctx.client
+                and client_ctx._httpx_settings == httpx_settings
+                and loop in (client_ctx.client._loop, None)
+            ):
+                return client_ctx.client
 
     api = PREFECT_API_URL.value()
+    server_type = None
 
-    if not api:
+    if not api and PREFECT_SERVER_ALLOW_EPHEMERAL_MODE:
         # create an ephemeral API if none was provided
-        from prefect.server.api.server import create_app
+        from prefect.server.api.server import SubprocessASGIServer
+
+        server = SubprocessASGIServer()
+        server.start()
+        assert server.server_process is not None, "Server process did not start"
 
-        api = create_app(settings_ctx.settings, ephemeral=True)
+        api = server.api_url
+        server_type = ServerType.EPHEMERAL
+    elif not api and not PREFECT_SERVER_ALLOW_EPHEMERAL_MODE:
+        raise ValueError(
+            "No Prefect API URL provided. Please set PREFECT_API_URL to the address of a running Prefect server."
+        )
 
     if sync_client:
         return SyncPrefectClient(
             api,
             api_key=PREFECT_API_KEY.value(),
             httpx_settings=httpx_settings,
+            server_type=server_type,
         )
     else:
         return PrefectClient(
             api,
             api_key=PREFECT_API_KEY.value(),
             httpx_settings=httpx_settings,
+            server_type=server_type,
         )
 
 
@@ -273,6 +275,7 @@ class PrefectClient:
         api_key: Optional[str] = None,
         api_version: Optional[str] = None,
         httpx_settings: Optional[Dict[str, Any]] = None,
+        server_type: Optional[ServerType] = None,
     ) -> None:
         httpx_settings = httpx_settings.copy() if httpx_settings else {}
         httpx_settings.setdefault("headers", {})
@@ -335,11 +338,14 @@ class PrefectClient:
             # client will use a standard HTTP/1.1 connection instead.
             httpx_settings.setdefault("http2", PREFECT_API_ENABLE_HTTP2.value())
 
-            self.server_type = (
-                ServerType.CLOUD
-                if api.startswith(PREFECT_CLOUD_API_URL.value())
-                else ServerType.SERVER
-            )
+            if server_type:
+                self.server_type = server_type
+            else:
+                self.server_type = (
+                    ServerType.CLOUD
+                    if api.startswith(PREFECT_CLOUD_API_URL.value())
+                    else ServerType.SERVER
+                )
 
         # Connect to an in-process application
         elif isinstance(api, ASGIApp):
@@ -3012,16 +3018,34 @@ class PrefectClient:
         return response.json()
 
     async def increment_concurrency_slots(
-        self, names: List[str], slots: int, mode: str
+        self, names: List[str], slots: int, mode: str, create_if_missing: Optional[bool]
     ) -> httpx.Response:
         return await self._client.post(
             "/v2/concurrency_limits/increment",
-            json={"names": names, "slots": slots, "mode": mode},
+            json={
+                "names": names,
+                "slots": slots,
+                "mode": mode,
+                "create_if_missing": create_if_missing,
+            },
         )
 
     async def release_concurrency_slots(
         self, names: List[str], slots: int, occupancy_seconds: float
     ) -> httpx.Response:
+        """
+        Release concurrency slots for the specified limits.
+
+        Args:
+            names (List[str]): A list of limit names for which to release slots.
+            slots (int): The number of concurrency slots to release.
+            occupancy_seconds (float): The duration in seconds that the slots
+                were occupied.
+
+        Returns:
+            httpx.Response: The HTTP response from the server.
+        """
+
         return await self._client.post(
             "/v2/concurrency_limits/decrement",
             json={
@@ -3370,6 +3394,7 @@ class SyncPrefectClient:
         api_key: Optional[str] = None,
         api_version: Optional[str] = None,
         httpx_settings: Optional[Dict[str, Any]] = None,
+        server_type: Optional[ServerType] = None,
     ) -> None:
         httpx_settings = httpx_settings.copy() if httpx_settings else {}
         httpx_settings.setdefault("headers", {})
@@ -3428,11 +3453,14 @@ class SyncPrefectClient:
             # client will use a standard HTTP/1.1 connection instead.
             httpx_settings.setdefault("http2", PREFECT_API_ENABLE_HTTP2.value())
 
-            self.server_type = (
-                ServerType.CLOUD
-                if api.startswith(PREFECT_CLOUD_API_URL.value())
-                else ServerType.SERVER
-            )
+            if server_type:
+                self.server_type = server_type
+            else:
+                self.server_type = (
+                    ServerType.CLOUD
+                    if api.startswith(PREFECT_CLOUD_API_URL.value())
+                    else ServerType.SERVER
+                )
 
         # Connect to an in-process application
         elif isinstance(api, ASGIApp):
@@ -3464,14 +3492,9 @@ class SyncPrefectClient:
             and PREFECT_CLIENT_CSRF_SUPPORT_ENABLED.value()
         )
 
-        if self.server_type == ServerType.EPHEMERAL:
-            self._client = PrefectHttpxSyncEphemeralClient(
-                api, base_url="http://ephemeral-prefect/api"
-            )
-        else:
-            self._client = PrefectHttpxSyncClient(
-                **httpx_settings, enable_csrf_support=enable_csrf_support
-            )
+        self._client = PrefectHttpxSyncClient(
+            **httpx_settings, enable_csrf_support=enable_csrf_support
+        )
 
         # See https://www.python-httpx.org/advanced/#custom-transports
         #
@@ -4046,6 +4069,33 @@ class SyncPrefectClient:
                 raise
         return DeploymentResponse.model_validate(response.json())
 
+    def read_deployment_by_name(
+        self,
+        name: str,
+    ) -> DeploymentResponse:
+        """
+        Query the Prefect API for a deployment by name.
+
+        Args:
+            name: A deployed flow's name: <FLOW_NAME>/<DEPLOYMENT_NAME>
+
+        Raises:
+            prefect.exceptions.ObjectNotFound: If request returns 404
+            httpx.RequestError: If request fails
+
+        Returns:
+            a Deployment model representation of the deployment
+        """
+        try:
+            response = self._client.get(f"/deployments/name/{name}")
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == status.HTTP_404_NOT_FOUND:
+                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e
+            else:
+                raise
+
+        return DeploymentResponse.model_validate(response.json())
+
     def create_artifact(
         self,
         artifact: ArtifactCreate,
@@ -4065,3 +4115,27 @@ class SyncPrefectClient:
         )
 
         return Artifact.model_validate(response.json())
+
+    def release_concurrency_slots(
+        self, names: List[str], slots: int, occupancy_seconds: float
+    ) -> httpx.Response:
+        """
+        Release concurrency slots for the specified limits.
+
+        Args:
+            names (List[str]): A list of limit names for which to release slots.
+            slots (int): The number of concurrency slots to release.
+            occupancy_seconds (float): The duration in seconds that the slots
+                were occupied.
+
+        Returns:
+            httpx.Response: The HTTP response from the server.
+        """
+        return self._client.post(
+            "/v2/concurrency_limits/decrement",
+            json={
+                "names": names,
+                "slots": slots,
+                "occupancy_seconds": occupancy_seconds,
+            },
+        )

{prefect-client-3.0.0rc12 → prefect-client-3.0.0rc14}/src/prefect/client/utilities.py

@@ -42,14 +42,14 @@ def get_or_create_client(
     if client is not None:
         return client, True
     from prefect._internal.concurrency.event_loop import get_running_loop
-    from prefect.context import ClientContext, FlowRunContext, TaskRunContext
+    from prefect.context import AsyncClientContext, FlowRunContext, TaskRunContext
 
-    client_context = ClientContext.get()
+    async_client_context = AsyncClientContext.get()
     flow_run_context = FlowRunContext.get()
     task_run_context = TaskRunContext.get()
 
-    if client_context and client_context.async_client._loop == get_running_loop():
-        return client_context.async_client, True
+    if async_client_context and async_client_context.client._loop == get_running_loop():
+        return async_client_context.client, True
     elif (
         flow_run_context
         and getattr(flow_run_context.client, "_loop", None) == get_running_loop()