docs(tiku): 为新增和修改的搜题方法及格式校验函数补全 Docstrings 以提高覆盖率

Author: Zropk66

api/answer.py

@@ -210,13 +210,28 @@ def _get_conf(self):
 
     @property
     def _is_manual_mode(self) -> bool:
+        """检查当前题库是否为手动模式或包含手动模式。
+
+        Returns:
+            bool: 如果是手动模式或子题库中包含手动模式返回 True，否则返回 False。
+        """
         return (
             getattr(self, 'is_manual', False) or
             self.__class__.__name__ == 'TikuManual' or
             (self.__class__.__name__ == 'TikuFallback' and any(getattr(p, 'is_manual', False) or p.__class__.__name__ == 'TikuManual' for p in getattr(self, 'providers', [])))
         )
 
     def query(self,q_info:dict) -> Optional[str]:
+        """单题搜题方法。
+
+        首先检索本地缓存，缓存未命中则调用 _query 从远程或本地题库获取。
+
+        Args:
+            q_info: 题目信息字典，必须包含 'title' 和 'type'。
+
+        Returns:
+            Optional[str]: 搜到的答案字符串，未搜到或校验失败返回 None。
+        """
         if self.DISABLE:
             return None
 
@@ -250,6 +265,17 @@ def query(self,q_info:dict) -> Optional[str]:
         return None
 
     def query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Optional[str]]:
+        """批量搜题方法。
+
+        优先通过本地缓存过滤，缓存未命中的题目交由 _query_all 批量获取。
+
+        Args:
+            q_list: 题目字典列表。
+            query_delay: 每道题查询之间的延时（秒）。
+
+        Returns:
+            list[Optional[str]]: 答案列表，与传入的题目列表一一对应。
+        """
         if self.DISABLE:
             return [None] * len(q_list)
 
@@ -306,15 +332,27 @@ def query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Option
 
     @abstractmethod
     def _query(self, q_info:dict) -> Optional[str]:
-        """
-        查询接口, 交由自定义题库实现
+        """查询接口, 交由自定义题库实现
+
+        Args:
+            q_info: 题目信息字典。
+
+        Returns:
+            Optional[str]: 搜到的答案，未搜到返回 None。
         """
         pass
 
     def _query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Optional[str]]:
-        """
-        批量查询的实现接口，默认循环调用单个查询 _query。
+        """批量查询的实现接口，默认循环调用单个查询 _query。
+
         子类若有批量查询或交互需求（如手动模式），可重写此方法。
+
+        Args:
+            q_list: 待搜题列表。
+            query_delay: 单题请求延时。
+
+        Returns:
+            list[Optional[str]]: 搜到的批量答案列表。
         """
         results = []
         for q in q_list:
@@ -480,6 +518,17 @@ def _query(self, q_info:dict) -> Optional[str]:
         return None
 
     def _query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Optional[str]]:
+        """实现多题库回退的批量查询逻辑。
+
+        根据 providers 配置的顺序，对仍未命中的题目列表依次分配给子题库查询，直至所有题目命中或已无可用题库。
+
+        Args:
+            q_list: 待查询题目列表。
+            query_delay: 单题请求延时。
+
+        Returns:
+            list[Optional[str]]: 合并后的批量答案列表。
+        """
         results = [None] * len(q_list)
         pending_indices = list(range(len(q_list)))
 
@@ -1460,16 +1509,27 @@ def __init__(self, config_path: Optional[str] = None) -> None:
 
     @staticmethod
     def _extract_option_letters(ans: str) -> list[str]:
+        """从用户输入的答案中尝试提取纯选项字母。
+
+        当且仅当输入的除空白与标点符号外的字符全部为英文字母时才提取，否则返回空列表以指示为文本匹配模式。
+
+        Args:
+            ans: 用户手动输入的原始答案文本。
+
+        Returns:
+            list[str]: 提取出来的大写字母列表，或空列表。
+        """
         cleaned = re.sub(r'[\s,，;；、]+', '', ans)
         if not cleaned or not re.fullmatch(r'[A-Za-z]+', cleaned):
             return []
         return [c.upper() for c in cleaned]
 
     def _init_tiku(self):
+        """根据配置初始化手动模式的参数（输入模式、分隔符等）。"""
         self.default_mode = self._conf.get('manual_mode_default', 'batch').strip().lower()
         if self.default_mode not in ['batch', 'single']:
             self.default_mode = 'batch'
-        
+
         self.separator = self._conf.get('manual_mode_separator', ';')
         if self.separator.lower() in ['\\n', 'newline', '换行']:
             self.separator = '\n'
@@ -1480,7 +1540,7 @@ def _init_tiku(self):
 
     @staticmethod
     def _safe_close_tqdm_bars():
-        """安全地清除并关闭所有活动的 tqdm 进度条，防止私有属性变更引发异常"""
+        """安全地清除并关闭所有活动的 tqdm 进度条，防止私有属性变更异常。"""
         try:
             from tqdm import tqdm
             if hasattr(tqdm, '_instances') and hasattr(tqdm._instances, '__iter__'):
