prefect-client 3.0.10__py3-none-any.whl → 3.0.11__py3-none-any.whl

prefect/runner/runner.py

@@ -32,7 +32,6 @@ Example:
 
 import asyncio
 import datetime
-import inspect
 import logging
 import os
 import shutil
@@ -1213,7 +1212,7 @@ class Runner:
                 task_status.started()
 
             result = fn(*args, **kwargs)
-            if inspect.iscoroutine(result):
+            if asyncio.iscoroutine(result):
                 await result
 
         await self._runs_task_group.start(wrapper)

prefect/runner/server.py

@@ -298,4 +298,15 @@ def start_webserver(runner: "Runner", log_level: Optional[str] = None) -> None:
     port = PREFECT_RUNNER_SERVER_PORT.value()
     log_level = log_level or PREFECT_RUNNER_SERVER_LOG_LEVEL.value()
     webserver = build_server(runner)
-    uvicorn.run(webserver, host=host, port=port, log_level=log_level)
+    uvicorn.run(
+        webserver, host=host, port=port, log_level=log_level.lower()
+    )  # Uvicorn supports only lowercase log_level
+    # From the Uvicorn config file:
+    # LOG_LEVELS: dict[str, int] = {
+    #     "critical": logging.CRITICAL,
+    #     "error": logging.ERROR,
+    #     "warning": logging.WARNING,
+    #     "info": logging.INFO,
+    #     "debug": logging.DEBUG,
+    #     "trace": TRACE_LOG_LEVEL,
+    # }

prefect/settings/__init__.py

@@ -0,0 +1,59 @@
+"""
+Prefect settings are defined using `BaseSettings` from `pydantic_settings`. `BaseSettings` can load setting values
+from system environment variables and each additionally specified `env_file`.
+
+The recommended user-facing way to access Prefect settings at this time is to import specific setting objects directly,
+like `from prefect.settings import PREFECT_API_URL; print(PREFECT_API_URL.value())`.
+
+Importantly, we replace the `callback` mechanism for updating settings with an "after" model_validator that updates dependent settings.
+After https://github.com/pydantic/pydantic/issues/9789 is resolved, we will be able to define context-aware defaults
+for settings, at which point we will not need to use the "after" model_validator.
+"""
+
+from prefect.settings.legacy import (
+    Setting,
+    _get_settings_fields,
+    _get_valid_setting_names,
+)
+from prefect.settings.models.root import Settings
+
+from prefect.settings.profiles import (
+    Profile,
+    ProfilesCollection,
+    load_current_profile,
+    update_current_profile,
+    load_profile,
+    save_profiles,
+    load_profiles,
+)
+from prefect.settings.context import get_current_settings, temporary_settings
+from prefect.settings.constants import DEFAULT_PROFILES_PATH
+
+############################################################################
+# Allow traditional env var access
+
+
+def __getattr__(name: str) -> Setting:
+    if name in _get_valid_setting_names(Settings):
+        return _get_settings_fields(Settings)[name]
+    raise AttributeError(f"{name} is not a Prefect setting.")
+
+
+__all__ = [  # noqa: F822
+    "Profile",
+    "ProfilesCollection",
+    "Setting",
+    "Settings",
+    "load_current_profile",
+    "update_current_profile",
+    "load_profile",
+    "save_profiles",
+    "load_profiles",
+    "get_current_settings",
+    "temporary_settings",
+    "DEFAULT_PROFILES_PATH",
+    # add public settings here for auto-completion
+    "PREFECT_API_KEY",  # type: ignore
+    "PREFECT_API_URL",  # type: ignore
+    "PREFECT_UI_URL",  # type: ignore
+]

prefect/settings/base.py

