prefect-client 3.1.11__py3-none-any.whl → 3.1.13__py3-none-any.whl

prefect/_experimental/sla/client.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from prefect.client.orchestration.base import BaseAsyncClient, BaseClient
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from prefect._experimental.sla.objects import SlaMergeResponse, SlaTypes
+
+
+class SlaClient(BaseClient):
+    def apply_slas_for_deployment(
+        self, deployment_id: "UUID", slas: "list[SlaTypes]"
+    ) -> "SlaMergeResponse":
+        """
+        Applies service level agreements for a deployment. Performs matching by SLA name. If a SLA with the same name already exists, it will be updated. If a SLA with the same name does not exist, it will be created. Existing SLAs that are not in the list will be deleted.
+        Args:
+            deployment_id: The ID of the deployment to update SLAs for
+            slas: List of SLAs to associate with the deployment
+        Raises:
+            httpx.RequestError: if the SLAs were not updated for any reason
+        Returns:
+            SlaMergeResponse: The response from the backend, containing the names of the created, updated, and deleted SLAs
+        """
+        resource_id = f"prefect.deployment.{deployment_id}"
+
+        for sla in slas:
+            sla.set_deployment_id(deployment_id)
+
+        slas_spec_list = [
+            sla.model_dump(mode="json", exclude_unset=True) for sla in slas
+        ]
+
+        response = self.request(
+            "POST",
+            f"/slas/apply-resource-slas/{resource_id}",
+            json=slas_spec_list,
+        )
+        response.raise_for_status()
+
+        response_json = response.json()
+
+        from prefect._experimental.sla.objects import SlaMergeResponse
+
+        return SlaMergeResponse(
+            created=[sla.get("name") for sla in response_json.get("created")],
+            updated=[sla.get("name") for sla in response_json.get("updated")],
+            deleted=[sla.get("name") for sla in response_json.get("deleted")],
+        )
+
+
+class SlaAsyncClient(BaseAsyncClient):
+    async def apply_slas_for_deployment(
+        self, deployment_id: "UUID", slas: "list[SlaTypes]"
+    ) -> "UUID":
+        """
+        Applies service level agreements for a deployment. Performs matching by SLA name. If a SLA with the same name already exists, it will be updated. If a SLA with the same name does not exist, it will be created. Existing SLAs that are not in the list will be deleted.
+        Args:
+            deployment_id: The ID of the deployment to update SLAs for
+            slas: List of SLAs to associate with the deployment
+        Raises:
+            httpx.RequestError: if the SLAs were not updated for any reason
+        Returns:
+            SlaMergeResponse: The response from the backend, containing the names of the created, updated, and deleted SLAs
+        """
+        resource_id = f"prefect.deployment.{deployment_id}"
+
+        for sla in slas:
+            sla.set_deployment_id(deployment_id)
+
+        slas_spec_list = [
+            sla.model_dump(mode="json", exclude_unset=True) for sla in slas
+        ]
+
+        response = await self.request(
+            "POST",
+            f"/slas/apply-resource-slas/{resource_id}",
+            json=slas_spec_list,
+        )
+        response.raise_for_status()
+
+        response_json = response.json()
+
+        from prefect._experimental.sla.objects import SlaMergeResponse
+
+        return SlaMergeResponse(
+            created=[sla.get("name") for sla in response_json.get("created")],
+            updated=[sla.get("name") for sla in response_json.get("updated")],
+            deleted=[sla.get("name") for sla in response_json.get("deleted")],
+        )

