Coverage for /usr/local/lib/python3.12/site-packages/prefect/_experimental/plugins/spec.py: 100%
20 statements
« prev ^ index » next coverage.py v7.10.6, created at 2025-12-05 13:38 +0000
1"""
2Experimental plugin API specification.
4This module defines the hook specification and data structures for Prefect's
5experimental plugin system.
6"""
8from __future__ import annotations 1a
10import logging 1a
11from dataclasses import dataclass 1a
12from typing import Callable, Mapping, Optional 1a
14import pluggy 1a
16# Bump this when breaking the hook contract
17PREFECT_PLUGIN_API_VERSION = "0.1" 1a
19hookspec = pluggy.HookspecMarker("prefect-experimental") 1a
22@dataclass 1a
23class HookContext: 1a
24 """
25 Context provided to plugin hooks at startup.
27 Attributes:
28 prefect_version: The version of Prefect running
29 api_url: The configured Prefect API URL, if any
30 logger_factory: Factory function to create a stdlib logger for the plugin
31 """
33 prefect_version: str 1a
34 api_url: str | None 1a
35 # Logger factory returns a stdlib logger; plugins should use this.
36 logger_factory: Callable[[str], logging.Logger] 1a
37 # Future: async Prefect client getter, settings snapshot, etc.
40@dataclass 1a
41class SetupResult: 1a
42 """
43 Result returned by a plugin's setup_environment hook.
45 Attributes:
46 env: Environment variables to set (e.g., AWS_* variables)
47 note: Short, non-secret human-readable hint about what was configured
48 required: If True and hook fails, abort in strict mode
49 """
51 env: Mapping[str, str] # e.g. AWS_* variables 1a
52 note: Optional[str] = None # short, non-secret human hint 1a
53 required: bool = False # if True and hook fails -> abort (in strict mode) 1a
56class HookSpec: 1a
57 """
58 Plugin hook specification.
60 Plugins should implement the methods defined here to provide startup hooks.
61 """
63 @hookspec 1a
64 def setup_environment(self, *, ctx: HookContext) -> Optional[SetupResult]: 1a
65 """
66 Prepare process environment for Prefect and its children.
68 This hook is called before Prefect CLI commands, workers, or agents
69 start their main work. It allows plugins to configure environment
70 variables, authenticate with external services, or perform other
71 setup tasks.
73 Args:
74 ctx: Context object with Prefect version, API URL, and logger factory
76 Returns:
77 SetupResult with environment variables to set, or None to indicate
78 no changes are needed.
80 Important:
81 - Must not print secrets or write sensitive data to disk by default
82 - Should be idempotent
83 - May be async or sync
84 - Exceptions are caught and logged unless required=True in strict mode
85 """