prefect-client 2.16.9__py3-none-any.whl → 2.17.1__py3-none-any.whl

prefect/events/clients.py

@@ -17,6 +17,7 @@ from uuid import UUID
 import orjson
 import pendulum
 from cachetools import TTLCache
+from typing_extensions import Self
 from websockets.client import WebSocketClientProtocol, connect
 from websockets.exceptions import (
     ConnectionClosed,
@@ -118,8 +119,8 @@ def _get_api_url_and_key(
     return api_url, api_key
 
 
-class PrefectCloudEventsClient(EventsClient):
-    """A Prefect Events client that streams Events to a Prefect Cloud Workspace"""
+class PrefectEventsClient(EventsClient):
+    """A Prefect Events client that streams events to a Prefect server"""
 
     _websocket: Optional[WebSocketClientProtocol]
     _unconfirmed_events: List[Event]
@@ -127,37 +128,36 @@ class PrefectCloudEventsClient(EventsClient):
     def __init__(
         self,
         api_url: str = None,
-        api_key: str = None,
         reconnection_attempts: int = 10,
         checkpoint_every: int = 20,
     ):
         """
         Args:
-            api_url: The base URL for a Prefect Cloud workspace
-            api_key: The API of an actor with the manage_events scope
+            api_url: The base URL for a Prefect server
             reconnection_attempts: When the client is disconnected, how many times
                 the client should attempt to reconnect
             checkpoint_every: How often the client should sync with the server to
                 confirm receipt of all previously sent events
         """
-        api_url, api_key = _get_api_url_and_key(api_url, api_key)
+        api_url = api_url or PREFECT_API_URL.value()
+        if not api_url:
+            raise ValueError(
+                "api_url must be provided or set in the Prefect configuration"
+            )
 
-        socket_url = (
+        self._events_socket_url = (
             api_url.replace("https://", "wss://")
             .replace("http://", "ws://")
             .rstrip("/")
+            + "/events/in"
         )
-
-        self._connect = connect(
-            socket_url + "/events/in",
-            extra_headers={"Authorization": f"bearer {api_key}"},
-        )
+        self._connect = connect(self._events_socket_url)
         self._websocket = None
         self._reconnection_attempts = reconnection_attempts
         self._unconfirmed_events = []
         self._checkpoint_every = checkpoint_every
 
-    async def __aenter__(self) -> "PrefectCloudEventsClient":
+    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
         await super().__aenter__()
@@ -238,6 +238,38 @@ class PrefectCloudEventsClient(EventsClient):
                     await asyncio.sleep(1)
 
 
+class PrefectCloudEventsClient(PrefectEventsClient):
+    """A Prefect Events client that streams events to a Prefect Cloud Workspace"""
+
+    def __init__(
+        self,
+        api_url: str = None,
+        api_key: str = None,
+        reconnection_attempts: int = 10,
+        checkpoint_every: int = 20,
+    ):
+        """
+        Args:
+            api_url: The base URL for a Prefect Cloud workspace
+            api_key: The API of an actor with the manage_events scope
+            reconnection_attempts: When the client is disconnected, how many times
+                the client should attempt to reconnect
+            checkpoint_every: How often the client should sync with the server to
+                confirm receipt of all previously sent events
+        """
+        api_url, api_key = _get_api_url_and_key(api_url, api_key)
+        super().__init__(
+            api_url=api_url,
+            reconnection_attempts=reconnection_attempts,
+            checkpoint_every=checkpoint_every,
+        )
+
+        self._connect = connect(
+            self._events_socket_url,
+            extra_headers={"Authorization": f"bearer {api_key}"},
+        )
+
+
 SEEN_EVENTS_SIZE = 500_000
 SEEN_EVENTS_TTL = 120
 

prefect/events/filters.py

@@ -6,18 +6,21 @@ import pendulum
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect._internal.schemas.bases import PrefectBaseModel
 from prefect._internal.schemas.fields import DateTimeTZ
+from prefect.utilities.collections import AutoEnum
 
 from .schemas.events import Event, Resource, ResourceSpecification
 
 if HAS_PYDANTIC_V2:
-    from pydantic.v1 import Field
+    from pydantic.v1 import Field, PrivateAttr
 else:
-    from pydantic import Field
+    from pydantic import Field, PrivateAttr
 
 
 class EventDataFilter(PrefectBaseModel, extra="forbid"):
     """A base class for filtering event data."""
 
+    _top_level_filter: "EventFilter | None" = PrivateAttr(None)
+
     def get_filters(self) -> List["EventDataFilter"]:
         return [
             filter
@@ -103,6 +106,10 @@ class EventResourceFilter(EventDataFilter):
     labels: Optional[ResourceSpecification] = Field(
         None, description="Only include events for resources with these labels"
     )
+    distinct: bool = Field(
+        False,
+        description="Only include events for distinct resources",
+    )
 
     def includes(self, event: Event) -> bool:
         if self.id:
@@ -189,6 +196,11 @@ class EventIDFilter(EventDataFilter):
         return True
 
 
+class EventOrder(AutoEnum):
+    ASC = "ASC"
+    DESC = "DESC"
+
+
 class EventFilter(EventDataFilter):
     occurred: EventOccurredFilter = Field(
         default_factory=EventOccurredFilter,
@@ -211,3 +223,8 @@ class EventFilter(EventDataFilter):
         default_factory=EventIDFilter,
         description="Filter criteria for the events' ID",
     )
+
+    order: EventOrder = Field(
+        EventOrder.DESC,
+        description="The order to return filtered events",
+    )

prefect/events/utilities.py

@@ -6,9 +6,13 @@ import pendulum
 
 from prefect._internal.schemas.fields import DateTimeTZ
 
-from .clients import AssertingEventsClient, PrefectCloudEventsClient
+from .clients import (
+    AssertingEventsClient,
+    PrefectCloudEventsClient,
+    PrefectEventsClient,
+)
 from .schemas.events import Event, RelatedResource
-from .worker import EventsWorker, emit_events_to_cloud
+from .worker import EventsWorker, should_emit_events
 
 TIGHT_TIMING = timedelta(minutes=5)
 
@@ -42,10 +46,14 @@ def emit_event(
         The event that was emitted if worker is using a client that emit
         events, otherwise None
     """
-    if not emit_events_to_cloud():
+    if not should_emit_events():
         return None
 
-    operational_clients = [AssertingEventsClient, PrefectCloudEventsClient]
+    operational_clients = [
+        AssertingEventsClient,
+        PrefectCloudEventsClient,
+        PrefectEventsClient,
+    ]
     worker_instance = EventsWorker.instance()
 
     if worker_instance.client_type not in operational_clients:

prefect/events/worker.py

@@ -4,25 +4,41 @@ from typing import Any, Optional, Tuple, Type
 
 from typing_extensions import Self
 
-from prefect._internal.compatibility.experimental import experiment_enabled
 from prefect._internal.concurrency.services import QueueService
-from prefect.settings import PREFECT_API_KEY, PREFECT_API_URL, PREFECT_CLOUD_API_URL
+from prefect.settings import (
+    PREFECT_API_KEY,
+    PREFECT_API_URL,
+    PREFECT_CLOUD_API_URL,
+    PREFECT_EXPERIMENTAL_EVENTS,
+)
 from prefect.utilities.context import temporary_context
 
-from .clients import EventsClient, NullEventsClient, PrefectCloudEventsClient
+from .clients import (
+    EventsClient,
+    NullEventsClient,
+    PrefectCloudEventsClient,
+    PrefectEventsClient,
+)
 from .related import related_resources_from_run_context
 from .schemas.events import Event
 
 
+def should_emit_events() -> bool:
+    return emit_events_to_cloud() or should_emit_events_to_running_server()
+
+
 def emit_events_to_cloud() -> bool:
-    api = PREFECT_API_URL.value()
-    return (
-        experiment_enabled("events_client")
-        and api
-        and api.startswith(PREFECT_CLOUD_API_URL.value())
+    api_url = PREFECT_API_URL.value()
+    return isinstance(api_url, str) and api_url.startswith(
+        PREFECT_CLOUD_API_URL.value()
     )
 
 
+def should_emit_events_to_running_server() -> bool:
+    api_url = PREFECT_API_URL.value()
+    return isinstance(api_url, str) and PREFECT_EXPERIMENTAL_EVENTS
+
+
 class EventsWorker(QueueService[Event]):
     def __init__(
         self, client_type: Type[EventsClient], client_options: Tuple[Tuple[str, Any]]
@@ -67,6 +83,8 @@ class EventsWorker(QueueService[Event]):
                     "api_url": PREFECT_API_URL.value(),
                     "api_key": PREFECT_API_KEY.value(),
                 }
+            elif should_emit_events_to_running_server():
+                client_type = PrefectEventsClient
 
             else:
                 client_type = NullEventsClient

prefect/exceptions.py

@@ -1,19 +1,14 @@
 """
 Prefect-specific exceptions.
 """
+
 import inspect
 import traceback
 from types import ModuleType, TracebackType
 from typing import Callable, Dict, Iterable, List, Optional, Type
 
-from prefect._internal.pydantic import HAS_PYDANTIC_V2
-
-if HAS_PYDANTIC_V2:
-    import pydantic.v1 as pydantic
-else:
-    import pydantic
-
 from httpx._exceptions import HTTPStatusError
+from pydantic import ValidationError
 from rich.traceback import Traceback
 from typing_extensions import Self
 
@@ -182,7 +177,7 @@ class ParameterTypeError(PrefectException):
         super().__init__(msg)
 
     @classmethod
-    def from_validation_error(cls, exc: pydantic.ValidationError) -> Self:
+    def from_validation_error(cls, exc: ValidationError) -> Self:
         bad_params = [f'{err["loc"][0]}: {err["msg"]}' for err in exc.errors()]
         msg = "Flow run received invalid parameters:\n - " + "\n - ".join(bad_params)
         return cls(msg)

prefect/filesystems.py

@@ -270,7 +270,7 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
     basepath: str = Field(
         default=...,
         description="Default path for this block to write to.",
-        example="s3://my-bucket/my-folder/",
+        examples=["s3://my-bucket/my-folder/"],
     )
     settings: Dict[str, Any] = Field(
         default_factory=dict,
@@ -451,19 +451,19 @@ class S3(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="An S3 bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     aws_access_key_id: Optional[SecretStr] = Field(
         default=None,
         title="AWS Access Key ID",
         description="Equivalent to the AWS_ACCESS_KEY_ID environment variable.",
-        example="AKIAIOSFODNN7EXAMPLE",
+        examples=["AKIAIOSFODNN7EXAMPLE"],
     )
     aws_secret_access_key: Optional[SecretStr] = Field(
         default=None,
         title="AWS Secret Access Key",
         description="Equivalent to the AWS_SECRET_ACCESS_KEY environment variable.",
-        example="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+        examples=["wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"],
     )
 
     _remote_file_system: RemoteFileSystem = None
@@ -549,7 +549,7 @@ class GCS(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="A GCS bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     service_account_info: Optional[SecretStr] = Field(
         default=None,
@@ -653,7 +653,7 @@ class Azure(WritableFileSystem, WritableDeploymentStorage):
     bucket_path: str = Field(
         default=...,
         description="An Azure storage bucket path.",
-        example="my-bucket/a-directory-within",
+        examples=["my-bucket/a-directory-within"],
     )
     azure_storage_connection_string: Optional[SecretStr] = Field(
         default=None,
@@ -804,7 +804,7 @@ class SMB(WritableFileSystem, WritableDeploymentStorage):
     share_path: str = Field(
         default=...,
         description="SMB target (requires <SHARE>, followed by <PATH>).",
-        example="/SHARE/dir/subdir",
+        examples=["/SHARE/dir/subdir"],
     )
     smb_username: Optional[SecretStr] = Field(
         default=None,

prefect/flows.py

@@ -590,13 +590,13 @@ class Flow(Generic[P, R]):
     @sync_compatible
     @deprecated_parameter(
         "schedule",
-        start_date="Mar 2023",
+        start_date="Mar 2024",
         when=lambda p: p is not None,
         help="Use `schedules` instead.",
     )
     @deprecated_parameter(
         "is_schedule_active",
-        start_date="Mar 2023",
+        start_date="Mar 2024",
         when=lambda p: p is not None,
         help="Use `paused` instead.",
     )
@@ -1125,10 +1125,11 @@ class Flow(Generic[P, R]):
                 style="blue",
             )
             if PREFECT_UI_URL:
-                console.print(
+                message = (
                     "\nYou can also run your flow via the Prefect UI:"
                     f" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\n"
                 )
+                console.print(message, soft_wrap=True)
 
         return deployment_ids[0]
 

prefect/manifests.py

@@ -4,14 +4,7 @@ Manifests are portable descriptions of one or more workflows within a given dire
 They are the foundational building blocks for defining Flow Deployments.
 """
 
-
-from prefect._internal.pydantic import HAS_PYDANTIC_V2
-
-if HAS_PYDANTIC_V2:
-    from pydantic.v1 import BaseModel, Field
-else:
-    from pydantic import BaseModel, Field
-
+from prefect.pydantic import BaseModel, Field
 from prefect.utilities.callables import ParameterSchema
 
 

prefect/profiles.toml

@@ -1,3 +1,3 @@
 active = "default"
 
-[profiles.default]
+[profiles.default]

prefect/pydantic/__init__.py

@@ -1,3 +1,6 @@
+"""
+This initialization file makes the `BaseModel` and `PrefectBaseModel` classes available for import from the pydantic module within Prefect. This setup allows other parts of the Prefect codebase to use these models without needing to understand the underlying compatibility layer.
+"""
 import typing
 from prefect._internal.pydantic._flags import HAS_PYDANTIC_V2, USE_PYDANTIC_V2
 
@@ -5,15 +8,32 @@ if typing.TYPE_CHECKING:
     # import of virtually everything is supported via `__getattr__` below,
     # but we need them here for type checking and IDE support
     from pydantic import validator, root_validator
-    from .main import BaseModel, PrefectBaseModel, FieldInfo, Field
+    from .main import (
+        BaseModel,
+        PrefectBaseModel,
+        FieldInfo,
+        Field,
+        PrivateAttr,
+        SecretStr,
+        field_validator,
+        model_validator,
+        ConfigDict,
+        ValidationError,
+    )
 
 __all__ = [
     "BaseModel",
     "PrefectBaseModel",
     "Field",
     "FieldInfo",
+    "PrivateAttr",
+    "SecretStr",
     "validator",
     "root_validator",
+    "field_validator",
+    "model_validator",
+    "ConfigDict",
+    "ValidationError",
 ]
 
 _dynamic_imports: "typing.Dict[str, typing.Tuple[str, str]]" = {
@@ -21,6 +41,12 @@ _dynamic_imports: "typing.Dict[str, typing.Tuple[str, str]]" = {
     "PrefectBaseModel": ("prefect.pydantic", ".main"),
     "Field": ("prefect.pydantic", ".main"),
     "FieldInfo": ("prefect.pydantic", ".main"),
+    "PrivateAttr": ("prefect.pydantic", ".main"),
+    "SecretStr": ("prefect.pydantic", ".main"),
+    "field_validator": ("prefect.pydantic", ".main"),
+    "model_validator": ("prefect.pydantic", ".main"),
+    "ConfigDict": ("prefect.pydantic", ".main"),
+    "ValidationError": ("prefect.pydantic", ".main"),
 }
 
 

prefect/pydantic/main.py

@@ -1,6 +1,19 @@
+"""
+This file defines a `PrefectBaseModel` class that extends the `BaseModel` (imported from the internal compatibility layer).
+"""
 import typing
 
-from prefect._internal.pydantic._compat import BaseModel, Field, FieldInfo
+from prefect._internal.pydantic._compat import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    FieldInfo,
+    PrivateAttr,
+    SecretStr,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
 
 
 class PrefectBaseModel(BaseModel):
@@ -12,4 +25,15 @@ class PrefectBaseModel(BaseModel):
         return set()
 
 
-__all__ = ["BaseModel", "PrefectBaseModel", "Field", "FieldInfo"]
+__all__ = [
+    "BaseModel",
+    "PrefectBaseModel",
+    "Field",
+    "FieldInfo",
+    "PrivateAttr",
+    "SecretStr",
+    "field_validator",
+    "model_validator",
+    "ConfigDict",
+    "ValidationError",
+]

prefect/settings.py

@@ -107,6 +107,8 @@ DEFAULT_PROFILES_PATH = Path(__file__).parent.joinpath("profiles.toml")
 REMOVED_EXPERIMENTAL_FLAGS = {
     "PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_SCHEDULING_UI",
     "PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_DEPLOYMENT_PARAMETERS",
+    "PREFECT_EXPERIMENTAL_ENABLE_EVENTS_CLIENT",
+    "PREFECT_EXPERIMENTAL_WARN_EVENTS_CLIENT",
 }
 
 
@@ -1367,16 +1369,6 @@ PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH = Setting(bool, default=Tru
 Whether or not to enable flow run states on the flow run graph.
 """
 
-PREFECT_EXPERIMENTAL_ENABLE_EVENTS_CLIENT = Setting(bool, default=True)
-"""
-Whether or not to enable experimental Prefect work pools.
-"""
-
-PREFECT_EXPERIMENTAL_WARN_EVENTS_CLIENT = Setting(bool, default=False)
-"""
-Whether or not to warn when experimental Prefect work pools are used.
-"""
-
 PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS = Setting(bool, default=True)
 """
 Whether or not to enable experimental Prefect work pools.
@@ -1679,6 +1671,37 @@ PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED = Setting(bool, default=True)
 Whether or not to start the event debug logger service in the server application.
 """
 
+PREFECT_API_SERVICES_TRIGGERS_ENABLED = Setting(bool, default=True)
+"""
+Whether or not to start the triggers service in the server application.
+"""
+
+PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER = Setting(timedelta, default=timedelta(seconds=60))
+"""
+The amount of time to retain expired automation buckets
+"""
+
+PREFECT_EVENTS_PROACTIVE_GRANULARITY = Setting(timedelta, default=timedelta(seconds=5))
+"""
+How frequently proactive automations are evaluated
+"""
+
+PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED = Setting(bool, default=True)
+"""
+Whether or not to start the event persister service in the server application.
+"""
+
+PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE = Setting(int, default=20, gt=0)
+"""
+The number of events the event persister will attempt to insert in one batch.
+"""
+
+PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL = Setting(float, default=5, gt=0.0)
+"""
+The maximum number of seconds between flushes of the event persister.
+"""
+
+
 # Deprecated settings ------------------------------------------------------------------
 
 

prefect/task_server.py

@@ -53,8 +53,8 @@ def should_try_to_read_parameters(task: Task, task_run: TaskRun) -> bool:
 
 
 class TaskServer:
-    """This class is responsible for serving tasks that may be executed autonomously by a
-    task runner in the engine.
+    """This class is responsible for serving tasks that may be executed in the background
+    by a task runner via the traditional engine machinery.
 
     When `start()` is called, the task server will open a websocket connection to a
     server-side queue of scheduled task runs. When a scheduled task run is found, the

prefect/utilities/dispatch.py

@@ -19,6 +19,7 @@ key = get_dispatch_key(Foo)  # 'foo'
 lookup_type(Base, key) # Foo
 ```
 """
+
 import abc
 import inspect
 import warnings