@@ -1500,6 +1560,14 @@ def _safe_close_tqdm_bars():
             logger.debug(f"获取/清理 tqdm 实例列表失败: {e}")
 
     def _query(self, q_info: dict) -> Optional[str]:
+        """手动单题搜题实现。
+
+        Args:
+            q_info: 题目信息字典。
+
+        Returns:
+            Optional[str]: 用户输入的答案字符串，跳过则返回 None。
+        """
         # 强行关闭清除所有当前活动的 tqdm 进度条
         self._safe_close_tqdm_bars()
 
@@ -1509,6 +1577,17 @@ def _query(self, q_info: dict) -> Optional[str]:
         return ans
 
     def _query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Optional[str]]:
+        """手动批量搜题实现。
+
+        根据配置进入批量粘贴流或单题轮询流。
+
+        Args:
+            q_list: 待搜题列表。
+            query_delay: 单题延时（此处不生效）。
+
+        Returns:
+            list[Optional[str]]: 用户输入的批量答案列表。
+        """
         # 强行关闭清除所有当前活动的 tqdm 进度条
         self._safe_close_tqdm_bars()
 
@@ -1523,6 +1602,7 @@ def _query_all(self, q_list: list[dict], query_delay: float = 0.0) -> list[Optio
 
     @staticmethod
     def _get_type_display(type_str: str) -> str:
+        """获取题目类型的中文友好名称。"""
         type_map = {
             'single': '单选题',
             'multiple': '多选题',

api/answer_check.py

@@ -1,4 +1,12 @@
 def check_single(answer):
+    """验证答案是否符合单选题的格式要求。
+
+    Args:
+        answer: 待验证的答案文本。
+
+    Returns:
+        bool: 如果答案不包含明显的多段答案分隔符，则返回 True；否则返回 False。
+    """
     if answer is None:
         return False
 
@@ -18,13 +26,31 @@ def check_single(answer):
 
 
 def check_multiple(answer):
+    """验证答案是否符合多选题的格式要求。
+
+    Args:
+        answer: 待验证的答案文本。
+
+    Returns:
+        bool: 如果答案可以被切分为多个有效的选项元素，则返回 True；否则返回 False。
+    """
     _t = cut(answer)
     if _t is not None and len(_t) > 0:
         return True
     return False
 
 
 def check_judgement(answer, true_list, false_list):
+    """验证并识别判断题答案。
+
+    Args:
+        answer: 待验证的答案文本。
+        true_list: 自定义正确判断词列表。
+        false_list: 自定义错误判断词列表。
+
+    Returns:
+        int: 如果是正确返回 1，如果是错误返回 0，无法判断返回 -1。
+    """
     val = str(answer).strip().lower()
     if val in ['true', 't', '1', '对', '正确', '√', '是', 'yes', 'y'] or val in [x.lower() for x in true_list]:
         return 1
@@ -35,13 +61,33 @@ def check_judgement(answer, true_list, false_list):
 
 
 def check_completion(answer):
+    """验证答案是否符合填空题的格式要求。
+
+    Args:
+        answer: 待验证的答案文本。
+
+    Returns:
+        bool: 如果答案长度大于 0，则返回 True；否则返回 False。
+    """
     if len(answer) > 0:
         return True
     else:
         return False
 
 
 def check_answer(answer, type, tiku):  # 只会写小杯代码，这里用个tiku感觉怪怪的，但先这么写着
+    """对搜题得到的答案进行有效性与题型一致性校验。
+
+    如果是手动模式或多题库回退包装器，将直接放行信任答案。
+
+    Args:
+        answer: 待验证的答案文本。
+        type: 题目类型 ('single', 'multiple', 'completion', 'judgement')。
+        tiku: 调用此校验的题库对象实例。
+
+    Returns:
+        bool: 校验通过返回 True，校验失败舍弃则返回 False。
+    """
     # 如果是手动模式或多题库回退包装器，直接信任
     # （手动模式豁免常规校验；回退包装器因其子题库在各自环节均已单独校验过，此处无需二次校验，以防二次过滤误杀）
     if getattr(tiku, 'is_manual', False) or getattr(tiku, 'skip_answer_validation', False):
@@ -65,6 +111,14 @@ def check_answer(answer, type, tiku):  # 只会写小杯代码，这里用个tik
 
 
 def cut(answer):
+    """根据高频分隔符切分多选或多空答案文本。
+
+    Args:
+        answer: 待切分的答案文本。
+
+    Returns:
+        list[str]: 切分后的子答案列表，如果无法切分则返回包含原文本的单元素列表，为 None 则返回 None。
+    """
     cut_char = [
         "\n",
         ",",

api/base.py

@@ -906,7 +906,7 @@ def fetch_response_with_retry():
             questions = decode_questions_info(_resp.text)
 
             if _resp.status_code == 200 and questions.get("questions"):
-                return (_resp, questions)
+                return _resp, questions
 
             logger.warning(
                 f"无效响应 (Code: {getattr(_resp, 'status_code', 'Unknown')}), 重试中...")