@@ -0,0 +1,131 @@
+from functools import partial
+from typing import Any, Dict, Tuple, Type
+
+from pydantic import (
+    AliasChoices,
+    AliasPath,
+    SerializationInfo,
+    SerializerFunctionWrapHandler,
+    model_serializer,
+)
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+
+from prefect.settings.sources import EnvFilterSettingsSource, ProfileSettingsTomlLoader
+from prefect.utilities.collections import visit_collection
+from prefect.utilities.pydantic import handle_secret_render
+
+
+class PrefectBaseSettings(BaseSettings):
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: Type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> Tuple[PydanticBaseSettingsSource, ...]:
+        """
+        Define an order for Prefect settings sources.
+
+        The order of the returned callables decides the priority of inputs; first item is the highest priority.
+
+        See https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources
+        """
+        env_filter = set()
+        for field in settings_cls.model_fields.values():
+            if field.validation_alias is not None and isinstance(
+                field.validation_alias, AliasChoices
+            ):
+                for alias in field.validation_alias.choices:
+                    if isinstance(alias, AliasPath) and len(alias.path) > 0:
+                        env_filter.add(alias.path[0])
+        return (
+            init_settings,
+            EnvFilterSettingsSource(
+                settings_cls,
+                case_sensitive=cls.model_config.get("case_sensitive"),
+                env_prefix=cls.model_config.get("env_prefix"),
+                env_nested_delimiter=cls.model_config.get("env_nested_delimiter"),
+                env_ignore_empty=cls.model_config.get("env_ignore_empty"),
+                env_parse_none_str=cls.model_config.get("env_parse_none_str"),
+                env_parse_enums=cls.model_config.get("env_parse_enums"),
+                env_filter=list(env_filter),
+            ),
+            dotenv_settings,
+            file_secret_settings,
+            ProfileSettingsTomlLoader(settings_cls),
+        )
+
+    def to_environment_variables(
+        self,
+        exclude_unset: bool = False,
+        include_secrets: bool = True,
+    ) -> Dict[str, str]:
+        """Convert the settings object to a dictionary of environment variables."""
+
+        env: Dict[str, Any] = self.model_dump(
+            exclude_unset=exclude_unset,
+            mode="json",
+            context={"include_secrets": include_secrets},
+        )
+        env_variables = {}
+        for key in self.model_fields.keys():
+            if isinstance(child_settings := getattr(self, key), PrefectBaseSettings):
+                child_env = child_settings.to_environment_variables(
+                    exclude_unset=exclude_unset,
+                    include_secrets=include_secrets,
+                )
+                env_variables.update(child_env)
+            elif (value := env.get(key)) is not None:
+                env_variables[
+                    f"{self.model_config.get('env_prefix')}{key.upper()}"
+                ] = str(value)
+        return env_variables
+
+    @model_serializer(
+        mode="wrap", when_used="always"
+    )  # TODO: reconsider `when_used` default for more control
+    def ser_model(
+        self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
+    ) -> Any:
+        jsonable_self = handler(self)
+        # iterate over fields to ensure child models that have been updated are also included
+        for key in self.model_fields.keys():
+            if info.exclude and key in info.exclude:
+                continue
+            if info.include and key not in info.include:
+                continue
+
+            child_include = None
+            child_exclude = None
+            if info.include and key in info.include and isinstance(info.include, dict):
+                child_include = info.include[key]
+
+            if isinstance(child_settings := getattr(self, key), PrefectBaseSettings):
+                child_jsonable = child_settings.model_dump(
+                    mode=info.mode,
+                    include=child_include,
+                    exclude=child_exclude,
+                    exclude_unset=info.exclude_unset,
+                    context=info.context,
+                    by_alias=info.by_alias,
+                    exclude_none=info.exclude_none,
+                    exclude_defaults=info.exclude_defaults,
+                    serialize_as_any=info.serialize_as_any,
+                )
+                if child_jsonable:
+                    jsonable_self[key] = child_jsonable
+        if info.context and info.context.get("include_secrets") is True:
+            jsonable_self.update(
+                {
+                    field_name: visit_collection(
+                        expr=getattr(self, field_name),
+                        visit_fn=partial(handle_secret_render, context=info.context),
+                        return_data=True,
+                    )
+                    for field_name in set(jsonable_self.keys())  # type: ignore
+                }
+            )
+
+        return jsonable_self

prefect/settings/constants.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+from typing import Tuple, Type
+
+from pydantic import Secret, SecretStr
+
+DEFAULT_PREFECT_HOME = Path.home() / ".prefect"
+DEFAULT_PROFILES_PATH = Path(__file__).parent.joinpath("profiles.toml")
+_SECRET_TYPES: Tuple[Type, ...] = (Secret, SecretStr)

