prefect-client 3.1.14__py3-none-any.whl → 3.2.0__py3-none-any.whl

prefect/runtime/task_run.py

@@ -18,11 +18,21 @@ Available attributes:
 from __future__ import annotations
 
 import os
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable
 
 from prefect.context import TaskRunContext
+from prefect.settings import get_current_settings
 
-__all__ = ["id", "tags", "name", "parameters", "run_count", "task_name"]
+__all__ = [
+    "id",
+    "tags",
+    "name",
+    "parameters",
+    "run_count",
+    "task_name",
+    "api_url",
+    "ui_url",
+]
 
 
 type_cast: dict[
@@ -72,17 +82,17 @@ def __getattr__(name: str) -> Any:
         return real_value
 
 
-def __dir__() -> List[str]:
+def __dir__() -> list[str]:
     return sorted(__all__)
 
 
-def get_id() -> str:
+def get_id() -> str | None:
     task_run_ctx = TaskRunContext.get()
     if task_run_ctx is not None:
         return str(task_run_ctx.task_run.id)
 
 
-def get_tags() -> List[str]:
+def get_tags() -> list[str]:
     task_run_ctx = TaskRunContext.get()
     if task_run_ctx is None:
         return []
@@ -98,7 +108,7 @@ def get_run_count() -> int:
         return task_run_ctx.task_run.run_count
 
 
-def get_name() -> Optional[str]:
+def get_name() -> str | None:
     task_run_ctx = TaskRunContext.get()
     if task_run_ctx is None:
         return None
@@ -106,7 +116,7 @@ def get_name() -> Optional[str]:
         return task_run_ctx.task_run.name
 
 
-def get_task_name() -> Optional[str]:
+def get_task_name() -> str | None:
     task_run_ctx = TaskRunContext.get()
     if task_run_ctx is None:
         return None
@@ -114,7 +124,7 @@ def get_task_name() -> Optional[str]:
         return task_run_ctx.task.name
 
 
-def get_parameters() -> Dict[str, Any]:
+def get_parameters() -> dict[str, Any]:
     task_run_ctx = TaskRunContext.get()
     if task_run_ctx is not None:
         return task_run_ctx.parameters
@@ -122,11 +132,29 @@ def get_parameters() -> Dict[str, Any]:
         return {}
 
 
-FIELDS: dict[str, Callable[[], Any]] = {
+def get_task_run_api_url() -> str | None:
+    if (api_url := get_current_settings().api.url) is None:
+        return None
+    if (task_run_id := get_id()) is None:
+        return None
+    return f"{api_url}/runs/task-run/{task_run_id}"
+
+
+def get_task_run_ui_url() -> str | None:
+    if (ui_url := get_current_settings().ui_url) is None:
+        return None
+    if (task_run_id := get_id()) is None:
+        return None
+    return f"{ui_url}/runs/task-run/{task_run_id}"
+
+
+FIELDS: dict[str, Callable[[], Any | None]] = {
     "id": get_id,
     "tags": get_tags,
     "name": get_name,
     "parameters": get_parameters,
     "run_count": get_run_count,
     "task_name": get_task_name,
+    "api_url": get_task_run_api_url,
+    "ui_url": get_task_run_ui_url,
 }

prefect/schedules.py

@@ -0,0 +1,231 @@
+"""
+This module contains functionality for creating schedules for deployments.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+from functools import partial
+from typing import Any
+
+from prefect._internal.schemas.validators import (
+    validate_cron_string,
+    validate_rrule_string,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class Schedule:
+    """
+    A dataclass representing a schedule.
+
+    Note that only one of `interval`, `cron`, or `rrule` can be defined at a time.
+
+    Attributes:
+        interval: A timedelta representing the frequency of the schedule.
+        cron: A valid cron string (e.g. "0 0 * * *").
+        rrule: A valid RRule string (e.g. "RRULE:FREQ=DAILY;INTERVAL=1").
+        timezone: A valid timezone string in IANA tzdata format (e.g. America/New_York).
+        anchor_date: An anchor date to schedule increments against; if not provided,
+            the current timestamp will be used.
+        day_or: Control how `day` and `day_of_week` entries are handled.
+            Defaults to True, matching cron which connects those values using
+            OR. If the switch is set to False, the values are connected using AND.
+            This behaves like fcron and enables you to e.g. define a job that
+            executes each 2nd friday of a month by setting the days of month and
+            the weekday.
+        active: Whether or not the schedule is active.
+        parameters: A dictionary containing parameter overrides for the schedule.
+        slug: A unique identifier for the schedule.
+    """
+
+    interval: datetime.timedelta | None = None
+    cron: str | None = None
+    rrule: str | None = None
+    timezone: str | None = None
+    anchor_date: datetime.datetime = dataclasses.field(
+        default_factory=partial(datetime.datetime.now, tz=datetime.timezone.utc)
+    )
+    day_or: bool = False
+    active: bool = True
+    parameters: dict[str, Any] = dataclasses.field(default_factory=dict)
+    slug: str | None = None
+
+    def __post_init__(self) -> None:
+        defined_fields = [
+            field
+            for field in ["interval", "cron", "rrule"]
+            if getattr(self, field) is not None
+        ]
+        if len(defined_fields) > 1:
+            raise ValueError(
+                f"Only one schedule type can be defined at a time. Found: {', '.join(defined_fields)}"
+            )
+
+        if self.cron is not None:
+            validate_cron_string(self.cron)
+        if self.rrule is not None:
+            validate_rrule_string(self.rrule)
+
+
+def Cron(
+    cron: str,
+    /,
+    timezone: str | None = None,
+    day_or: bool = False,
+    active: bool = True,
+    parameters: dict[str, Any] | None = None,
+    slug: str | None = None,
+) -> Schedule:
+    """
+    Creates a cron schedule.
+
+    Args:
+        cron: A valid cron string (e.g. "0 0 * * *").
+        timezone: A valid timezone string in IANA tzdata format (e.g. America/New_York).
+        day_or: Control how `day` and `day_of_week` entries are handled.
+            Defaults to True, matching cron which connects those values using
+            OR. If the switch is set to False, the values are connected using AND.
+            This behaves like fcron and enables you to e.g. define a job that
+            executes each 2nd friday of a month by setting the days of month and
+            the weekday.
+        active: Whether or not the schedule is active.
+        parameters: A dictionary containing parameter overrides for the schedule.
+        slug: A unique identifier for the schedule.
+
+    Returns:
+        A cron schedule.
+
+    Examples:
+        Create a cron schedule that runs every day at 12:00 AM UTC:
+        ```python
+        from prefect.schedules import Cron
+
+        Cron("0 0 * * *")
+        ```
+
+        Create a cron schedule that runs every Monday at 8:00 AM in the America/New_York timezone:
+        ```python
+        from prefect.schedules import Cron
+
+        Cron("0 8 * * 1", timezone="America/New_York")
+        ```
+
+    """
+    if parameters is None:
+        parameters = {}
+    return Schedule(
+        cron=cron,
+        timezone=timezone,
+        day_or=day_or,
+        active=active,
+        parameters=parameters,
+        slug=slug,
+    )
+
+
+def Interval(
+    interval: datetime.timedelta | float | int,
+    /,
+    anchor_date: datetime.datetime | None = None,
+    timezone: str | None = None,
+    active: bool = True,
+    parameters: dict[str, Any] | None = None,
+    slug: str | None = None,
+) -> Schedule:
+    """
+    Creates an interval schedule.
+
+    Args:
+        interval: The interval to use for the schedule. If an integer is provided,
+            it will be interpreted as seconds.
+        anchor_date: The anchor date to use for the schedule.
+        timezone: A valid timezone string in IANA tzdata format (e.g. America/New_York).
+        active: Whether or not the schedule is active.
+        parameters: A dictionary containing parameter overrides for the schedule.
+        slug: A unique identifier for the schedule.
+
+    Returns:
+        An interval schedule.
+
+    Examples:
+        Create an interval schedule that runs every hour:
+        ```python
+        from datetime import timedelta
+
+        from prefect.schedules import Interval
+
+        Interval(timedelta(hours=1))
+        ```
+
+        Create an interval schedule that runs every 60 seconds starting at a specific date:
+        ```python
+        from datetime import datetime
+
+        from prefect.schedules import Interval
+
+        Interval(60, anchor_date=datetime(2024, 1, 1))
+        ```
+    """
+    if isinstance(interval, (float, int)):
+        interval = datetime.timedelta(seconds=interval)
+    if anchor_date is None:
+        anchor_date = datetime.datetime.now(tz=datetime.timezone.utc)
+    if parameters is None:
+        parameters = {}
+    return Schedule(
+        interval=interval,
+        anchor_date=anchor_date,
+        timezone=timezone,
+        active=active,
+        parameters=parameters,
+        slug=slug,
+    )
+
+
+def RRule(
+    rrule: str,
+    /,
+    timezone: str | None = None,
+    active: bool = True,
+    parameters: dict[str, Any] | None = None,
+    slug: str | None = None,
+) -> Schedule:
+    """
+    Creates an RRule schedule.
+
+    Args:
+        rrule: A valid RRule string (e.g. "RRULE:FREQ=DAILY;INTERVAL=1").
+        timezone: A valid timezone string in IANA tzdata format (e.g. America/New_York).
+        active: Whether or not the schedule is active.
+        parameters: A dictionary containing parameter overrides for the schedule.
+        slug: A unique identifier for the schedule.
+
+    Returns:
+        An RRule schedule.
+
+    Examples:
+        Create an RRule schedule that runs every day at 12:00 AM UTC:
+        ```python
+        from prefect.schedules import RRule
+
+        RRule("RRULE:FREQ=DAILY;INTERVAL=1")
+        ```
+
+        Create an RRule schedule that runs every 2nd friday of the month in the America/Chicago timezone:
+        ```python
+        from prefect.schedules import RRule
+
+        RRule("RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=2FR", timezone="America/Chicago")
+        ```
+    """
+    if parameters is None:
+        parameters = {}
+    return Schedule(
+        rrule=rrule,
+        timezone=timezone,
+        active=active,
+        parameters=parameters,
+        slug=slug,
+    )

prefect/serializers.py

@@ -75,17 +75,17 @@ class Serializer(BaseModel, Generic[D]):
     """
 
     def __init__(self, **data: Any) -> None:
-        type_string = get_dispatch_key(self) if type(self) != Serializer else "__base__"
+        type_string = (
+            get_dispatch_key(self) if type(self) is not Serializer else "__base__"
+        )
         data.setdefault("type", type_string)
         super().__init__(**data)
 
     @overload
-    def __new__(cls, *, type: str, **kwargs: Any) -> "Serializer[Any]":
-        ...
+    def __new__(cls, *, type: str, **kwargs: Any) -> "Serializer[Any]": ...
 
     @overload
-    def __new__(cls, *, type: None = ..., **kwargs: Any) -> Self:
-        ...
+    def __new__(cls, *, type: None = ..., **kwargs: Any) -> Self: ...
 
     def __new__(cls, **kwargs: Any) -> Union[Self, "Serializer[Any]"]:
         if type_ := kwargs.get("type"):

prefect/settings/__init__.py

@@ -15,7 +15,7 @@ from prefect.settings.legacy import (
     _get_settings_fields,
     _get_valid_setting_names,
 )
-from prefect.settings.models.root import Settings
+from prefect.settings.models.root import Settings, canonical_environment_prefix
 
 from prefect.settings.profiles import (
     Profile,
@@ -51,6 +51,7 @@ __all__ = [  # noqa: F822
     "load_profiles",
     "get_current_settings",
     "temporary_settings",
+    "canonical_environment_prefix",
     "DEFAULT_PROFILES_PATH",
     # add public settings here for auto-completion
     "PREFECT_API_AUTH_STRING",  # type: ignore

prefect/settings/base.py

@@ -108,9 +108,9 @@ class PrefectBaseSettings(BaseSettings):
                 )
                 env_variables.update(child_env)
             elif (value := env.get(key)) is not None:
-                env_variables[
-                    f"{self.model_config.get('env_prefix')}{key.upper()}"
-                ] = _to_environment_variable_value(value)
+                env_variables[f"{self.model_config.get('env_prefix')}{key.upper()}"] = (
+                    _to_environment_variable_value(value)
+                )
         return env_variables
 
     @model_serializer(

prefect/settings/models/root.py

@@ -441,3 +441,7 @@ def _default_database_connection_url(settings: "Settings") -> SecretStr:
             f"Unsupported database driver: {settings.server.database.driver}"
         )
     return SecretStr(value)
+
+
+def canonical_environment_prefix(settings: "Settings") -> str:
+    return settings.model_config.get("env_prefix") or ""

prefect/settings/models/server/services.py

@@ -7,7 +7,14 @@ from pydantic_settings import SettingsConfigDict
 from prefect.settings.base import PrefectBaseSettings, build_settings_config
 
 
-class ServerServicesCancellationCleanupSettings(PrefectBaseSettings):
+class ServicesBaseSetting(PrefectBaseSettings):
+    enabled: bool = Field(
+        default=True,
+        description="Whether or not to start the service in the server application.",
+    )
+
+
+class ServerServicesCancellationCleanupSettings(ServicesBaseSetting):
     """
     Settings for controlling the cancellation cleanup service
     """
@@ -37,7 +44,7 @@ class ServerServicesCancellationCleanupSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesEventPersisterSettings(PrefectBaseSettings):
+class ServerServicesEventPersisterSettings(ServicesBaseSetting):
     """
     Settings for controlling the event persister service
     """
@@ -78,8 +85,38 @@ class ServerServicesEventPersisterSettings(PrefectBaseSettings):
         ),
     )
 
+    batch_size_delete: int = Field(
+        default=10_000,
+        gt=0,
+        description="The number of expired events and event resources the event persister will attempt to delete in one batch.",
+        validation_alias=AliasChoices(
+            AliasPath("batch_size_delete"),
+            "prefect_server_services_event_persister_batch_size_delete",
+        ),
+    )
+
+
+class ServerServicesEventLoggerSettings(ServicesBaseSetting):
+    """
+    Settings for controlling the event logger service
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = build_settings_config(
+        ("server", "services", "event_logger")
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Whether or not to start the event logger service in the server application.",
+        validation_alias=AliasChoices(
+            AliasPath("enabled"),
+            "prefect_server_services_event_logger_enabled",
+            "prefect_api_services_event_logger_enabled",
+        ),
+    )
+
 
-class ServerServicesFlowRunNotificationsSettings(PrefectBaseSettings):
+class ServerServicesFlowRunNotificationsSettings(ServicesBaseSetting):
     """
     Settings for controlling the flow run notifications service
     """
@@ -99,7 +136,7 @@ class ServerServicesFlowRunNotificationsSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesForemanSettings(PrefectBaseSettings):
+class ServerServicesForemanSettings(ServicesBaseSetting):
     """
     Settings for controlling the foreman service
     """
@@ -180,7 +217,7 @@ class ServerServicesForemanSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesLateRunsSettings(PrefectBaseSettings):
+class ServerServicesLateRunsSettings(ServicesBaseSetting):
     """
     Settings for controlling the late runs service
     """
@@ -224,7 +261,7 @@ class ServerServicesLateRunsSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesSchedulerSettings(PrefectBaseSettings):
+class ServerServicesSchedulerSettings(ServicesBaseSetting):
     """
     Settings for controlling the scheduler service
     """
@@ -349,7 +386,7 @@ class ServerServicesSchedulerSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesPauseExpirationsSettings(PrefectBaseSettings):
+class ServerServicesPauseExpirationsSettings(ServicesBaseSetting):
     """
     Settings for controlling the pause expiration service
     """
@@ -385,7 +422,7 @@ class ServerServicesPauseExpirationsSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesTaskRunRecorderSettings(PrefectBaseSettings):
+class ServerServicesTaskRunRecorderSettings(ServicesBaseSetting):
     """
     Settings for controlling the task run recorder service
     """
@@ -405,7 +442,7 @@ class ServerServicesTaskRunRecorderSettings(PrefectBaseSettings):
     )
 
 
-class ServerServicesTriggersSettings(PrefectBaseSettings):
+class ServerServicesTriggersSettings(ServicesBaseSetting):
     """
     Settings for controlling the triggers service
     """
@@ -442,6 +479,10 @@ class ServerServicesSettings(PrefectBaseSettings):
         default_factory=ServerServicesEventPersisterSettings,
         description="Settings for controlling the event persister service",
     )
+    event_logger: ServerServicesEventLoggerSettings = Field(
+        default_factory=ServerServicesEventLoggerSettings,
+        description="Settings for controlling the event logger service",
+    )
     flow_run_notifications: ServerServicesFlowRunNotificationsSettings = Field(
         default_factory=ServerServicesFlowRunNotificationsSettings,
         description="Settings for controlling the flow run notifications service",

prefect/settings/sources.py

@@ -188,7 +188,7 @@ class ProfileSettingsTomlLoader(PydanticBaseSettingsSource):
                             self.field_is_complex(field),
                         )
 
-        name = f"{self.config.get('env_prefix','')}{field_name.upper()}"
+        name = f"{self.config.get('env_prefix', '')}{field_name.upper()}"
         value = self.profile_settings.get(name)
         return value, field_name, self.field_is_complex(field)
 
@@ -266,9 +266,9 @@ class PrefectTomlConfigSettingsSource(TomlConfigSettingsSourceBase):
         settings_cls: Type[BaseSettings],
     ):
         super().__init__(settings_cls)
-        self.toml_file_path: Path | str | Sequence[
-            Path | str
-        ] | None = settings_cls.model_config.get("toml_file", DEFAULT_PREFECT_TOML_PATH)
+        self.toml_file_path: Path | str | Sequence[Path | str] | None = (
+            settings_cls.model_config.get("toml_file", DEFAULT_PREFECT_TOML_PATH)
+        )
         self.toml_data: dict[str, Any] = self._read_files(self.toml_file_path)
         self.toml_table_header: tuple[str, ...] = settings_cls.model_config.get(
             "prefect_toml_table_header", tuple()

prefect/states.py

@@ -12,13 +12,11 @@ from typing import TYPE_CHECKING, Any, Dict, Iterable, Optional, Type
 
 import anyio
 import httpx
-import pendulum
 from opentelemetry import propagate
 from typing_extensions import TypeGuard
 
 from prefect._internal.compatibility import deprecated
-from prefect.client.schemas import State as State
-from prefect.client.schemas import StateDetails, StateType
+from prefect.client.schemas.objects import State, StateDetails, StateType
 from prefect.exceptions import (
     CancelledRun,
     CrashedRun,
@@ -30,6 +28,7 @@ from prefect.exceptions import (
     UnfinishedRun,
 )
 from prefect.logging.loggers import get_logger, get_run_logger
+from prefect.types._datetime import DateTime, PendulumDuration
 from prefect.utilities.annotations import BaseAnnotation
 from prefect.utilities.asyncutils import in_async_main_thread, sync_compatible
 from prefect.utilities.collections import ensure_iterable
@@ -37,6 +36,7 @@ from prefect.utilities.collections import ensure_iterable
 if TYPE_CHECKING:
     import logging
 
+    from prefect.client.schemas.actions import StateCreate
     from prefect.results import (
         R,
         ResultStore,
@@ -45,6 +45,34 @@ if TYPE_CHECKING:
 logger: "logging.Logger" = get_logger("states")
 
 
+def to_state_create(state: State) -> "StateCreate":
+    """
+    Convert the state to a `StateCreate` type which can be used to set the state of
+    a run in the API.
+
+    This method will drop this state's `data` if it is not a result type. Only
+    results should be sent to the API. Other data is only available locally.
+    """
+    from prefect.client.schemas.actions import StateCreate
+    from prefect.results import (
+        ResultRecord,
+        should_persist_result,
+    )
+
+    if isinstance(state.data, ResultRecord) and should_persist_result():
+        data = state.data.metadata  # pyright: ignore[reportUnknownMemberType] unable to narrow ResultRecord type
+    else:
+        data = None
+
+    return StateCreate(
+        type=state.type,
+        name=state.name,
+        message=state.message,
+        data=data,
+        state_details=state.state_details,
+    )
+
+
 @deprecated.deprecated_parameter(
     "fetch",
     when=lambda fetch: fetch is not True,
@@ -97,10 +125,10 @@ async def _get_state_result_data_with_retries(
     # grace here about missing results.  The exception below could come in the form
     # of a missing file, a short read, or other types of errors depending on the
     # result storage backend.
-    from prefect.results import (
-        ResultRecord,
+    from prefect._result_records import (
         ResultRecordMetadata,
     )
+    from prefect.results import ResultStore
 
     if retry_result_failure is False:
         max_attempts = 1
@@ -110,7 +138,7 @@ async def _get_state_result_data_with_retries(
     for i in range(1, max_attempts + 1):
         try:
             if isinstance(state.data, ResultRecordMetadata):
-                record = await ResultRecord._from_metadata(state.data)
+                record = await ResultStore._from_metadata(state.data)
                 return record.result
             else:
                 return await state.data.get()
@@ -462,10 +490,11 @@ async def get_state_exception(state: State) -> BaseException:
         - `CrashedRun` if the state type is CRASHED.
         - `CancelledRun` if the state type is CANCELLED.
     """
-    from prefect.results import (
+    from prefect._result_records import (
         ResultRecord,
         ResultRecordMetadata,
     )
+    from prefect.results import ResultStore
 
     if state.is_failed():
         wrapper = FailedRun
@@ -482,7 +511,7 @@ async def get_state_exception(state: State) -> BaseException:
     if isinstance(state.data, ResultRecord):
         result = state.data.result
     elif isinstance(state.data, ResultRecordMetadata):
-        record = await ResultRecord._from_metadata(state.data)
+        record = await ResultStore._from_metadata(state.data)
         result = record.result
     elif state.data is None:
         result = None
@@ -631,7 +660,7 @@ def Scheduled(
     """
     state_details = StateDetails.model_validate(kwargs.pop("state_details", {}))
     if scheduled_time is None:
-        scheduled_time = pendulum.now("UTC")
+        scheduled_time = DateTime.now("UTC")
     elif state_details.scheduled_time:
         raise ValueError("An extra scheduled_time was provided in state_details")
     state_details.scheduled_time = scheduled_time
@@ -729,8 +758,10 @@ def Paused(
     if pause_expiration_time is None and timeout_seconds is None:
         pass
     else:
-        state_details.pause_timeout = pause_expiration_time or (
-            pendulum.now("UTC") + pendulum.Duration(seconds=timeout_seconds)
+        state_details.pause_timeout = (
+            DateTime.instance(pause_expiration_time)
+            if pause_expiration_time
+            else DateTime.now("UTC") + PendulumDuration(seconds=timeout_seconds or 0)
         )
 
     state_details.pause_reschedule = reschedule