prefect/_experimental/sla/objects.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import abc
+from typing import Literal, Optional, Union
+from uuid import UUID
+
+from pydantic import Field, PrivateAttr, computed_field
+from typing_extensions import Self, TypeAlias
+
+from prefect._internal.schemas.bases import PrefectBaseModel
+
+
+class ServiceLevelAgreement(PrefectBaseModel, abc.ABC):
+    """An ORM representation of a Service Level Agreement."""
+
+    _deployment_id: Optional[UUID] = PrivateAttr(default=None)
+
+    name: str = Field(
+        default=...,
+        description="The name of the SLA. Names must be unique on a per-deployment basis.",
+    )
+    severity: Literal["minor", "low", "moderate", "high", "critical"] = Field(
+        default="moderate",
+        description="The severity of the SLA.",
+    )
+    enabled: Optional[bool] = Field(
+        default=True,
+        description="Whether the SLA is enabled.",
+    )
+
+    def set_deployment_id(self, deployment_id: UUID) -> Self:
+        self._deployment_id = deployment_id
+        return self
+
+    @computed_field
+    @property
+    def owner_resource(self) -> Union[str, None]:
+        if self._deployment_id:
+            return f"prefect.deployment.{self._deployment_id}"
+        return None
+
+
+class TimeToCompletionSla(ServiceLevelAgreement):
+    """An SLA that triggers when a flow run takes longer than the specified duration."""
+
+    duration: int = Field(
+        default=...,
+        description="The maximum flow run duration allowed before the SLA is violated, expressed in seconds.",
+    )
+
+
+class SlaMergeResponse(PrefectBaseModel):
+    """A response object for the apply_slas_for_deployment method. Contains the names of the created, updated, and deleted SLAs."""
+
+    created: list[str]
+    updated: list[str]
+    deleted: list[str]
+
+
+# Concrete SLA types
+SlaTypes: TypeAlias = Union[TimeToCompletionSla]

prefect/_internal/concurrency/services.py

@@ -32,7 +32,7 @@ class _QueueServiceBase(abc.ABC, Generic[T]):
         self._task: Optional[asyncio.Task[None]] = None
         self._stopped: bool = False
         self._started: bool = False
