prefect-client 3.1.10__py3-none-any.whl → 3.1.12__py3-none-any.whl

prefect/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-12-24T22:58:40-0800",
+ "date": "2025-01-09T10:09:15-0800",
  "dirty": true,
  "error": null,
- "full-revisionid": "b11b56fc6143df2bd4c7018f7a974dc656fe9aa3",
- "version": "3.1.10"
+ "full-revisionid": "e299e5a781867735d62685e7c190b5d100a28b62",
+ "version": "3.1.12"
 }
 '''  # END VERSION_JSON
 

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):
         """
         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"]

prefect/blocks/abstract.py

@@ -1,16 +1,16 @@
+from __future__ import annotations
+
+import logging
+import sys
 from abc import ABC, abstractmethod
 from contextlib import contextmanager
-from logging import Logger, LoggerAdapter
+from logging import Logger
 from pathlib import Path
 from typing import (
     Any,
     BinaryIO,
-    Dict,
     Generator,
     Generic,
-    List,
-    Optional,
-    Tuple,
     TypeVar,
     Union,
 )
@@ -23,7 +23,12 @@ from prefect.logging.loggers import get_logger, get_run_logger
 
 T = TypeVar("T")
 
-LoggerOrAdapter: TypeAlias = Union[Logger, LoggerAdapter]
+if sys.version_info >= (3, 12):
+    LoggingAdapter = logging.LoggerAdapter[logging.Logger]
+else:
+    LoggingAdapter = logging.LoggerAdapter
+
+LoggerOrAdapter: TypeAlias = Union[Logger, LoggingAdapter]
 
 
 class CredentialsBlock(Block, ABC):
@@ -52,7 +57,7 @@ class CredentialsBlock(Block, ABC):
             return get_logger(self.__class__.__name__)
 
     @abstractmethod
-    def get_client(self, *args, **kwargs):
+    def get_client(self, *args: Any, **kwargs: Any) -> Any:
         """
         Returns a client for interacting with the external system.
 
@@ -94,7 +99,7 @@ class NotificationBlock(Block, ABC):
             return get_logger(self.__class__.__name__)
 
     @abstractmethod
-    async def notify(self, body: str, subject: Optional[str] = None) -> None:
+    async def notify(self, body: str, subject: str | None = None) -> None:
         """
         Send a notification.
 
@@ -153,7 +158,7 @@ class JobRun(ABC, Generic[T]):  # not a block
         """
 
 
-class JobBlock(Block, ABC):
+class JobBlock(Block, ABC, Generic[T]):
     """
     Block that represents an entity in an external service
     that can trigger a long running execution.
@@ -176,7 +181,7 @@ class JobBlock(Block, ABC):
             return get_logger(self.__class__.__name__)
 
     @abstractmethod
-    async def trigger(self) -> JobRun:
+    async def trigger(self) -> JobRun[T]:
         """
         Triggers a job run in an external service and returns a JobRun object
         to track the execution of the run.
@@ -221,8 +226,11 @@ class DatabaseBlock(Block, ABC):
 
     @abstractmethod
     async def fetch_one(
-        self, operation, parameters=None, **execution_kwargs
-    ) -> Tuple[Any]:
+        self,
+        operation: str,
+        parameters: dict[str, Any] | None = None,
+        **execution_kwargs: Any,
+    ) -> tuple[Any, ...]:
         """
         Fetch a single result from the database.
 
@@ -238,8 +246,12 @@ class DatabaseBlock(Block, ABC):
 
     @abstractmethod
     async def fetch_many(
-        self, operation, parameters=None, size=None, **execution_kwargs
-    ) -> List[Tuple[Any]]:
+        self,
+        operation: str,
+        parameters: dict[str, Any] | None = None,
+        size: int | None = None,
+        **execution_kwargs: Any,
+    ) -> list[tuple[Any, ...]]:
         """
         Fetch a limited number of results from the database.
 
@@ -256,8 +268,11 @@ class DatabaseBlock(Block, ABC):
 
     @abstractmethod
     async def fetch_all(
-        self, operation, parameters=None, **execution_kwargs
-    ) -> List[Tuple[Any]]:
+        self,
+        operation: str,
+        parameters: dict[str, Any] | None = None,
+        **execution_kwargs: Any,
+    ) -> list[tuple[Any, ...]]:
         """
         Fetch all results from the database.
 
@@ -272,7 +287,12 @@ class DatabaseBlock(Block, ABC):
         """
 
     @abstractmethod
-    async def execute(self, operation, parameters=None, **execution_kwargs) -> None:
+    async def execute(
+        self,
+        operation: str,
+        parameters: dict[str, Any] | None = None,
+        **execution_kwargs: Any,
+    ) -> None:
         """
         Executes an operation on the database. This method is intended to be used
         for operations that do not return data, such as INSERT, UPDATE, or DELETE.
@@ -285,7 +305,10 @@ class DatabaseBlock(Block, ABC):
 
     @abstractmethod
     async def execute_many(
-        self, operation, seq_of_parameters, **execution_kwargs
+        self,
+        operation: str,
+        seq_of_parameters: list[dict[str, Any]],
+        **execution_kwargs: Any,
     ) -> None:
         """
         Executes multiple operations on the database. This method is intended to be used
@@ -307,7 +330,7 @@ class DatabaseBlock(Block, ABC):
             f"{self.__class__.__name__} does not support async context management."
         )
 
-    async def __aexit__(self, *args) -> None:
+    async def __aexit__(self, *args: Any) -> None:
         """
         Context management method for async databases.
         """
@@ -323,7 +346,7 @@ class DatabaseBlock(Block, ABC):
             f"{self.__class__.__name__} does not support context management."
         )
 
-    def __exit__(self, *args) -> None:
+    def __exit__(self, *args: Any) -> None:
         """
         Context management method for databases.
         """
@@ -358,8 +381,8 @@ class ObjectStorageBlock(Block, ABC):
     async def download_object_to_path(
         self,
         from_path: str,
-        to_path: Union[str, Path],
-        **download_kwargs: Dict[str, Any],
+        to_path: str | Path,
+        **download_kwargs: Any,
     ) -> Path:
         """
         Downloads an object from the object storage service to a path.
@@ -378,7 +401,7 @@ class ObjectStorageBlock(Block, ABC):
         self,
         from_path: str,
         to_file_object: BinaryIO,
-        **download_kwargs: Dict[str, Any],
+        **download_kwargs: Any,
     ) -> BinaryIO:
         """
         Downloads an object from the object storage service to a file-like object,
@@ -397,8 +420,8 @@ class ObjectStorageBlock(Block, ABC):
     async def download_folder_to_path(
         self,
         from_folder: str,
-        to_folder: Union[str, Path],
-        **download_kwargs: Dict[str, Any],
+        to_folder: str | Path,
+        **download_kwargs: Any,
     ) -> Path:
         """
         Downloads a folder from the object storage service to a path.
@@ -414,7 +437,7 @@ class ObjectStorageBlock(Block, ABC):
 
     @abstractmethod
     async def upload_from_path(
-        self, from_path: Union[str, Path], to_path: str, **upload_kwargs: Dict[str, Any]
+        self, from_path: str | Path, to_path: str, **upload_kwargs: Any
     ) -> str:
         """
         Uploads an object from a path to the object storage service.
@@ -430,7 +453,7 @@ class ObjectStorageBlock(Block, ABC):
 
     @abstractmethod
     async def upload_from_file_object(
-        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]
+        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Any
     ) -> str:
         """
         Uploads an object to the object storage service from a file-like object,
@@ -448,9 +471,9 @@ class ObjectStorageBlock(Block, ABC):
     @abstractmethod
     async def upload_from_folder(
         self,
-        from_folder: Union[str, Path],
+        from_folder: str | Path,
         to_folder: str,
-        **upload_kwargs: Dict[str, Any],
+        **upload_kwargs: Any,
     ) -> str:
         """
         Uploads a folder to the object storage service from a path.
@@ -496,7 +519,7 @@ class SecretBlock(Block, ABC):
         """
 
     @abstractmethod
-    async def write_secret(self, secret_data) -> str:
+    async def write_secret(self, secret_data: bytes) -> str:
         """
         Writes secret data to the configured secret in the secret storage service.