prefect/settings/context.py

@@ -0,0 +1,65 @@
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Generator, Iterable, Mapping, Optional
+
+from prefect.settings.models.root import Settings
+
+if TYPE_CHECKING:
+    from prefect.settings.legacy import Setting
+
+
+def get_current_settings() -> Settings:
+    """
+    Returns a settings object populated with values from the current settings context
+    or, if no settings context is active, the environment.
+    """
+    from prefect.context import SettingsContext
+
+    settings_context = SettingsContext.get()
+    if settings_context is not None:
+        return settings_context.settings
+
+    return Settings()
+
+
+@contextmanager
+def temporary_settings(
+    updates: Optional[Mapping["Setting", Any]] = None,
+    set_defaults: Optional[Mapping["Setting", Any]] = None,
+    restore_defaults: Optional[Iterable["Setting"]] = None,
+) -> Generator[Settings, None, None]:
+    """
+    Temporarily override the current settings by entering a new profile.
+
+    See `Settings.copy_with_update` for details on different argument behavior.
+
+    Examples:
+        >>> from prefect.settings import PREFECT_API_URL
+        >>>
+        >>> with temporary_settings(updates={PREFECT_API_URL: "foo"}):
+        >>>    assert PREFECT_API_URL.value() == "foo"
+        >>>
+        >>>    with temporary_settings(set_defaults={PREFECT_API_URL: "bar"}):
+        >>>         assert PREFECT_API_URL.value() == "foo"
+        >>>
+        >>>    with temporary_settings(restore_defaults={PREFECT_API_URL}):
+        >>>         assert PREFECT_API_URL.value() is None
+        >>>
+        >>>         with temporary_settings(set_defaults={PREFECT_API_URL: "bar"})
+        >>>             assert PREFECT_API_URL.value() == "bar"
+        >>> assert PREFECT_API_URL.value() is None
+    """
+    import prefect.context
+
+    context = prefect.context.get_settings_context()
+
+    if not restore_defaults:
+        restore_defaults = []
+
+    new_settings = context.settings.copy_with_update(
+        updates=updates, set_defaults=set_defaults, restore_defaults=restore_defaults
+    )
+
+    with prefect.context.SettingsContext(
+        profile=context.profile, settings=new_settings
+    ):
+        yield new_settings

prefect/settings/legacy.py