-        self._key = hash(args)
+        self._key = hash((self.__class__, *args))
         self._lock = threading.Lock()
         self._queue_get_thread = WorkerThread(
             # TODO: This thread should not need to be a daemon but when it is not, it
@@ -256,7 +256,7 @@ class _QueueServiceBase(abc.ABC, Generic[T]):
         If an instance already exists with the given arguments, it will be returned.
         """
         with cls._instance_lock:
-            key = hash(args)
+            key = hash((cls, *args))
             if key not in cls._instances:
                 cls._instances[key] = cls._new_instance(*args)
 

prefect/_internal/concurrency/threads.py

@@ -2,6 +2,8 @@
 Utilities for managing worker threads.
 """
 
+from __future__ import annotations
+
 import asyncio
 import atexit
 import concurrent.futures
@@ -197,6 +199,10 @@ class EventLoopThread(Portal):
     def running(self) -> bool:
         return not self._shutdown_event.is_set()
 
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop | None:
+        return self._loop
+
     def _entrypoint(self):
         """
         Entrypoint for the thread.

prefect/_internal/retries.py

@@ -29,7 +29,7 @@ def retry_async_fn(
     retry_on_exceptions: tuple[type[Exception], ...] = (Exception,),
     operation_name: Optional[str] = None,
 ) -> Callable[
-    [Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, Optional[R]]]
+    [Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]
 ]:
     """A decorator for retrying an async function.
 
@@ -48,9 +48,9 @@ def retry_async_fn(
 
     def decorator(
         func: Callable[P, Coroutine[Any, Any, R]],
-    ) -> Callable[P, Coroutine[Any, Any, Optional[R]]]:
+    ) -> Callable[P, Coroutine[Any, Any, R]]:
         @wraps(func)
-        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> Optional[R]:
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             name = operation_name or func.__name__
             for attempt in range(max_attempts):
                 try:
@@ -67,6 +67,9 @@ def retry_async_fn(
                         f"Retrying in {delay:.2f} seconds..."
                     )
                     await asyncio.sleep(delay)
+            # Technically unreachable, but this raise helps pyright know that this function
+            # won't return None.
+            raise Exception(f"Function {name!r} failed after {max_attempts} attempts")
 
         return wrapper
 

prefect/_internal/schemas/validators.py

@@ -6,6 +6,8 @@ format.
 This will be subject to consolidation and refactoring over the next few months.
 """
 
+from __future__ import annotations
+
 import os
 import re
 import urllib.parse
@@ -627,18 +629,18 @@ def validate_name_present_on_nonanonymous_blocks(values: M) -> M:
 
 
 @overload
-def validate_command(v: str) -> Path:
+def validate_working_dir(v: str) -> Path:
     ...
 
 
 @overload
-def validate_command(v: None) -> None:
+def validate_working_dir(v: None) -> None:
     ...
 
 
-def validate_command(v: Optional[str]) -> Optional[Path]:
+def validate_working_dir(v: Optional[Path | str]) -> Optional[Path]:
     """Make sure that the working directory is formatted for the current platform."""
-    if v is not None:
+    if isinstance(v, str):
         return relative_path_to_current_platform(v)
     return v
 

prefect/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-01-02T13:11:17-0600",
+ "date": "2025-01-17T08:46:53-0800",
  "dirty": true,
  "error": null,
- "full-revisionid": "e448bd3462d7c2580427624f426d81cf6e9a7ff1",
- "version": "3.1.11"
+ "full-revisionid": "16e85ce3c281778f5ab6487a73377eed63bcac8b",
+ "version": "3.1.13"
 }
 '''  # END VERSION_JSON
 

prefect/artifacts.py

@@ -20,7 +20,10 @@ from prefect.logging.loggers import get_logger
 from prefect.utilities.asyncutils import sync_compatible
 from prefect.utilities.context import get_task_and_flow_run_ids
 
-logger = get_logger("artifacts")
+if TYPE_CHECKING:
+    import logging
+
+logger: "logging.Logger" = get_logger("artifacts")
 
 if TYPE_CHECKING:
     from prefect.client.orchestration import PrefectClient

prefect/automations.py

@@ -4,6 +4,7 @@ from uuid import UUID
 from pydantic import Field
 from typing_extensions import Self
 
+from prefect._internal.compatibility.async_dispatch import async_dispatch
 from prefect.client.orchestration import get_client
 from prefect.events.actions import (
     CallWebhook,
@@ -39,7 +40,6 @@ from prefect.events.schemas.automations import (
     Trigger,
 )
 from prefect.exceptions import PrefectHTTPStatusError
-from prefect.utilities.asyncutils import sync_compatible
 
 __all__ = [
     "AutomationCore",
@@ -78,11 +78,13 @@ __all__ = [
 class Automation(AutomationCore):
     id: Optional[UUID] = Field(default=None, description="The ID of this automation")
 
-    @sync_compatible
-    async def create(self: Self) -> Self:
+    async def acreate(self: Self) -> Self:
         """
-        Create a new automation.
+        Asynchronously create a new automation.
+
+        Examples:
 
+        ```python
         auto_to_create = Automation(
             name="woodchonk",
             trigger=EventTrigger(
@@ -97,20 +99,55 @@ class Automation(AutomationCore):
             ),
             actions=[CancelFlowRun()]
         )
-        created_automation = auto_to_create.create()
+        created_automation = await auto_to_create.acreate()
+        ```
         """
         async with get_client() as client:
             automation = AutomationCore(**self.model_dump(exclude={"id"}))
             self.id = await client.create_automation(automation=automation)
             return self
 
-    @sync_compatible
-    async def update(self: Self):
+    @async_dispatch(acreate)
+    def create(self: Self) -> Self:
+        """
+        Create a new automation.
+
+        Examples:
+
+        ```python
+        auto_to_create = Automation(
+            name="woodchonk",
+            trigger=EventTrigger(
+                expect={"animal.walked"},
+                match={
+                    "genus": "Marmota",
+                    "species": "monax",
+                },
+                posture="Reactive",
+                threshold=3,
+                within=timedelta(seconds=10),
+            ),
+            actions=[CancelFlowRun()]
+        )
+        created_automation = auto_to_create.create()
+        ```
+        """
+        with get_client(sync_client=True) as client:
+            automation = AutomationCore(**self.model_dump(exclude={"id"}))
+            self.id = client.create_automation(automation=automation)
+            return self
+
+    async def aupdate(self: Self) -> None:
         """
         Updates an existing automation.
+
+        Examples:
+
+        ```python
         auto = Automation.read(id=123)
         auto.name = "new name"
         auto.update()
+        ```
         """
         assert self.id is not None
         async with get_client() as client:
@@ -119,28 +156,51 @@ class Automation(AutomationCore):
             )
             await client.update_automation(automation_id=self.id, automation=automation)
 
+    @async_dispatch(aupdate)
+    def update(self: Self):
+        """
+        Updates an existing automation.
+
+        Examples:
+
+
+        ```python
+        auto = Automation.read(id=123)
+        auto.name = "new name"
+        auto.update()
+        ```
+        """
+        assert self.id is not None
+        with get_client(sync_client=True) as client:
+            automation = AutomationCore(
+                **self.model_dump(exclude={"id", "owner_resource"})
+            )
+            client.update_automation(automation_id=self.id, automation=automation)
+
     @overload
     @classmethod
-    async def read(cls, id: UUID, name: Optional[str] = ...) -> Self:
+    async def aread(cls, id: UUID, name: Optional[str] = ...) -> Self:
         ...
 
     @overload
     @classmethod
-    async def read(cls, id: None = None, name: str = ...) -> Optional[Self]:
+    async def aread(cls, id: None = None, name: str = ...) -> Self:
         ...
 
     @classmethod
-    @sync_compatible
-    async def read(
-        cls, id: Optional[UUID] = None, name: Optional[str] = None
-    ) -> Optional[Self]:
+    async def aread(cls, id: Optional[UUID] = None, name: Optional[str] = None) -> Self:
         """
-        Read an automation by ID or name.
-        automation = Automation.read(name="woodchonk")
+        Asynchronously read an automation by ID or name.
 
-        or
+        Examples:
 
-        automation = Automation.read(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))
+        ```python
+        automation = await Automation.aread(name="woodchonk")
+        ```
+
+        ```python
+        automation = await Automation.aread(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))
+        ```
         """
         if id and name:
             raise ValueError("Only one of id or name can be provided")
@@ -162,15 +222,68 @@ class Automation(AutomationCore):
                     assert name is not None
                 automation = await client.read_automations_by_name(name=name)
                 if len(automation) > 0:
-                    return cls(**automation[0].model_dump()) if automation else None
-                else:
-                    raise ValueError(f"Automation with name {name!r} not found")
+                    return cls(**automation[0].model_dump())
+                raise ValueError(f"Automation with name {name!r} not found")
 
-    @sync_compatible
-    async def delete(self: Self) -> bool:
+    @overload
+    @classmethod
+    async def read(cls, id: UUID, name: Optional[str] = ...) -> Self:
+        ...
+
+    @overload
+    @classmethod
+    async def read(cls, id: None = None, name: str = ...) -> Self:
+        ...
+
+    @classmethod
+    @async_dispatch(aread)
+    def read(cls, id: Optional[UUID] = None, name: Optional[str] = None) -> Self:
         """
