prefect 3.4.24.dev2__tar.gz → 3.4.24.dev4__tar.gz

{prefect-3.4.24.dev2 → prefect-3.4.24.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect
-Version: 3.4.24.dev2
+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
@@ -52,6 +52,7 @@ Requires-Dist: orjson<4.0,>=3.7
 Requires-Dist: packaging<25.1,>=21.3
 Requires-Dist: pathspec>=0.8.0
 Requires-Dist: pendulum<4,>=3.0.0; python_version < '3.13'
+Requires-Dist: pluggy>=1.6.0
 Requires-Dist: prometheus-client>=0.20.0
 Requires-Dist: pydantic!=2.11.0,!=2.11.1,!=2.11.2,!=2.11.3,!=2.11.4,<3.0.0,>=2.10.1
 Requires-Dist: pydantic-core<3.0.0,>=2.12.0
@@ -59,7 +60,6 @@ Requires-Dist: pydantic-extra-types<3.0.0,>=2.8.2
 Requires-Dist: pydantic-settings!=2.9.0,<3.0.0,>2.2.1
 Requires-Dist: python-dateutil<3.0.0,>=2.8.2
 Requires-Dist: python-slugify<9.0,>=5.0
-Requires-Dist: python-socks[asyncio]<3.0,>=2.5.3
 Requires-Dist: pytz<2026,>=2021.1
 Requires-Dist: pyyaml<7.0.0,>=5.4.1
 Requires-Dist: readchar<5.0.0,>=4.0.0
@@ -74,7 +74,7 @@ Requires-Dist: typer!=0.12.2,<0.20.0,>=0.12.0
 Requires-Dist: typing-extensions<5.0.0,>=4.10.0
 Requires-Dist: uv>=0.6.0
 Requires-Dist: uvicorn!=0.29.0,>=0.14.0
-Requires-Dist: websockets<16.0,>=13.0
+Requires-Dist: websockets<16.0,>=15.0.1
 Requires-Dist: whenever<0.10.0,>=0.7.3; python_version >= '3.13'
 Provides-Extra: aws
 Requires-Dist: prefect-aws>=0.5.8; extra == 'aws'

{prefect-3.4.24.dev2 → prefect-3.4.24.dev4}/pyproject.toml

@@ -69,7 +69,6 @@ dependencies = [
     "pydantic_settings>2.2.1,<3.0.0,!=2.9.0",
     "python-dateutil>=2.8.2,<3.0.0",
     "python-slugify>=5.0,<9.0",
-    "python-socks[asyncio]>=2.5.3,<3.0",
     "pyyaml>=5.4.1,<7.0.0",
     "rfc3339-validator>=0.1.4,<0.2.0",
     "rich>=11.0,<15.0",
@@ -78,10 +77,11 @@ dependencies = [
     "toml>=0.10.0",
     "typing_extensions>=4.10.0,<5.0.0",
     "uvicorn>=0.14.0,!=0.29.0",
-    "websockets>=13.0,<16.0",
+    "websockets>=15.0.1,<16.0",
     "whenever>=0.7.3,<0.10.0; python_version>='3.13'",
     "uv>=0.6.0",
     "semver>=3.0.4",
+    "pluggy>=1.6.0",
 ]
 [project.urls]
 Changelog = "https://github.com/PrefectHQ/prefect/releases"

{prefect-3.4.24.dev2 → prefect-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-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:44.434596+00:00"
+__git_commit__ = "4d7bea0be73f046c90a05a964312a8e86261e17d"
+__dirty__ = False

prefect-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-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-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-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-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-3.4.24.dev4/src/prefect/_internal/websockets.py

@@ -0,0 +1,88 @@
+"""
+Internal WebSocket proxy utilities for Prefect client connections.
+
+This module provides shared WebSocket proxy connection logic and SSL configuration
+to avoid duplication between events and logs clients.
+"""
+
+import ssl
+import warnings
+from functools import wraps
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+import certifi
+from websockets.asyncio.client import connect
+
+from prefect.settings import get_current_settings
+
+
+def create_ssl_context_for_websocket(uri: str) -> Optional[ssl.SSLContext]:
+    """Create SSL context for WebSocket connections based on URI scheme."""
+    u = urlparse(uri)
+
+    if u.scheme != "wss":
+        return None
+
+    if get_current_settings().api.tls_insecure_skip_verify:
+        # Create an unverified context for insecure connections
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        return ctx
+    else:
+        # Create a verified context with the certificate file
+        cert_file = get_current_settings().api.ssl_cert_file
+        if not cert_file:
+            cert_file = certifi.where()
+        return ssl.create_default_context(cafile=cert_file)
+
+
+@wraps(connect)
+def websocket_connect(uri: str, **kwargs: Any) -> connect:
+    """
+    Create a WebSocket connection with proxy and SSL support.
+
+    Proxy support is automatic via HTTP_PROXY/HTTPS_PROXY environment variables.
+    The websockets library handles proxy detection and connection automatically.
+    """
+    # Configure SSL context for HTTPS connections
+    ssl_context = create_ssl_context_for_websocket(uri)
+    if ssl_context:
+        kwargs.setdefault("ssl", ssl_context)
+
+    # Add custom headers from settings
+    custom_headers = get_current_settings().client.custom_headers
+    if custom_headers:
+        # Get existing additional_headers or create new dict
+        additional_headers = kwargs.get("additional_headers", {})
+        if not isinstance(additional_headers, dict):
+            additional_headers = {}
+
+        for header_name, header_value in custom_headers.items():
+            # Check for protected headers that shouldn't be overridden
+            if header_name.lower() in {
+                "user-agent",
+                "sec-websocket-key",
+                "sec-websocket-version",
+                "sec-websocket-extensions",
+                "sec-websocket-protocol",
+                "connection",
+                "upgrade",
+                "host",
+            }:
+                warnings.warn(
+                    f"Custom header '{header_name}' is ignored because it conflicts with "
+                    f"a protected WebSocket header. Protected headers include: "
+                    f"User-Agent, Sec-WebSocket-Key, Sec-WebSocket-Version, "
+                    f"Sec-WebSocket-Extensions, Sec-WebSocket-Protocol, Connection, "
+                    f"Upgrade, Host",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            else:
+                additional_headers[header_name] = header_value
+
+        kwargs["additional_headers"] = additional_headers
+
+    return connect(uri, **kwargs)

{prefect-3.4.24.dev2 → prefect-3.4.24.dev4}/src/prefect/cli/__init__.py

@@ -18,6 +18,7 @@ import prefect.cli.deploy
 import prefect.cli.deployment
 import prefect.cli.dev
 import prefect.cli.events
+import prefect.cli.experimental
 import prefect.cli.flow
 import prefect.cli.flow_run
 import prefect.cli.global_concurrency_limit