@@ -0,0 +1,167 @@
+import inspect
+import os
+from functools import cache
+from typing import Any, Dict, Optional, Set, Type, get_args
+
+from pydantic import AliasChoices
+from pydantic_settings import BaseSettings
+from typing_extensions import Self
+
+from prefect.settings.base import PrefectBaseSettings
+from prefect.settings.constants import _SECRET_TYPES
+from prefect.settings.context import get_current_settings
+from prefect.settings.models.root import Settings
+
+
+class Setting:
+    """Mimics the old Setting object for compatibility with existing code."""
+
+    def __init__(
+        self, name: str, default: Any, type_: Any, accessor: Optional[str] = None
+    ):
+        self._name = name
+        self._default = default
+        self._type = type_
+        if accessor is None:
+            self.accessor = _env_var_to_accessor(name)
+        else:
+            self.accessor = accessor
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def is_secret(self):
+        if self._type in _SECRET_TYPES:
+            return True
+        for secret_type in _SECRET_TYPES:
+            if secret_type in get_args(self._type):
+                return True
+        return False
+
+    def default(self):
+        return self._default
+
+    def value(self: Self) -> Any:
+        if (
+            self.name == "PREFECT_TEST_SETTING"
+            or self.name == "PREFECT_TESTING_TEST_SETTING"
+        ):
+            if (
+                "PREFECT_TEST_MODE" in os.environ
+                or "PREFECT_TESTING_TEST_MODE" in os.environ
+            ):
+                return get_current_settings().testing.test_setting
+            else:
+                return None
+
+        return self.value_from(get_current_settings())
+
+    def value_from(self: Self, settings: "Settings") -> Any:
+        path = self.accessor.split(".")
+        current_value = settings
+        for key in path:
+            current_value = getattr(current_value, key, None)
+        if isinstance(current_value, _SECRET_TYPES):
+            return current_value.get_secret_value()
+        return current_value
+
+    def __bool__(self) -> bool:
+        return bool(self.value())
+
+    def __str__(self) -> str:
+        return str(self.value())
+
+    def __repr__(self) -> str:
+        return f"<{self.name}: {self._type!r}>"
+
+    def __eq__(self, __o: object) -> bool:
+        return __o.__eq__(self.value())
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.name))
+
+
+def _env_var_to_accessor(env_var: str) -> str:
+    """
+    Convert an environment variable name to a settings accessor.
+    """
+    if (field := _get_settings_fields(Settings).get(env_var)) is not None:
+        return field.accessor
+    return env_var.replace("PREFECT_", "").lower()
+
+
+@cache
+def _get_valid_setting_names(cls: type[BaseSettings]) -> Set[str]:
+    """
+    A set of valid setting names, e.g. "PREFECT_API_URL" or "PREFECT_API_KEY".
+    """
+    settings_fields = set()
+    for field_name, field in cls.model_fields.items():
+        if inspect.isclass(field.annotation) and issubclass(
+            field.annotation, PrefectBaseSettings
+        ):
+            settings_fields.update(_get_valid_setting_names(field.annotation))
+        else:
+            if field.validation_alias and isinstance(
+                field.validation_alias, AliasChoices
+            ):
+                for alias in field.validation_alias.choices:
+                    if not isinstance(alias, str):
+                        continue
+                    settings_fields.add(alias.upper())
+            else:
+                settings_fields.add(
+                    f"{cls.model_config.get('env_prefix')}{field_name.upper()}"
+                )
+    return settings_fields
+
+
+@cache
+def _get_settings_fields(
+    settings: Type[BaseSettings], accessor_prefix: Optional[str] = None
+) -> Dict[str, "Setting"]:
+    """Get the settings fields for the settings object"""
+    settings_fields: Dict[str, Setting] = {}
+    for field_name, field in settings.model_fields.items():
+        if inspect.isclass(field.annotation) and issubclass(
+            field.annotation, PrefectBaseSettings
+        ):
+            accessor = (
+                field_name
+                if accessor_prefix is None
+                else f"{accessor_prefix}.{field_name}"
+            )
+            settings_fields.update(_get_settings_fields(field.annotation, accessor))
+        else:
+            accessor = (
+                field_name
+                if accessor_prefix is None
+                else f"{accessor_prefix}.{field_name}"
+            )
+            if field.validation_alias and isinstance(
+                field.validation_alias, AliasChoices
+            ):
+                for alias in field.validation_alias.choices:
+                    if not isinstance(alias, str):
+                        continue
+                    setting = Setting(
+                        name=alias.upper(),
+                        default=field.default,
+                        type_=field.annotation,
+                        accessor=accessor,
+                    )
+                    settings_fields[setting.name] = setting
+                    settings_fields[setting.accessor] = setting
+            else:
+                setting = Setting(
+                    name=f"{settings.model_config.get('env_prefix')}{field_name.upper()}",
+                    default=field.default,
+                    type_=field.annotation,
+                    accessor=accessor,
+                )
+                settings_fields[setting.name] = setting
+                settings_fields[setting.accessor] = setting
+
+    return settings_fields

prefect/settings/models/api.py