+        Read an automation by ID or name.
+
+        Examples:
+
+        ```python
+        automation = Automation.read(name="woodchonk")
+        ```
+
+        ```python
+        automation = Automation.read(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))
+        ```
+        """
+        if id and name:
+            raise ValueError("Only one of id or name can be provided")
+        if not id and not name:
+            raise ValueError("One of id or name must be provided")
+        with get_client(sync_client=True) as client:
+            if id:
+                try:
+                    automation = client.read_automation(automation_id=id)
+                except PrefectHTTPStatusError as exc:
+                    if exc.response.status_code == 404:
+                        raise ValueError(f"Automation with ID {id!r} not found")
+                    raise
+                if automation is None:
+                    raise ValueError(f"Automation with ID {id!r} not found")
+                return cls(**automation.model_dump())
+            else:
+                if TYPE_CHECKING:
+                    assert name is not None
+                automation = client.read_automations_by_name(name=name)
+                if len(automation) > 0:
+                    return cls(**automation[0].model_dump())
+                raise ValueError(f"Automation with name {name!r} not found")
+
+    async def adelete(self: Self) -> bool:
+        """
+        Asynchronously delete an automation.
+
+        Examples:
+
+        ```python
         auto = Automation.read(id = 123)
-        auto.delete()
+        await auto.adelete()
+        ```
         """
         if self.id is None:
             raise ValueError("Can't delete an automation without an id")
@@ -184,38 +297,131 @@ class Automation(AutomationCore):
                     return False
                 raise
 
-    @sync_compatible
-    async def disable(self: Self) -> bool:
+    @async_dispatch(adelete)
+    def delete(self: Self) -> bool:
+        """
+        Delete an automation.
+
+        Examples:
+
+        ```python
+        auto = Automation.read(id = 123)
+        auto.delete()
+        ```
+        """
+        if self.id is None:
+            raise ValueError("Can't delete an automation without an id")
+
+        with get_client(sync_client=True) as client:
+            try:
+                client.delete_automation(self.id)
+                return True
+            except PrefectHTTPStatusError as exc:
+                if exc.response.status_code == 404:
+                    return False
+                raise
+
+    async def adisable(self: Self) -> bool:
+        """
+        Asynchronously disable an automation.
+
+        Raises:
+            ValueError: If the automation does not have an id
+            PrefectHTTPStatusError: If the automation cannot be disabled
+
+        Example:
+        ```python
+        auto = await Automation.aread(id = 123)
+        await auto.adisable()
+        ```
+        """
+        if self.id is None:
+            raise ValueError("Can't disable an automation without an id")
+
+        async with get_client() as client:
+            try:
+                await client.pause_automation(self.id)
+                return True
+            except PrefectHTTPStatusError as exc:
+                if exc.response.status_code == 404:
+                    return False
+                raise
+
+    @async_dispatch(adisable)
+    def disable(self: Self) -> bool:
         """
         Disable an automation.
