bricks-py 0.2.1__tar.gz → 0.2.2__tar.gz

{bricks_py-0.2.1 → bricks_py-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bricks-py
-Version: 0.2.1
+Version: 0.2.2
 Summary: quickly build your crawler
 Project-URL: Homepage, https://github.com/KKKKKKKEM/bricks
 Project-URL: Repository, https://github.com/KKKKKKKEM/bricks.git

{bricks_py-0.2.1 → bricks_py-0.2.2}/bricks/core/events.py

@@ -78,6 +78,70 @@ class Task:
     match_code: Optional[object] = None  # lazily-compiled eval code object for str matches
 
 
+@dataclass
+class EventSpec:
+    """声明式钩子元数据，由 @events.on() 附加到装饰的方法上。
+
+    与 Task 不同，EventSpec 不引用实际的可调用对象；它只保存 *声明* 参数。
+    可调用对象在实例创建时由 Pangu._install_events() 解析和绑定。
+    """
+    form: str
+    index: Optional[int] = None
+    disposable: bool = False
+    args: Optional[list] = None
+    kwargs: Optional[dict] = None
+    match: Optional[Union[Callable, str]] = None
+
+
+# ------------------------------------------------------------------ #
+# EventSpec helpers - attach / read metadata on functions & descriptors
+# ------------------------------------------------------------------ #
+
+_EVENT_SPEC_ATTR = "__event_spec__"  # Backward-compatible single-spec view.
+_EVENT_SPECS_ATTR = "__event_specs__"
+
+
+def _set_event_spec(func, spec: EventSpec):
+    """将 EventSpec 附加到普通函数上，允许一个方法声明多个 hook。"""
+    specs = list(getattr(func, _EVENT_SPECS_ATTR, ()))
+    legacy_spec = getattr(func, _EVENT_SPEC_ATTR, None)
+    if legacy_spec is not None and legacy_spec not in specs:
+        specs.insert(0, legacy_spec)
+    specs.append(spec)
+    setattr(func, _EVENT_SPECS_ATTR, specs)
+    setattr(func, _EVENT_SPEC_ATTR, spec)
+
+
+def _get_event_spec(obj) -> Optional[EventSpec]:
+    """从函数或描述符 (staticmethod / classmethod) 上读取最后声明的 EventSpec。"""
+    if isinstance(obj, (staticmethod, classmethod)):
+        return getattr(obj.__func__, _EVENT_SPEC_ATTR, None)
+    return getattr(obj, _EVENT_SPEC_ATTR, None)
+
+
+def _get_event_specs(obj) -> List[EventSpec]:
+    """从函数或描述符上读取全部 EventSpec 元数据。"""
+    if isinstance(obj, (staticmethod, classmethod)):
+        obj = obj.__func__
+    specs = getattr(obj, _EVENT_SPECS_ATTR, None)
+    if specs:
+        return list(specs)
+    spec = getattr(obj, _EVENT_SPEC_ATTR, None)
+    return [spec] if spec is not None else []
+
+
+def _has_event_spec(obj) -> bool:
+    """检查函数或描述符是否携带 EventSpec 元数据。"""
+    return bool(_get_event_specs(obj))
+
+
+def _get_event_legacy(obj):
+    """从函数或描述符上读取旧版 __event__ 元数据，用于向后兼容。"""
+    if isinstance(obj, (staticmethod, classmethod)):
+        return getattr(obj.__func__, "__event__", None)
+    return getattr(obj, "__event__", None)
+
+
 @dataclass
 class Register:
     """事件注册信息
@@ -417,9 +481,25 @@ def on(
         match: Optional[Union[Callable, str]] = None,
 ):
     """
-    使用装饰器的方式注册事件
+    使用装饰器的方式注册事件 / 声明事件元数据
+
+    行为取决于被装饰对象的位置:
+
+    * **模块级 / 局部函数** — 立即以 ``target=None`` 全局注册（行为与旧版一致）。
+    * **类方法 / 静态方法 / 类方法描述符** — 仅附加 ``EventSpec`` 元数据，
+      由 ``Pangu._install_events()`` 在实例化时绑定并注册。
+
+    支持两种装饰器顺序::
 
-    注意：如果使用 @staticmethod 等装饰器，@on 应该放在最内层（紧贴函数定义）
+        # 推荐：@events.on 在最内层
+        @staticmethod
+        @events.on("my_event")
+        def handler(context): ...
+
+        # 也支持：@events.on 在最外层
+        @events.on("my_event")
+        @staticmethod
+        def handler(context): ...
 
     :param form: 事件类型，可以传入常量属性
     :param index: 事件排序索引，默认按代码顺序递增，索引越大越靠后执行
@@ -434,21 +514,36 @@ def on(
         def my_handler(context):
             print("Request starting")
     """
+    spec = EventSpec(
+        form=form,
+        index=index,
+        disposable=disposable,
+        args=args,
+        kwargs=kwargs,
+        match=match,
+    )
 
     def inner(func):
-        e = Task(
-            func=func,
-            index=index,
-            disposable=disposable,
-            args=args,
-            kwargs=kwargs,
-            match=match,
-        )
-
-        if "." not in func.__qualname__ or "<locals>" in func.__qualname__:
+        # 提取底层函数以检查 qualname（兼容 staticmethod / classmethod 描述符）
+        if isinstance(func, (staticmethod, classmethod)):
+            actual_func = func.__func__
+        else:
+            actual_func = func
+
+        # 模块级函数或局部函数：立即全局注册
+        if "." not in actual_func.__qualname__ or "<locals>" in actual_func.__qualname__:
+            e = Task(
+                func=actual_func,
+                index=index,
+                disposable=disposable,
+                args=args,
+                kwargs=kwargs,
+                match=match,
+            )
             EventManager.register(Context(form=form, target=None), e)
         else:
-            setattr(func, "__event__", (form, e))
+            # 类方法：仅声明元数据，延迟到实例化时绑定注册
+            _set_event_spec(actual_func, spec)
 
         return func
 

{bricks_py-0.2.1 → bricks_py-0.2.2}/bricks/core/genesis.py

@@ -10,7 +10,15 @@ from loguru import logger
 
 from bricks.core import dispatch, signals
 from bricks.core.context import Context, Error, Flow
-from bricks.core.events import REGISTERED_EVENTS, EventManager, Register, Task
+from bricks.core.events import (
+    REGISTERED_EVENTS,
+    EventManager,
+    EventSpec,
+    Register,
+    Task,
+    _get_event_legacy,
+    _get_event_specs,
+)
 from bricks.state import const
 from bricks.utils import pandora
 from bricks.utils.scheduler import BaseTrigger, Scheduler
@@ -20,8 +28,6 @@ class MetaClass(type):
     def __call__(cls, *args, **kwargs):
         instance = type.__call__(cls, *args, **kwargs)
 
-        registed_evets = []
-
         # 加载拦截器
         for method in dir(instance):
             # 修改被拦截的方法
@@ -35,19 +41,14 @@ class MetaClass(type):
                 raw_method and setattr(
                     instance, raw_method_name, method_wrapper(raw_method)
                 )  # type: ignore
-            else:
-                func = getattr(instance, method, None)
-                if not func or not callable(func):
-                    continue
-
-                if hasattr(func, "__event__"):
-                    registed_evets.append(func.__event__)
 
-        else:
-            hasattr(instance, "install") and instance.install()  # type: ignore
+        # 安装 @events.on 装饰的事件钩子（仅事件能力实例，如 Pangu）
+        if hasattr(instance, "_install_events"):
+            instance._install_events()
 
-        for event in registed_evets:
-            instance.use(*event)
+        # 运行生命周期 install
+        if hasattr(instance, "install"):
+            instance.install()
 
         return instance
 
@@ -210,6 +211,62 @@ class Pangu(Chaos):
                 options=self.get("dispatcher.options", default={}),
             )
 
+    def _install_events(self):
+        """扫描 MRO 类层次中 @events.on 装饰的方法并注册为事件钩子。
+
+        处理实例方法、staticmethod 和 classmethod 描述符。
+        继承的钩子只注册一次；如果子类重写了同名方法（无论是否装饰），
+        只使用子类的版本。
+
+        支持单个方法声明多个 @events.on() 装饰器，每个 form 均会独立注册。
+        """
+        seen = set()
+
+        for klass in type(self).__mro__:
+            for name, value in klass.__dict__.items():
+                if name in seen:
+                    continue
+                seen.add(name)
+
+                specs = _get_event_specs(value)
+
+                # 向后兼容：检查旧版 __event__ 格式
+                if not specs:
+                    event_val = _get_event_legacy(value)
+                    if event_val is not None:
+                        try:
+                            old_form, old_task = event_val
+                            specs = [EventSpec(
+                                form=old_form,
+                                index=getattr(old_task, "index", None),
+                                disposable=getattr(old_task, "disposable", False),
+                                args=getattr(old_task, "args", None),
+                                kwargs=getattr(old_task, "kwargs", None),
+                                match=getattr(old_task, "match", None),
+                            )]
+                        except (ValueError, TypeError):
+                            pass
+
+                if not specs:
+                    continue
+
+                # 通过 getattr 获取绑定的可调用对象（自动处理所有描述符类型）
+                try:
+                    bound = getattr(self, name)
+                except AttributeError:
+                    continue
+
+                for spec in specs:
+                    task = Task(
+                        func=bound,
+                        index=spec.index,
+                        disposable=spec.disposable,
+                        args=spec.args,
+                        kwargs=spec.kwargs,
+                        match=spec.match,
+                    )
+                    self.use(spec.form, task)
+
     @property
     def plugins(self) -> List[Register]:
         return REGISTERED_EVENTS.registered[self]  # type: ignore

{bricks_py-0.2.1 → bricks_py-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bricks-py"
-version = "0.2.1"
+version = "0.2.2"
 description = "quickly build your crawler"
 readme = "README.md"
 license = { text = "MIT" }