@@ -0,0 +1,41 @@
+import os
+from typing import Optional
+
+from pydantic import Field, SecretStr
+from pydantic_settings import SettingsConfigDict
+
+from prefect.settings.base import PrefectBaseSettings
+
+
+class APISettings(PrefectBaseSettings):
+    """
+    Settings for interacting with the Prefect API
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PREFECT_API_", env_file=".env", extra="ignore"
+    )
+    url: Optional[str] = Field(
+        default=None,
+        description="The URL of the Prefect API. If not set, the client will attempt to infer it.",
+    )
+    key: Optional[SecretStr] = Field(
+        default=None,
+        description="The API key used for authentication with the Prefect API. Should be kept secret.",
+    )
+    tls_insecure_skip_verify: bool = Field(
+        default=False,
+        description="If `True`, disables SSL checking to allow insecure requests. This is recommended only during development, e.g. when using self-signed certificates.",
+    )
+    ssl_cert_file: Optional[str] = Field(
+        default=os.environ.get("SSL_CERT_FILE"),
+        description="This configuration settings option specifies the path to an SSL certificate file.",
+    )
+    enable_http2: bool = Field(
+        default=False,
+        description="If true, enable support for HTTP/2 for communicating with an API. If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.",
+    )
+    request_timeout: float = Field(
+        default=60.0,
+        description="The default timeout for requests to the API",
+    )

prefect/settings/models/cli.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+from prefect.settings.base import PrefectBaseSettings
+
+
+class CLISettings(PrefectBaseSettings):
+    """
+    Settings for controlling CLI behavior
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PREFECT_CLI_", env_file=".env", extra="ignore"
+    )
+
+    colors: bool = Field(
+        default=True,
+        description="If True, use colors in CLI output. If `False`, output will not include colors codes.",
+    )
+
+    prompt: Optional[bool] = Field(
+        default=None,
+        description="If `True`, use interactive prompts in CLI commands. If `False`, no interactive prompts will be used. If `None`, the value will be dynamically determined based on the presence of an interactive-enabled terminal.",
+    )
+
+    wrap_lines: bool = Field(
+        default=True,
+        description="If `True`, wrap text by inserting new lines in long lines in CLI output. If `False`, output will not be wrapped.",
+    )

prefect/settings/models/client.py

@@ -0,0 +1,90 @@
+from pydantic import AliasChoices, AliasPath, Field
+from pydantic_settings import SettingsConfigDict
+
+from prefect.settings.base import PrefectBaseSettings
+from prefect.types import ClientRetryExtraCodes
+
+
+class ClientMetricsSettings(PrefectBaseSettings):
+    """
+    Settings for controlling metrics reporting from the client
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PREFECT_CLIENT_METRICS_", env_file=".env", extra="ignore"
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Whether or not to enable Prometheus metrics in the client.",
+        # Using alias for backwards compatibility. Need to duplicate the prefix because
+        # Pydantic does not allow the alias to be prefixed with the env_prefix. The AliasPath
+        # needs to be first to ensure that init kwargs take precedence over env vars.
+        validation_alias=AliasChoices(
+            AliasPath("enabled"),
+            "prefect_client_metrics_enabled",
+            "prefect_client_enable_metrics",
+        ),
+    )
+
+    port: int = Field(
+        default=4201, description="The port to expose the client Prometheus metrics on."
+    )
+
+
+class ClientSettings(PrefectBaseSettings):
+    """
+    Settings for controlling API client behavior
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PREFECT_CLIENT_", env_file=".env", extra="ignore"
+    )
+
+    max_retries: int = Field(
+        default=5,
+        ge=0,
+        description="""
+        The maximum number of retries to perform on failed HTTP requests.
+        Defaults to 5. Set to 0 to disable retries.
+        See `PREFECT_CLIENT_RETRY_EXTRA_CODES` for details on which HTTP status codes are
+        retried.
+        """,
+    )
+
+    retry_jitter_factor: float = Field(
+        default=0.2,
+        ge=0.0,
+        description="""
+        A value greater than or equal to zero to control the amount of jitter added to retried
+        client requests. Higher values introduce larger amounts of jitter.
+        Set to 0 to disable jitter. See `clamped_poisson_interval` for details on the how jitter
+        can affect retry lengths.
+        """,
+    )
+
+    retry_extra_codes: ClientRetryExtraCodes = Field(
+        default_factory=set,
+        description="""
+        A list of extra HTTP status codes to retry on. Defaults to an empty list.
+        429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
+        may result in unexpected behavior.
+        """,
+        examples=["404,429,503", "429", {404, 429, 503}],
+    )
+
+    csrf_support_enabled: bool = Field(
+        default=True,
+        description="""
+        Determines if CSRF token handling is active in the Prefect client for API
+        requests.
+
+        When enabled (`True`), the client automatically manages CSRF tokens by
+        retrieving, storing, and including them in applicable state-changing requests
+        """,
+    )
+
+    metrics: ClientMetricsSettings = Field(
+        default_factory=ClientMetricsSettings,
+        description="Settings for controlling metrics reporting from the client",
+    )