+
+
+        Raises:
+            ValueError: If the automation does not have an id
+            PrefectHTTPStatusError: If the automation cannot be disabled
+
+        Example:
+        ```python
         auto = Automation.read(id = 123)
         auto.disable()
+        ```
         """
         if self.id is None:
             raise ValueError("Can't disable an automation without an id")
 
+        with get_client(sync_client=True) as client:
+            try:
+                client.pause_automation(self.id)
+                return True
+            except PrefectHTTPStatusError as exc:
+                if exc.response.status_code == 404:
+                    return False
+                raise
+
+    async def aenable(self: Self) -> bool:
+        """
+        Asynchronously enable an automation.
+
+        Raises:
+            ValueError: If the automation does not have an id
+            PrefectHTTPStatusError: If the automation cannot be enabled
+
+        Example:
+        ```python
+        auto = await Automation.aread(id = 123)
+        await auto.aenable()
+        ```
+        """
+        if self.id is None:
+            raise ValueError("Can't enable an automation without an id")
+
         async with get_client() as client:
             try:
-                await client.pause_automation(self.id)
+                await client.resume_automation(self.id)
                 return True
             except PrefectHTTPStatusError as exc:
                 if exc.response.status_code == 404:
                     return False
                 raise
 
-    @sync_compatible
-    async def enable(self: Self) -> bool:
+    @async_dispatch(aenable)
+    def enable(self: Self) -> bool:
         """
         Enable an automation.
+
+        Raises:
+            ValueError: If the automation does not have an id
+            PrefectHTTPStatusError: If the automation cannot be enabled
+
+        Example:
+        ```python
         auto = Automation.read(id = 123)
         auto.enable()
+        ```
         """
         if self.id is None:
             raise ValueError("Can't enable an automation without an id")
 
-        async with get_client() as client:
+        with get_client(sync_client=True) as client:
             try:
-                await client.resume_automation(self.id)
+                client.resume_automation(self.id)
                 return True
             except PrefectHTTPStatusError as exc:
                 if exc.response.status_code == 404:

prefect/blocks/__init__.py

@@ -1,7 +1,7 @@
 # ensure core blocks are registered
 
-import prefect.blocks.notifications
-import prefect.blocks.system
-import prefect.blocks.webhook
+import prefect.blocks.notifications as notifications
+import prefect.blocks.system as system
+import prefect.blocks.webhook as webhook
 
 __all__ = ["notifications", "system", "webhook"]