prefect-client 3.4.24.dev3__tar.gz → 3.4.24.dev4__tar.gz

{prefect_client-3.4.24.dev3 → prefect_client-3.4.24.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.4.24.dev3
+Version: 3.4.24.dev4
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect_client-3.4.24.dev3 → prefect_client-3.4.24.dev4}/src/prefect/__init__.py

@@ -65,6 +65,57 @@ __ui_static_path__: pathlib.Path = __module_path__ / "server" / "ui"
 
 del _build_info, pathlib
 
+
+def _initialize_plugins() -> None:
+    """
+    Initialize the experimental plugin system if enabled.
+
+    This runs automatically when Prefect is imported and plugins are enabled
+    via experiments.plugins.enabled setting. Errors are logged but don't prevent
+    Prefect from loading.
+    """
+    try:
+        # Import here to avoid circular imports and defer cost until needed
+        from prefect.settings import get_current_settings
+
+        if not get_current_settings().experiments.plugins.enabled:
+            return
+
+        import anyio
+
+        from prefect._experimental.plugins import run_startup_hooks
+        from prefect._experimental.plugins.spec import HookContext
+        from prefect.logging import get_logger
+        from prefect.settings import get_current_settings
+
+        ctx = HookContext(
+            prefect_version=__version__,
+            api_url=get_current_settings().api.url,
+            logger_factory=get_logger,
+        )
+
+        # Run plugin hooks synchronously during import
+        anyio.run(run_startup_hooks, ctx)
+    except SystemExit:
+        # Re-raise SystemExit from strict mode
+        raise
+    except Exception as e:
+        # Log but don't crash on plugin errors
+        try:
+            from prefect.logging import get_logger
+
+            logger = get_logger("prefect.plugins")
+            logger.exception("Failed to initialize plugins: %s", e)
+        except Exception:
+            # If even logging fails, print to stderr and continue
+            import sys
+
+            print(f"Failed to initialize plugins: {e}", file=sys.stderr)
+
+
+# Initialize plugins on import if enabled
+_initialize_plugins()
+
 _public_api: dict[str, tuple[Optional[str], str]] = {
     "allow_failure": (__spec__.parent, ".main"),
     "aserve": (__spec__.parent, ".main"),

prefect_client-3.4.24.dev4/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.4.24.dev4"
+__build_date__ = "2025-10-15 08:09:24.517909+00:00"
+__git_commit__ = "4d7bea0be73f046c90a05a964312a8e86261e17d"
+__dirty__ = False

prefect_client-3.4.24.dev4/src/prefect/_experimental/plugins/__init__.py

@@ -0,0 +1,139 @@
+"""
+Experimental plugin system for Prefect.
+
+This module provides a startup hook system that allows third-party packages
+to run initialization code before Prefect CLI commands, workers, or agents
+start their main work.
+
+**Note: This is an experimental API and is subject to change.**
+"""
+
+from __future__ import annotations
+from typing import Any
+
+import anyio
+
+from prefect._experimental.plugins.apply import apply_setup_result, summarize_env
+from prefect._experimental.plugins.diagnostics import SetupSummary
+from prefect._experimental.plugins.manager import (
+    build_manager,
+    call_async_hook,
+    load_entry_point_plugins,
+    register_hook,
+)
+from prefect._experimental.plugins.spec import (
+    PREFECT_PLUGIN_API_VERSION,
+    HookContext,
+    HookSpec,
+    SetupResult,
+)
+from prefect.settings import get_current_settings
+
+__all__ = [
+    "run_startup_hooks",
+    "HookContext",
+    "SetupResult",
+    "HookSpec",
+    "SetupSummary",
+    "PREFECT_PLUGIN_API_VERSION",
+    "register_hook",
+]
+
+
+async def run_startup_hooks(ctx: HookContext) -> list[SetupSummary]:
+    """
+    Run all registered plugin startup hooks.
+
+    This is the main entry point for the plugin system. It:
+    1. Checks if plugins are enabled via configuration
+    2. Discovers and loads plugins from entry points
+    3. Calls setup_environment hooks (respecting timeouts)
+    4. Applies environment changes from successful hooks
+    5. Returns diagnostic summaries
+
+    Args:
+        ctx: Context object with Prefect version, API URL, and logger factory
+
+    Returns:
+        List of SetupSummary objects describing what each plugin did
+
+    Raises:
+        SystemExit: In strict mode, if a required plugin fails
+    """
+    logger = ctx.logger_factory("prefect.plugins")
+    settings = get_current_settings().experiments.plugins
+
+    if not settings.enabled:
+        logger.debug("Experimental plugins not enabled")
+        return []
+
+    logger.debug("Initializing experimental plugin system")
+    pm = build_manager(HookSpec)
+    allow = settings.allow
+    deny = settings.deny
+    load_entry_point_plugins(pm, allow=allow, deny=deny, logger=logger)
+
+    summaries: list[SetupSummary] = []
+
+    if settings.safe_mode:
+        logger.info("Safe mode enabled - plugins loaded but hooks not called")
+        return summaries
+
+    # Call all hooks with timeout
+    timeout = settings.setup_timeout_seconds
+    results: list[tuple[str, Any, Exception | None]] = []
+
+    try:
+        with anyio.move_on_after(timeout) as cancel_scope:
+            results = await call_async_hook(pm, "setup_environment", ctx=ctx)
+
+        if cancel_scope.cancel_called:
+            logger.warning("Plugin setup timed out after %.1fs", timeout)
+    except Exception as e:
+        logger.exception("Unexpected error during plugin setup: %s", e)
+
+    # Process results
+    for name, res, err in results:
+        if err:
+            logger.error("Plugin %s failed: %s", name, err)
+            summaries.append(
+                SetupSummary(plugin=name, env_preview={}, note=None, error=str(err))
+            )
+            continue
+
+        if res is None:
+            logger.debug("Plugin %s returned no changes", name)
+            summaries.append(
+                SetupSummary(plugin=name, env_preview={}, note=None, error=None)
+            )
+            continue
+
+        try:
+            apply_setup_result(res, logger)
+            summaries.append(
+                SetupSummary(
+                    name,
+                    summarize_env(dict(res.env)),
+                    res.note,
+                    error=None,
+                )
+            )
+            logger.debug("Plugin %s completed successfully", name)
+        except Exception as e:
+            logger.exception("Failed to apply result from plugin %s", name)
+            summaries.append(SetupSummary(name, {}, None, None, error=str(e)))
+
+    # Strict failure policy
+    if settings.strict:
+        for name, res, err in results:
+            if err:
+                raise SystemExit(f"[plugins] required plugin '{name}' failed: {err}")
+            if res and getattr(res, "required", False) and not res.env:
+                raise SystemExit(
+                    f"[plugins] required plugin '{name}' returned SetupResult with "
+                    f"required=True but empty env. If no changes are needed, return "
+                    f"None instead of SetupResult."
+                )
+
+    logger.info("Plugin system initialization complete (%d plugins)", len(summaries))
+    return summaries

prefect_client-3.4.24.dev4/src/prefect/_experimental/plugins/apply.py

@@ -0,0 +1,62 @@
+"""
+Safe application of plugin setup results with secret redaction.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from prefect._experimental.plugins.spec import SetupResult
+
+REDACT_KEYS = ("SECRET", "TOKEN", "PASSWORD", "KEY")
+
+
+def redact(key: str, value: str) -> str:
+    """
+    Redact sensitive values based on key name heuristics.
+
+    Args:
+        key: Environment variable name
+        value: Environment variable value
+
+    Returns:
+        Redacted value if the key appears sensitive, otherwise truncated value
+    """
+    k = key.upper()
+    if any(tag in k for tag in REDACT_KEYS):
+        return "••••••"
+    return value if len(value) <= 64 else value[:20] + "…"
+
+
+def apply_setup_result(result: SetupResult, logger: logging.Logger) -> None:
+    """
+    Apply environment changes to the current process.
+
+    This function never logs secrets - all values are redacted based on key name
+    heuristics.
+
+    Args:
+        result: The SetupResult containing environment variables to set
+        logger: Logger to use for informational messages
+    """
+    for k, v in (result.env or {}).items():
+        os.environ[str(k)] = str(v)
+    note = result.note or ""
+    logger.info(
+        "plugin env applied%s",
+        f" — {note}" if note else "",
+    )
+
+
+def summarize_env(env: dict[str, str]) -> dict[str, str]:
+    """
+    Create a safe summary of environment variables with redacted values.
+
+    Args:
+        env: Dictionary of environment variables
+
+    Returns:
+        Dictionary with same keys but redacted values
+    """
+    return {k: redact(k, v) for k, v in env.items()}

prefect_client-3.4.24.dev4/src/prefect/_experimental/plugins/diagnostics.py

@@ -0,0 +1,25 @@
+"""
+Diagnostic data structures for plugin system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SetupSummary:
+    """
+    Summary of a plugin's setup_environment execution.
+
+    Attributes:
+        plugin: Name of the plugin
+        env_preview: Preview of environment variables set (with redacted values)
+        note: Human-readable note from the plugin, if any
+        error: Error message if the plugin failed, or None if successful
+    """
+
+    plugin: str
+    env_preview: dict[str, str]
+    note: str | None
+    error: str | None

prefect_client-3.4.24.dev4/src/prefect/_experimental/plugins/manager.py

@@ -0,0 +1,133 @@
+"""
+Plugin manager using pluggy with async bridge.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata as md
+import inspect
+import logging
+import sys
+from typing import Any
+
+import pluggy
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+from prefect._experimental.plugins.spec import PREFECT_PLUGIN_API_VERSION
+
+PM_PROJECT_NAME = "prefect-experimental"
+ENTRYPOINTS_GROUP = "prefect.plugins"
+
+register_hook = pluggy.HookimplMarker(PM_PROJECT_NAME)
+
+
+def build_manager(hookspecs: type) -> pluggy.PluginManager:
+    """
+    Create a pluggy PluginManager and register hook specifications.
+
+    Args:
+        hookspecs: The hook specification class/protocol
+
+    Returns:
+        Configured PluginManager instance
+    """
+    pm = pluggy.PluginManager(PM_PROJECT_NAME)
+    pm.add_hookspecs(hookspecs)
+    return pm
+
+
+def load_entry_point_plugins(
+    pm: pluggy.PluginManager,
+    *,
+    allow: set[str] | None,
+    deny: set[str] | None,
+    logger: logging.Logger,
+) -> None:
+    """
+    Discover and load plugins from entry points.
+
+    Args:
+        pm: The PluginManager to register plugins with
+        allow: If set, only load plugins with names in this set
+        deny: If set, skip plugins with names in this set
+        logger: Logger for reporting load failures
+    """
+    # Python 3.10+ supports group parameter, 3.9 requires dict access
+    if sys.version_info >= (3, 10):
+        entry_points_list = md.entry_points(group=ENTRYPOINTS_GROUP)
+    else:
+        # Python 3.9 returns a dict-like object
+        entry_points_list = md.entry_points().get(ENTRYPOINTS_GROUP, [])
+
+    for ep in entry_points_list:
+        if allow and ep.name not in allow:
+            logger.debug("Skipping plugin %s (not in allow list)", ep.name)
+            continue
+        if deny and ep.name in deny:
+            logger.debug("Skipping plugin %s (in deny list)", ep.name)
+            continue
+        try:
+            plugin = ep.load()
+            # Version fence (best effort)
+            requires = getattr(plugin, "PREFECT_PLUGIN_API_REQUIRES", ">=0.1,<1")
+
+            # Validate plugin API version requirement
+            try:
+                spec = SpecifierSet(requires)
+                if PREFECT_PLUGIN_API_VERSION not in spec:
+                    logger.warning(
+                        "Skipping plugin %s: requires API version %s, current version is %s",
+                        ep.name,
+                        requires,
+                        PREFECT_PLUGIN_API_VERSION,
+                    )
+                    continue
+            except InvalidSpecifier:
+                logger.debug(
+                    "Plugin %s has invalid version specifier %r, ignoring version check",
+                    ep.name,
+                    requires,
+                )
+
+            pm.register(plugin, name=ep.name)
+            logger.debug(
+                "Loaded plugin %s (requires API %s, current %s)",
+                ep.name,
+                requires,
+                PREFECT_PLUGIN_API_VERSION,
+            )
+        except Exception:
+            logger.exception("Failed to load plugin %s", ep.name)
+
+
+async def call_async_hook(
+    pm: pluggy.PluginManager, hook_name: str, **kwargs: Any
+) -> list[tuple[str, Any, Exception | None]]:
+    """
+    Call a hook that may return coroutines.
+
+    This function handles both sync and async hook implementations, gathering
+    results and exceptions per plugin.
+
+    Args:
+        pm: The PluginManager
+        hook_name: Name of the hook to call
+        **kwargs: Arguments to pass to the hook
+
+    Returns:
+        List of tuples: (plugin_name, result, exception)
+        - If successful: (name, result, None)
+        - If failed: (name, None, exception)
+    """
+    hook = getattr(pm.hook, hook_name)
+    results: list[tuple[str, Any, Exception | None]] = []
+    for impl in hook.get_hookimpls():
+        fn = impl.function
+        try:
+            res = fn(**kwargs)
+            if inspect.iscoroutine(res):
+                res = await res
+            results.append((impl.plugin_name, res, None))
+        except Exception as exc:
+            results.append((impl.plugin_name, None, exc))
+    return results

prefect_client-3.4.24.dev4/src/prefect/_experimental/plugins/spec.py

@@ -0,0 +1,85 @@
+"""
+Experimental plugin API specification.
+
+This module defines the hook specification and data structures for Prefect's
+experimental plugin system.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Callable, Mapping, Optional
+
+import pluggy
+
+# Bump this when breaking the hook contract
+PREFECT_PLUGIN_API_VERSION = "0.1"
+
+hookspec = pluggy.HookspecMarker("prefect-experimental")
+
+
+@dataclass
+class HookContext:
+    """
+    Context provided to plugin hooks at startup.
+
+    Attributes:
+        prefect_version: The version of Prefect running
+        api_url: The configured Prefect API URL, if any
+        logger_factory: Factory function to create a stdlib logger for the plugin
+    """
+
+    prefect_version: str
+    api_url: str | None
+    # Logger factory returns a stdlib logger; plugins should use this.
+    logger_factory: Callable[[str], logging.Logger]
+    # Future: async Prefect client getter, settings snapshot, etc.
+
+
+@dataclass
+class SetupResult:
+    """
+    Result returned by a plugin's setup_environment hook.
+
+    Attributes:
+        env: Environment variables to set (e.g., AWS_* variables)
+        note: Short, non-secret human-readable hint about what was configured
+        required: If True and hook fails, abort in strict mode
+    """
+
+    env: Mapping[str, str]  # e.g. AWS_* variables
+    note: Optional[str] = None  # short, non-secret human hint
+    required: bool = False  # if True and hook fails -> abort (in strict mode)
+
+
+class HookSpec:
+    """
+    Plugin hook specification.
+
+    Plugins should implement the methods defined here to provide startup hooks.
+    """
+
+    @hookspec
+    def setup_environment(self, *, ctx: HookContext) -> Optional[SetupResult]:
+        """
+        Prepare process environment for Prefect and its children.
+
+        This hook is called before Prefect CLI commands, workers, or agents
+        start their main work. It allows plugins to configure environment
+        variables, authenticate with external services, or perform other
+        setup tasks.
+
+        Args:
+            ctx: Context object with Prefect version, API URL, and logger factory
+
+        Returns:
+            SetupResult with environment variables to set, or None to indicate
+            no changes are needed.
+
+        Important:
+            - Must not print secrets or write sensitive data to disk by default
+            - Should be idempotent
+            - May be async or sync
+            - Exceptions are caught and logged unless required=True in strict mode
+        """

{prefect_client-3.4.24.dev3 → prefect_client-3.4.24.dev4}/src/prefect/events/cli/automations.py

@@ -2,6 +2,7 @@
 Command line interface for working with automations.
 """
 
+import asyncio
 import functools
 from pathlib import Path
 from typing import Any, Callable, Optional, Type
@@ -301,6 +302,7 @@ async def pause(
 async def delete(
     name: Optional[str] = typer.Argument(None, help="An automation's name"),
     id: Optional[str] = typer.Option(None, "--id", help="An automation's id"),
+    _all: bool = typer.Option(False, "--all", help="Delete all automations"),
 ):
     """Delete an automation.
 
@@ -311,9 +313,37 @@ async def delete(
     Examples:
         `$ prefect automation delete "my-automation"`
         `$ prefect automation delete --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
+        `$ prefect automation delete --all`
     """
 
     async with get_client() as client:
+        if _all:
+            if name is not None or id is not None:
+                exit_with_error(
+                    "Cannot provide an automation name or id when deleting all automations."
+                )
+            automations = await client.read_automations()
+            if len(automations) == 0:
+                exit_with_success("No automations found.")
+            if is_interactive() and not typer.confirm(
+                f"Are you sure you want to delete all {len(automations)} automations?",
+                default=False,
+            ):
+                exit_with_error("Deletion aborted.")
+
+            semaphore = asyncio.Semaphore(10)
+
+            async def limited_delete(automation_id):
+                async with semaphore:
+                    await client.delete_automation(automation_id)
+
+            await asyncio.gather(
+                *[limited_delete(automation.id) for automation in automations]
+            )
+
+            plural = "" if len(automations) == 1 else "s"
+            exit_with_success(f"Deleted {len(automations)} automation{plural}.")
+
         if not id and not name:
             exit_with_error("Please provide either a name or an id.")
 

{prefect_client-3.4.24.dev3 → prefect_client-3.4.24.dev4}/src/prefect/input/run_input.py

@@ -249,7 +249,10 @@ class BaseRunInput(pydantic.BaseModel):
         """
         fields: Dict[str, Any] = {}
         for key, value in kwargs.items():
-            fields[key] = (type(value), value)
+            original_field = cls.model_fields.get(key)
+            # Use the original field annotation if it exists, otherwise infer from value
+            field_type = original_field.annotation if original_field else type(value)
+            fields[key] = (field_type, value)
         model = pydantic.create_model(cls.__name__, **fields, __base__=cls)
 
         if description is not None:

prefect_client-3.4.24.dev4/src/prefect/settings/models/experiments.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from functools import partial
+from typing import Annotated, ClassVar, Union
+
+from pydantic import AliasChoices, AliasPath, BeforeValidator, Field
+from pydantic_settings import SettingsConfigDict
+
+from prefect.settings.base import PrefectBaseSettings, build_settings_config
+from prefect.types import validate_set_T_from_delim_string
+
+
+class PluginsSettings(PrefectBaseSettings):
+    """
+    Settings for configuring the experimental plugin system
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = build_settings_config(
+        ("experiments", "plugins")
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable the experimental plugin system.",
+    )
+
+    allow: Annotated[
+        Union[set[str], None],
+        BeforeValidator(partial(validate_set_T_from_delim_string, type_=str)),
+    ] = Field(
+        default=None,
+        description="Comma-separated list of plugin names to allow. If set, only these plugins will be loaded.",
+    )
+
+    deny: Annotated[
+        Union[set[str], None],
+        BeforeValidator(partial(validate_set_T_from_delim_string, type_=str)),
+    ] = Field(
+        default=None,
+        description="Comma-separated list of plugin names to deny. These plugins will not be loaded.",
+    )
+
+    setup_timeout_seconds: float = Field(
+        default=20.0,
+        description="Maximum time in seconds for all plugins to complete their setup hooks.",
+    )
+
+    strict: bool = Field(
+        default=False,
+        description="If True, exit if a required plugin fails during setup.",
+    )
+
+    safe_mode: bool = Field(
+        default=False,
+        description="If True, load plugins but do not execute their hooks. Useful for testing.",
+    )
+
+
+class ExperimentsSettings(PrefectBaseSettings):
+    """
+    Settings for configuring experimental features
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = build_settings_config(("experiments",))
+
+    warn: bool = Field(
+        default=True,
+        description="If `True`, warn on usage of experimental features.",
+        validation_alias=AliasChoices(
+            AliasPath("warn"), "prefect_experiments_warn", "prefect_experimental_warn"
+        ),
+    )
+
+    plugins: PluginsSettings = Field(
+        default_factory=PluginsSettings,
+        description="Settings for the experimental plugin system",
+    )