chongming-plugins/example/global_var.py

"""Example 插件全局运行时状态 — 统一容器

约定:
  - 模块只做"声明默认值"，不产生任何导入期副作用
  - 所有值统一在 create_workers 中通过 set_global_var 显式写入
  - set_global_var 仅允许写入 _ALLOWED 白名单，拼写错误会立即抛错
  - require() 用于取"必须已初始化"的值，未初始化时抛清晰错误
"""
from typing import Any

from chongming_database import Database

# 允许写入的全局变量白名单（防止拼写错误静默创建无用的新变量）
_ALLOWED = frozenset({"db"})

# 显式声明所有运行时状态（默认 None，运行时由 create_workers 写入）
db: Database | None = None


def set_global_var(name: str, value: Any) -> None:
    """
    白名单校验版 setter — 设置模块级运行时状态。

    拼错变量名会立即抛 KeyError，而不是静默创建一个无用的新变量。

    Args:
        name: 必须在 _ALLOWED 白名单中的变量名
        value: 任意值
    """
    if name not in _ALLOWED:
        raise KeyError(
            f"global_var: 未知变量 '{name}'（允许: {sorted(_ALLOWED)}）"
        )
    globals()[name] = value


def require(name: str) -> Any:
    """
    获取必须已初始化的全局变量，未初始化时抛清晰错误。

    Args:
        name: 必须在 _ALLOWED 白名单中的变量名

    Returns:
        对应全局变量的值
    """
    if name not in _ALLOWED:
        raise KeyError(f"global_var: 未知变量 '{name}'（允许: {sorted(_ALLOWED)}）")
    value = globals().get(name)
    if value is None:
        raise RuntimeError(
            f"global_var: '{name}' 未初始化 —— 请确认插件 create_workers 已执行且配置正确"
        )
    return value


__all__ = sorted(_ALLOWED) + ["set_global_var", "require"]