flow_engine.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
  1. """
  2. flow_engine.py - Declarative annotated flow engine (based on DrissionPage native API)
  3. """
  4. import time
  5. from typing import Optional, Callable, Dict, Any, Type
  6. from core_types import BizLogicError
  7. def on(url: Optional[str] = None,
  8. title: Optional[str] = None,
  9. text: Optional[str] = None,
  10. ele: Optional[str] = None,
  11. not_ele: Optional[str] = None,
  12. predicate: Optional[Callable[['BaseFlow'], bool]] = None,
  13. priority: int = 100):
  14. """Main matching decorator: triggers method when page satisfies conditions (supports stacking for OR relationships)"""
  15. def decorator(func: Callable):
  16. rule_spec = {
  17. "url": url,
  18. "title": title,
  19. "text": text,
  20. "ele": ele,
  21. "not_ele": not_ele,
  22. "predicate": predicate,
  23. "priority": priority,
  24. "is_done": getattr(func, "_is_done", False),
  25. "fatal_msg": getattr(func, "_fatal_msg", None),
  26. "exception_cls": getattr(func, "_exception_cls", BizLogicError)
  27. }
  28. rules = getattr(func, "_flow_rules", None)
  29. if rules is None:
  30. rules = []
  31. func._flow_rules = rules
  32. rules.append(rule_spec)
  33. func._flow_rule = rule_spec
  34. return func
  35. return decorator
  36. def done(func: Callable):
  37. """Done state decorator: exits and marks flow successful upon execution"""
  38. func._is_done = True
  39. for r in getattr(func, "_flow_rules", []):
  40. r["is_done"] = True
  41. return func
  42. def fatal(error_msg: str, exception_cls: Type[Exception] = BizLogicError):
  43. """Fatal error decorator: aborts flow with an exception when matched"""
  44. def decorator(func: Callable):
  45. func._fatal_msg = error_msg
  46. func._exception_cls = exception_cls
  47. for r in getattr(func, "_flow_rules", []):
  48. r["fatal_msg"] = error_msg
  49. r["exception_cls"] = exception_cls
  50. return func
  51. return decorator
  52. def guard(url: Optional[str] = None,
  53. title: Optional[str] = None,
  54. text: Optional[str] = None,
  55. ele: Optional[str] = None,
  56. not_ele: Optional[str] = None,
  57. predicate: Optional[Callable[['BaseFlow'], bool]] = None,
  58. priority: int = 10):
  59. """High-priority exception guard decorator"""
  60. return on(url=url, title=title, text=text, ele=ele, not_ele=not_ele, predicate=predicate, priority=priority)
  61. class BaseFlow:
  62. """
  63. Lightweight annotated state machine driver engine.
  64. """
  65. def __init__(self,
  66. page,
  67. config: Optional[Dict[str, Any]] = None,
  68. context: Optional[Dict[str, Any]] = None,
  69. interval: float = 1.0,
  70. logger: Optional[Callable[[str], None]] = None,
  71. cf_bypasser=None,
  72. max_stuck_cycles: Optional[int] = 30):
  73. self.page = page
  74. self.config = config or {}
  75. self.context = context if context is not None else {}
  76. self.result = None
  77. self.interval = interval
  78. self.cf_bypasser = cf_bypasser
  79. self._logger = logger
  80. self.last_url = ""
  81. self.stuck_count = 0
  82. self.max_stuck_cycles = max_stuck_cycles
  83. # Collect annotated methods and sort by priority ascending
  84. self._rules = []
  85. for attr_name in dir(self):
  86. try:
  87. method = getattr(self, attr_name)
  88. if callable(method):
  89. for r in getattr(method, "_flow_rules", []):
  90. rule = r.copy()
  91. rule["is_done"] = getattr(method, "_is_done", rule.get("is_done", False))
  92. rule["fatal_msg"] = getattr(method, "_fatal_msg", rule.get("fatal_msg", None))
  93. rule["exception_cls"] = getattr(method, "_exception_cls", rule.get("exception_cls", BizLogicError))
  94. rule["method"] = method
  95. rule["name"] = attr_name
  96. self._rules.append(rule)
  97. except Exception:
  98. continue
  99. self._rules.sort(key=lambda r: r["priority"])
  100. def log(self, msg: str, level: str = "info"):
  101. if self._logger is not None:
  102. log_fn = getattr(self._logger, level.lower(), getattr(self._logger, "info", None))
  103. if callable(log_fn):
  104. log_fn(f"[{self.__class__.__name__}] {msg}")
  105. elif callable(self._logger):
  106. self._logger(f"[{self.__class__.__name__}] {msg}")
  107. else:
  108. print(f"[{self.__class__.__name__}] [{level.upper()}] {msg}")
  109. else:
  110. print(f"[{self.__class__.__name__}] [{level.upper()}] {msg}")
  111. def _matches(self, rule: Dict[str, Any]) -> bool:
  112. """Determines whether a rule is matched based on URL, Title, Text, Ele and custom Predicate"""
  113. # Guard: if no matching condition is specified, treat as unmatched
  114. if not any([
  115. rule.get("url"),
  116. rule.get("title"),
  117. rule.get("text"),
  118. rule.get("ele"),
  119. rule.get("not_ele"),
  120. rule.get("predicate"),
  121. ]):
  122. return False
  123. curr_url = getattr(self.page, "url", "") or ""
  124. curr_title = getattr(self.page, "title", "") or ""
  125. if rule["url"] and rule["url"] not in curr_url:
  126. return False
  127. if rule["title"] and rule["title"].lower() not in curr_title.lower():
  128. return False
  129. if rule["text"]:
  130. try:
  131. curr_html = getattr(self.page, "html", "") or ""
  132. if rule["text"] not in curr_html:
  133. return False
  134. except Exception:
  135. return False
  136. if rule["ele"]:
  137. try:
  138. if not self.page.ele(rule["ele"], timeout=0.2):
  139. return False
  140. except Exception:
  141. return False
  142. if rule["not_ele"]:
  143. try:
  144. if self.page.ele(rule["not_ele"], timeout=0.2):
  145. return False
  146. except Exception:
  147. pass
  148. if rule.get("predicate"):
  149. try:
  150. if not rule["predicate"](self):
  151. return False
  152. except Exception as e:
  153. self.log(f"[WARN] Rule @{rule.get('name', 'unknown')} predicate evaluation exception: {e}", level="warning")
  154. return False
  155. return True
  156. def run(self,
  157. max_steps: Optional[int] = None,
  158. timeout: Optional[float] = None,
  159. max_stuck_cycles: Optional[int] = None) -> Any:
  160. """
  161. Executes scanning dispatch loop, supporting both step count and timeout limits.
  162. :param max_steps: Maximum loop steps limit; None means unlimited.
  163. :param timeout: Maximum execution timeout (seconds); None means unlimited.
  164. :param max_stuck_cycles: Stuck cycles before refresh self-healing; None to disable.
  165. """
  166. if max_stuck_cycles is not None:
  167. self.max_stuck_cycles = max_stuck_cycles
  168. start_time = time.time()
  169. step = 0
  170. # Construct display info
  171. limits_desc = []
  172. if max_steps is not None:
  173. limits_desc.append(f"max_steps={max_steps}")
  174. if timeout is not None:
  175. limits_desc.append(f"timeout={timeout}s")
  176. limits_str = f" (Limits: {', '.join(limits_desc)})" if limits_desc else " (Unlimited mode)"
  177. self.log(f"🚀 Flow state machine started with {len(self._rules)} rule(s){limits_str}")
  178. while True:
  179. step += 1
  180. elapsed = time.time() - start_time
  181. # 1. Check step limit
  182. if max_steps is not None and step > max_steps:
  183. raise BizLogicError(
  184. f"Flow steps exhausted (Executed {step - 1} steps / limit {max_steps}, elapsed {elapsed:.1f}s), last URL: {getattr(self.page, 'url', '')}"
  185. )
  186. # 2. Check timeout limit
  187. if timeout is not None and elapsed > timeout:
  188. raise BizLogicError(
  189. f"Flow execution timed out (Elapsed {elapsed:.1f}s / limit {timeout:.1f}s, executed {step - 1} steps), last URL: {getattr(self.page, 'url', '')}"
  190. )
  191. # Format step prefix
  192. if max_steps is not None and timeout is not None:
  193. step_prefix = f"[{step}/{max_steps} | {elapsed:.1f}s/{timeout:.1f}s]"
  194. elif max_steps is not None:
  195. step_prefix = f"[{step}/{max_steps} | {elapsed:.1f}s]"
  196. elif timeout is not None:
  197. step_prefix = f"[Step {step} | {elapsed:.1f}s/{timeout:.1f}s]"
  198. else:
  199. step_prefix = f"[Step {step} | {elapsed:.1f}s]"
  200. try:
  201. self.page.wait.doc_loaded(timeout=5)
  202. except Exception:
  203. pass
  204. time.sleep(self.interval)
  205. curr_url = getattr(self.page, "url", "")
  206. # Stuck detection and refresh self-healing
  207. if self.max_stuck_cycles is not None and self.max_stuck_cycles > 0:
  208. if curr_url and curr_url == self.last_url:
  209. self.stuck_count += 1
  210. if self.stuck_count >= self.max_stuck_cycles:
  211. self.log(f"{step_prefix} [WARN] Page stuck for {self.stuck_count} cycles, executing refresh...", level="warning")
  212. try:
  213. self.page.refresh()
  214. self.page.wait.load_start(timeout=5)
  215. except Exception as e:
  216. self.log(f"[ERROR] Failed to refresh page: {e}", level="error")
  217. self.stuck_count = 0
  218. continue
  219. else:
  220. self.last_url, self.stuck_count = curr_url, 0
  221. # Match rules by priority
  222. matched_rule = None
  223. for rule in self._rules:
  224. if self._matches(rule):
  225. matched_rule = rule
  226. self.log(f"{step_prefix} 🎯 Matched rule: @{rule['name']} (priority={rule['priority']})")
  227. if rule["fatal_msg"]:
  228. self.log(f"💥 Fatal error interruption triggered: {rule['fatal_msg']}", level="error")
  229. exc_cls = rule.get("exception_cls", BizLogicError)
  230. raise exc_cls(rule["fatal_msg"])
  231. rule["method"]()
  232. if rule["is_done"]:
  233. self.log(f"✨ Goal achieved, flow complete! (Elapsed {time.time() - start_time:.1f}s, executed {step} steps)")
  234. return self.result if self.result is not None else True
  235. break
  236. if not matched_rule:
  237. self.log(f"{step_prefix} ⏳ No rules matched (URL: {curr_url}), waiting for next cycle...")