canary-framework 0.1.0__py3-none-any.whl

canary_framework/__init__.py

@@ -0,0 +1,31 @@
+"""CF 框架 —— 轻量级 Python 服务框架。
+
+核心导出:
+    - 装饰器: config, service, module, on_init, on_start, on_end
+    - 引擎:   Canary, Context
+"""
+
+__version__ = "0.1.0"
+
+from canary_framework.core import (
+    Canary,
+    Context,
+    config,
+    module,
+    on_end,
+    on_init,
+    on_start,
+    service,
+)
+
+__all__ = [
+    "Canary",
+    "Context",
+    "config",
+    "module",
+    "on_end",
+    "on_init",
+    "on_start",
+    "service",
+    "__version__",
+]

canary_framework/core/__init__.py

@@ -0,0 +1,24 @@
+"""CF 核心模块 —— 装饰器、引擎、注册中心和工具函数。
+
+公开 API:
+    - 装饰器:   config, service, module, on_init, on_start, on_end
+    - 引擎类:   Canary, Context
+"""
+
+from canary_framework.core.decorators.config import config
+from canary_framework.core.decorators.lifecycle import on_end, on_init, on_start
+from canary_framework.core.decorators.module import module
+from canary_framework.core.decorators.service import service
+from canary_framework.core.engine.canary import Canary
+from canary_framework.core.engine.context import Context
+
+__all__ = [
+    "config",
+    "service",
+    "module",
+    "on_init",
+    "on_start",
+    "on_end",
+    "Canary",
+    "Context",
+]

canary_framework/core/decorators/__init__.py

@@ -0,0 +1 @@
+

canary_framework/core/decorators/config.py

@@ -0,0 +1,58 @@
+"""@config 装饰器 —— 将普通类转换为 pydantic-settings BaseSettings 子类。
+
+转换后的类自动读取环境变量和 .env 文件（内置 env_file=".env"）。
+配置字段优先级: 环境变量 > .env 文件 > 默认值。
+
+Usage:
+    @config
+    class AppConfig:
+        host: str = "0.0.0.0"
+        port: int = 8000
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def config(cls: type) -> type:
+    """将普通类转为 BaseSettings 子类，使其具备自动配置加载能力。
+
+    动态创建逻辑:
+        1. 提取原始类的 __annotations__ 作为 pydantic 的字段声明
+        2. 提取原始类的类变量作为字段默认值
+        3. SettingsConfigDict(env_file=".env") 让 pydantic-settings 自动读取 .env
+        4. 用 type() 动态构造新类，保持原始类的 __name__ / __qualname__ / __module__
+
+    参数可以是无括号装饰器 @config 或有括号 @config()，效果相同。
+    """
+    # 提取用户定义的类型注解（pydantic 按此推断字段类型和环境变量映射）
+    annotations = getattr(cls, "__annotations__", {})
+
+    settings_cls = type(
+        cls.__name__,
+        (BaseSettings,),
+        {
+            "__annotations__": annotations,
+            # BaseSettings 的行为配置
+            "model_config": SettingsConfigDict(
+                env_file=".env",  # 自动从当前目录 .env 读取
+                env_file_encoding="utf-8",
+                extra="ignore",  # 忽略未声明的环境变量
+                env_prefix="",  # 无前缀，字段名直接对应环境变量键
+            ),
+            # 将原始类的类变量（默认值）复制到新类
+            **{
+                k: v
+                for k, v in vars(cls).items()
+                if not k.startswith("__") and k != "__annotations__"
+            },
+        },
+    )
+
+    # 保持元信息一致，方便调试和日志
+    settings_cls.__name__ = cls.__name__
+    settings_cls.__qualname__ = cls.__qualname__
+    settings_cls.__module__ = cls.__module__
+
+    return settings_cls

canary_framework/core/decorators/lifecycle.py

@@ -0,0 +1,86 @@
+"""生命周期钩子装饰器 —— @on_init / @on_start / @on_end。
+
+用于标记服务/模块类中的方法为生命周期钩子，框架在对应阶段自动查找并调用。
+钩子方法可以是 sync 或 async，框架通过 asyncio.iscoroutine 自动适配。
+
+三个阶段:
+    on_init(ctx)  — 初始化: 依赖已注入、配置已加载，接收 Context。
+    on_start()    — 启动: 无参数。
+    on_end()      — 停止: 无参数，按启动逆序调用。
+
+find_hooks 查找策略:
+    1. 优先查找被装饰器标记的方法（检查 __cf_on_init__ 等属性）
+    2. 回退: 按方法名 on_init / on_start / on_end 直接匹配
+    3. 以上均未找到 → 该阶段钩子为 None
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+_CF_ON_INIT = "__cf_on_init__"  # 标记: 初始化钩子
+_CF_ON_START = "__cf_on_start__"  # 标记: 启动钩子
+_CF_ON_END = "__cf_on_end__"  # 标记: 停止钩子
+
+
+def on_init(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """标记方法为 on_init 钩子。框架在其 init 阶段调用，传入 Context。"""
+    setattr(fn, _CF_ON_INIT, True)
+    return fn
+
+
+def on_start(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """标记方法为 on_start 钩子。框架在其 start 阶段调用，无参数。"""
+    setattr(fn, _CF_ON_START, True)
+    return fn
+
+
+def on_end(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """标记方法为 on_end 钩子。框架在其 stop 阶段按逆序调用，无参数。"""
+    setattr(fn, _CF_ON_END, True)
+    return fn
+
+
+def find_hooks(instance: object) -> dict[str, Callable[..., Any] | None]:
+    """在服务/模块实例上查找所有生命周期钩子方法。
+
+    两步查找:
+        1. 遍历 dir(instance)，通过 __cf_on_init__ 等标记属性匹配装饰的方法。
+        2. 回退: 未被装饰但方法名为 on_init/on_start/on_end 的也视作钩子。
+
+    Args:
+        instance: 服务或模块的类实例。
+
+    Returns:
+        {"on_init": method | None, "on_start": method | None, "on_end": method | None}
+        未找到的钩子对应值为 None。
+    """
+    hooks: dict[str, Callable[..., Any] | None] = {
+        "on_init": None,
+        "on_start": None,
+        "on_end": None,
+    }
+
+    # 第一步: 检查装饰器标记
+    for attr_name in dir(instance):
+        try:
+            attr = getattr(instance, attr_name)
+        except Exception:
+            continue
+        if not callable(attr):
+            continue
+
+        if getattr(attr, _CF_ON_INIT, False):
+            hooks["on_init"] = attr
+        elif getattr(attr, _CF_ON_START, False):
+            hooks["on_start"] = attr
+        elif getattr(attr, _CF_ON_END, False):
+            hooks["on_end"] = attr
+
+    # 第二步: 回退 —— 未标记但恰好名称为钩子名的方法
+    for key in ("on_init", "on_start", "on_end"):
+        if hooks[key] is None:
+            hooks[key] = getattr(instance, key, None)
+
+    return hooks

canary_framework/core/decorators/module.py

@@ -0,0 +1,66 @@
+"""模块装饰器 —— 将类声明为 CF 框架的模块（服务的组合容器）。
+
+模块本身也是服务，支持配置、生命周期钩子。额外的能力是声明 services 子节点列表。
+子服务/子模块通过 services 参数以类列表的形式注册到当前模块。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from canary_framework.core.decorators.service import is_cf_service
+
+_CF_MODULE_ATTR = "_cf_module__"  # 标记: 属于 CF 模块
+_CF_MODULE_META = "_cf_module_meta__"  # 存储: 元数据字典
+
+
+def module(
+    name: str,  # 模块名称，全局唯一
+    *,
+    config: type | None = None,  # 模块配置类（可选，子服务可继承）
+    services: list[type] | None = None,  # 子服务和子模块类列表（可选）
+):
+    """将类声明为 CF 框架的模块。
+
+    在类上设置 _cf_module__ = True 标记和 _cf_module_meta__ 元数据字典。
+    框架在 _collect 阶段识别并递归处理其 services 子节点。
+
+    Args:
+        name: 模块名称，全局唯一。
+        config: @config 装饰的配置类。子服务未声明 config 时继承此配置。
+        services: 子服务和子模块的类列表，每个必须被 @service 或 @module 装饰。
+
+    Raises:
+        TypeError: services 列表中存在未被 @service 或 @module 装饰的类。
+
+    Returns:
+        内层装饰器函数。
+    """
+    _config = config
+    _services = services or []
+
+    def decorator(cls: type) -> type:
+        # 校验子节点合法性
+        for svc_cls in _services:
+            if not is_cf_service(svc_cls) and not is_cf_module(svc_cls):
+                raise TypeError(
+                    f"@module '{name}': '{svc_cls.__name__}' is not a @service or @module class."
+                )
+
+        meta = {"name": name, "config_cls": _config, "services": _services}
+        setattr(cls, _CF_MODULE_ATTR, True)
+        setattr(cls, _CF_MODULE_META, meta)
+        cls.__cf_name__ = name  # type: ignore[attr-defined]
+        return cls
+
+    return decorator
+
+
+def is_cf_module(cls: type) -> bool:
+    """判断类是否被 @module 装饰过。"""
+    return bool(getattr(cls, _CF_MODULE_ATTR, False))
+
+
+def get_module_meta(cls: type) -> dict[str, Any]:
+    """获取 @module 装饰器设置的元数据字典。"""
+    return getattr(cls, _CF_MODULE_META, {})

canary_framework/core/decorators/service.py

@@ -0,0 +1,54 @@
+"""服务装饰器 —— 将类声明为 CF 框架的服务（最小运行单元）。
+
+服务通过 name 标识自身，通过 deps 声明依赖关系。
+依赖的服务实例由框架自动注入为 snake_case 属性名。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_CF_SERVICE_ATTR = "__cf_service__"  # 标记: 属于 CF 服务
+_CF_SERVICE_META = "__cf_service_meta__"  # 存储: 元数据字典
+
+
+def service(
+    name: str,  # 服务名称，全局唯一
+    *,
+    config: type | None = None,  # @config 装饰的配置类（可选）
+    deps: list[type] | None = None,  # 依赖的服务类列表（可选）
+):
+    """将类声明为 CF 框架的服务。
+
+    在类上设置 __cf_service__ = True 标记和 __cf_service_meta__ 元数据字典。
+    框架在 _collect 阶段识别这些标记并注册该服务。
+
+    Args:
+        name: 服务名称，全局唯一，用于依赖声明和名称索引。
+        config: @config 装饰的配置类，None 时从父模块继承。
+        deps: 依赖的服务类列表，框架自动将其实例注入为 snake_case 属性。
+
+    Returns:
+        内层装饰器函数。
+    """
+    _config = config
+    _deps = deps or []
+
+    def decorator(cls: type) -> type:
+        meta = {"name": name, "deps": _deps, "config_cls": _config}
+        setattr(cls, _CF_SERVICE_ATTR, True)
+        setattr(cls, _CF_SERVICE_META, meta)
+        cls.__cf_name__ = name  # type: ignore[attr-defined]
+        return cls
+
+    return decorator
+
+
+def is_cf_service(cls: type) -> bool:
+    """判断类是否被 @service 装饰过。"""
+    return bool(getattr(cls, _CF_SERVICE_ATTR, False))
+
+
+def get_service_meta(cls: type) -> dict[str, Any]:
+    """获取 @service 装饰器设置的元数据字典。"""
+    return getattr(cls, _CF_SERVICE_META, {})

canary_framework/core/engine/canary.py

@@ -0,0 +1,287 @@
+"""CF 框架核心引擎 —— 生命周期编排器。
+
+负责服务的递归发现、依赖校验、拓扑排序、Context 树构建和生命周期钩子调度。
+通过 Canary 和 WebCanary 两个公开类暴露给用户。
+
+日志系统:
+    框架使用 "cf" 命名空间的 logger，通过 CF_LOG_LEVEL 环境变量控制级别（默认 INFO）。
+    日志格式: [CF] [LEVEL] [module] message
+    与 uvicorn 日志隔离（不同的 logger 名称），不会重复输出。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from canary_framework.core.decorators.lifecycle import find_hooks
+from canary_framework.core.decorators.module import get_module_meta, is_cf_module
+from canary_framework.core.decorators.service import get_service_meta, is_cf_service
+from canary_framework.core.engine.context import Context
+from canary_framework.core.engine.injector import inject_deps
+from canary_framework.core.engine.sorter import topological_sort
+from canary_framework.core.registry.registry import Registry, ServiceEntry
+
+# 框架日志系统
+# 格式 [CF] [LEVEL] [模块] 消息，与 uvicorn 的 root logger 完全隔离（cf 命名空间）
+_cf_logger = logging.getLogger("cf")
+
+
+def _init_logging() -> None:
+    """初始化框架日志：从 CF_LOG_LEVEL 环境变量读取级别，配置格式和 handler。
+
+    只会配置一次（幂等），避免重复添加 handler。
+    logger.propagate = False 确保日志不传播到 root logger，不与 uvicorn 冲突。
+    """
+    level_name = os.environ.get("CF_LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+    _cf_logger.setLevel(level)
+
+    # 幂等：已经配置过 handler 则跳过
+    if _cf_logger.handlers:
+        return
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("[CF] [%(levelname)-5s] [%(name)s] %(message)s"))
+    _cf_logger.addHandler(handler)
+    # 禁止向 root logger 传播，避免 uvicorn 或其他库的 root handler 重复打印
+    _cf_logger.propagate = False
+
+    _cf_logger.debug("Logging initialized at level=%s", level_name)
+
+
+def _get_logger(name: str) -> logging.Logger:
+    """获取 cf 命名空间下的子 logger，如 cf.engine、cf.di、cf.config。"""
+    return logging.getLogger(f"cf.{name}")
+
+
+class Canary:
+    """Canary 核心引擎 —— 服务生命周期编排器。
+
+    负责完整的应用生命周期:
+        init()  → 收集 → 校验 → 拓扑排序 → Context 树 → DI → 配置 → on_init
+        start() → 按拓扑序触发 on_start
+        stop()  → 按逆序触发 on_end
+
+    Usage:
+        app = Canary(MyRootModule)
+        await app.init()
+        await app.start()
+        await app.stop()
+    """
+
+    def __init__(self, target: type) -> None:
+        self._target = target  # 根模块/服务类（入口点）
+        self._registry = Registry()  # 全局注册中心
+        self._startup_order: list[str] = []  # 拓扑排序后的名称列表
+
+    @property
+    def registry(self) -> Registry:
+        """公开 Registry，供子类（WebCanary）和测试访问。"""
+        return self._registry
+
+    # ── 公开生命周期方法 ─────────────────────────────────
+
+    async def init(self) -> None:
+        """初始化阶段：收集服务、校验依赖、构建 Context、注入、加载配置、调 on_init。
+
+        四阶段流程:
+            0. _collect()      — 递归发现并注册所有 @service / @module 类
+            1. _validate()     — 校验 deps 中声明的依赖完整性
+            2. topological_sort() — Kahn 算法计算启动顺序
+            3. _build_context_tree() — 按模块树建立 Context parent 链
+            4. 按拓扑序: 依赖注入 → 配置加载 → on_init(ctx)
+        """
+        _init_logging()
+        engine = _get_logger("engine")
+        engine.info("── init start ──")
+
+        # ── 阶段0: 收集 ──
+        engine.debug("Phase 0: collecting services/modules")
+        self._collect(self._target)
+
+        # ── 阶段1: 校验 ──
+        engine.debug("Phase 1: validating dependencies")
+        self._validate()
+
+        # ── 阶段2: 拓扑排序 ──
+        engine.debug("Phase 2: topological sort")
+        self._startup_order = topological_sort(self._registry)
+        engine.info(
+            "Startup order (%d): %s", len(self._startup_order), " → ".join(self._startup_order)
+        )
+
+        # ── 阶段3: 构建 Context 链 ──
+        engine.debug("Phase 3: building context tree")
+        self._build_context_tree(self._target, parent_ctx=None)
+
+        # ── 阶段4: 逐个初始化 ──
+        engine.debug("Phase 4: initializing entries")
+        for name in self._startup_order:
+            entry = self._registry.get_by_name(name)
+            await self._init_entry(entry)
+
+        engine.info("── init complete (%d services) ──", len(self._startup_order))
+
+    async def start(self) -> None:
+        """启动阶段：按拓扑序触发所有服务的 on_start 钩子。"""
+        engine = _get_logger("engine")
+        engine.info("── start ──")
+        for name in self._startup_order:
+            entry = self._registry.get_by_name(name)
+            await self._call_hook(entry, "on_start")
+        engine.info("── start complete ──")
+
+    async def stop(self) -> None:
+        """停止阶段：按逆序触发所有服务的 on_end 钩子。"""
+        engine = _get_logger("engine")
+        engine.info("── stop ──")
+        for name in reversed(self._startup_order):
+            entry = self._registry.get_by_name(name)
+            await self._call_hook(entry, "on_end")
+        engine.info("── stop complete ──")
+
+    # ── _init_entry: 单个 entry 的初始化 ──────────────────
+
+    async def _init_entry(self, entry: ServiceEntry) -> None:
+        """对单个注册项执行: 依赖注入 → 配置加载 → 触发 on_init 钩子。"""
+        engine = _get_logger("engine")
+        config_log = _get_logger("config")
+
+        engine.info("  init %s", entry.name)
+
+        # 依赖注入
+        inject_deps(entry.instance, entry, self._registry)
+
+        # 配置加载
+        if entry.config_cls is not None:
+            entry.config_instance = entry.config_cls()
+            config_log.info(
+                "  %s config loaded: %s",
+                entry.name,
+                {k: v for k, v in vars(entry.config_instance).items() if not k.startswith("_")},
+            )
+        else:
+            config_log.debug("  %s has no config", entry.name)
+
+        # on_init 钩子
+        await self._call_hook(entry, "on_init", entry.context)
+
+    # ── _call_hook ─────────────────────────────────────────
+
+    @staticmethod
+    async def _call_hook(entry: ServiceEntry, hook_name: str, *args: object) -> None:
+        """统一钩子调用（sync / async 自动适配）。
+
+        钩子查找结果缓存在 entry._hooks 上，每个 entry 仅扫描一次 dir(instance)。
+        asyncio.iscoroutine 判断方法返回值是否为协程，是则 await。
+        """
+        lifecycle = _get_logger("lifecycle")
+        if entry._hooks is None:
+            entry._hooks = find_hooks(entry.instance)
+        fn = entry._hooks.get(hook_name)
+        if fn is None:
+            lifecycle.debug("  %s.%s: not defined", entry.name, hook_name)
+            return
+        lifecycle.info("  %s.%s()", entry.name, hook_name)
+        result = fn(*args)
+        if asyncio.iscoroutine(result):
+            await result
+
+    # ── _collect ─────────────────────────────────────────
+
+    def _collect(
+        self,
+        cls: type,
+        parent_entry: ServiceEntry | None = None,
+    ) -> None:
+        """递归收集 @service / @module 类，注册到 Registry，建立父子关系。
+
+        对于模块，递归处理其 services 列表中的子节点。
+        对于服务，仅注册自身。
+        config_cls 继承: 子节点未声明 config → 从父模块拷贝。
+        """
+        if self._registry.has(cls):
+            return
+
+        registry_log = _get_logger("registry")
+
+        # 分支：模块
+        if is_cf_module(cls):
+            meta = get_module_meta(cls)
+            self._registry.register(cls, is_module=True, meta=meta)
+            entry = self._registry.get_by_class(cls)
+            entry.parent_entry = parent_entry
+            self._inherit_config(entry, parent_entry)
+
+            registry_log.info(
+                "  module %-30s config=%s  services=%d",
+                entry.name,
+                entry.config_cls.__name__ if entry.config_cls else "inherit",
+                len(meta.get("services", [])),
+            )
+            for sub_cls in meta.get("services", []):
+                self._collect(sub_cls, parent_entry=entry)
+            return
+
+        # 分支：服务
+        if is_cf_service(cls):
+            meta = get_service_meta(cls)
+            self._registry.register(cls, is_module=False, meta=meta)
+            entry = self._registry.get_by_class(cls)
+            entry.parent_entry = parent_entry
+            self._inherit_config(entry, parent_entry)
+
+            registry_log.info(
+                "  service %-30s config=%s  deps=%d",
+                entry.name,
+                entry.config_cls.__name__ if entry.config_cls else "inherit",
+                len(entry.deps),
+            )
+            return
+
+        raise TypeError(f"'{cls.__name__}' is not decorated with @service or @module")
+
+    def _inherit_config(self, entry: ServiceEntry, parent_entry: ServiceEntry | None) -> None:
+        """子节点未声明 config_cls 时，从父模块拷贝。"""
+        if entry.config_cls is None and parent_entry is not None:
+            entry.config_cls = parent_entry.config_cls
+
+    # ── _build_context_tree ──────────────────────────────
+
+    def _build_context_tree(
+        self,
+        cls: type,
+        parent_ctx: Context | None,
+    ) -> None:
+        """按模块树递归构建 Context parent 链。
+
+        每个 ServiceEntry 绑定一个 Context，根模块的 parent 为 None。
+        子服务的 parent 指向所属模块的 Context。
+        """
+        entry = self._registry.get_by_class(cls)
+        ctx = Context(entry=entry, parent=parent_ctx, registry=self._registry)
+        entry.context = ctx
+
+        if entry.is_module:
+            for sub_cls in entry.sub_services:
+                self._build_context_tree(sub_cls, parent_ctx=ctx)
+
+    # ── _validate ────────────────────────────────────────
+
+    def _validate(self) -> None:
+        """校验所有 deps 中声明的依赖是否都已注册。
+
+        遍历所有 ServiceEntry，检查 dep_names 中的每个名称是否在 Registry 中存在。
+        不存在时抛出 ValueError 并列出所有已注册名称。
+        """
+        all_names = set(self._registry.names())
+        for entry in self._registry.all_entries():
+            for dep_name in entry.dep_names:
+                if dep_name not in all_names:
+                    raise ValueError(
+                        f"Service '{entry.name}' depends on '{dep_name}', "
+                        f"but '{dep_name}' is not registered. "
+                        f"Registered: {sorted(all_names)}"
+                    )