chore: update .gitignore and enhance docstrings across multiple files

- Added *.pyc and *.pyo to .gitignore to prevent compiled Python files from being tracked. - Improved docstrings in various modules, providing clearer descriptions of functions, parameters, and return values to enhance code readability and maintainability.
2026-09-21 12:52:26 +00:00 · 2026-04-04 01:21:59 +08:00
parent dcf8844453
commit b0ae6af3b1
96 changed files with 5089 additions and 304 deletions
@@ -65,7 +65,10 @@ async def get_scheduler_jobs_controller() -> JSONResponse:
 )
 async def start_scheduler_controller() -> JSONResponse:
    """
-    启动调度器
+    启动调度器。
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.start()
    log.info("调度器已启动")
@@ -81,7 +84,10 @@ async def start_scheduler_controller() -> JSONResponse:
 )
 async def pause_scheduler_controller() -> JSONResponse:
    """
-    暂停调度器
+    暂停调度器。
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.pause()
    log.info("调度器已暂停")
@@ -97,7 +103,10 @@ async def pause_scheduler_controller() -> JSONResponse:
 )
 async def resume_scheduler_controller() -> JSONResponse:
    """
-    恢复调度器
+    恢复调度器。
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.resume()
    log.info("调度器已恢复")
@@ -113,7 +122,10 @@ async def resume_scheduler_controller() -> JSONResponse:
 )
 async def shutdown_scheduler_controller() -> JSONResponse:
    """
-    关闭调度器
+    关闭调度器。
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    await SchedulerUtil.shutdown()
    log.info("调度器已关闭")
@@ -129,7 +141,10 @@ async def shutdown_scheduler_controller() -> JSONResponse:
 )
 async def clear_jobs_controller() -> JSONResponse:
    """
-    清空调度器中的所有任务
+    清空调度器中的所有任务。
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.clear_jobs()
    log.info("已清空所有任务")
@@ -191,6 +206,9 @@ async def pause_job_controller(

    参数:
    - job_id (str): 调度器任务ID
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.pause_job(job_id=job_id)
    log.info(f"暂停任务成功: {job_id}")
@@ -212,6 +230,9 @@ async def resume_job_controller(

    参数:
    - job_id (str): 调度器任务ID
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.resume_job(job_id=job_id)
    log.info(f"恢复任务成功: {job_id}")
@@ -233,6 +254,9 @@ async def run_job_controller(

    参数:
    - job_id (str): 调度器任务ID
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.run_job_now(job_id=job_id)
    log.info(f"立即执行任务成功: {job_id}")
@@ -254,6 +278,9 @@ async def remove_job_controller(

    参数:
    - job_id (str): 调度器任务ID
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    SchedulerUtil.remove_job(job_id=job_id)
    log.info(f"移除任务成功: {job_id}")
@@ -340,6 +367,9 @@ async def delete_job_log_controller(
    参数:
    - ids (list[int]): ID列表
    - auth (AuthSchema): 认证信息模型
+
+    返回:
+    - JSONResponse: 成功提示响应。
    """
    await JobService.delete_job_log_service(auth=auth, ids=ids)
    log.info(f"删除执行日志成功: {ids}")
@@ -86,11 +86,17 @@ class JobCRUD(CRUDBase[JobModel, JobCreateSchema, JobUpdateSchema]):

        参数:
        - ids (list[int]): 日志ID列表
+
+        返回:
+        - None
        """
        return await self.delete(ids=ids)

    async def clear_obj_crud(self) -> None:
        """
-        清空所有执行日志
+        清空所有执行日志。
+
+        返回:
+        - None
        """
        return await self.clear()
@@ -67,7 +67,19 @@ class JobService:
        search: JobQueryParam | None = None,
        order_by: list[dict[str, str]] | None = None,
    ) -> dict:
-        """分页查询执行日志（数据库 OFFSET/LIMIT）。"""
+        """
+        分页查询执行日志（数据库 OFFSET/LIMIT）。
+
+        参数:
+        - auth (AuthSchema): 认证信息。
+        - page_no (int): 页码。
+        - page_size (int): 每页条数。
+        - search (JobQueryParam | None): 查询条件。
+        - order_by (list[dict[str, str]] | None): 排序。
+
+        返回:
+        - dict: 分页结果。
+        """
        offset = (page_no - 1) * page_size
        ob = order_by or [{"created_time": "desc"}]
        return await JobCRUD(auth).page(
@@ -149,6 +161,9 @@ class JobService:
        参数:
        - auth (AuthSchema): 认证信息模型
        - ids (list[int]): 日志ID列表
+
+        返回:
+        - None
        """
        if len(ids) < 1:
            raise CustomException(msg="删除失败，删除对象不能为空")
@@ -161,6 +176,9 @@ class JobService:

        参数:
        - auth (AuthSchema): 认证信息模型
+
+        返回:
+        - None
        """
        await JobCRUD(auth).clear_obj_crud()

@@ -33,6 +33,12 @@ async def get_node_options_controller(
 ) -> JSONResponse:
    """
    获取数据库中的定时任务节点定义（task_node），与编排节点类型无关。
+
+    参数:
+    - auth (AuthSchema): 认证信息。
+
+    返回:
+    - JSONResponse: 成功响应，data 为选项列表。
    """
    result = await NodeService.get_node_options_service(auth=auth)
    log.info("获取定时任务节点选项成功")
@@ -89,6 +89,9 @@ class NodeCRUD(CRUDBase[NodeModel, NodeCreateSchema, NodeUpdateSchema]):

        参数:
        - ids (list[int]): 节点ID列表
+
+        返回:
+        - None
        """
        return await self.delete(ids=ids)

@@ -99,6 +102,9 @@ class NodeCRUD(CRUDBase[NodeModel, NodeCreateSchema, NodeUpdateSchema]):
        参数:
        - ids (list[int]): 节点ID列表
        - kwargs: 其他要设置的字段,例如 available=True 或 available=False
+
+        返回:
+        - None
        """
        return await self.set(ids=ids, **kwargs)

@@ -108,5 +114,8 @@ class NodeCRUD(CRUDBase[NodeModel, NodeCreateSchema, NodeUpdateSchema]):

        注意:
        - 此操作会删除所有节点日志,请谨慎操作
+
+        返回:
+        - None
        """
        return await self.clear()
@@ -8,7 +8,12 @@ from datetime import datetime


 def demo_handler(*args, **kwargs) -> dict:
-    """示例处理器"""
+    """
+    示例处理器（演示节点调用形态）。
+
+    返回:
+    - dict: 包含 message、入参快照与时间戳。
+    """
    return {
        "message": "Hello from demo_handler!",
        "args": args,
@@ -19,9 +24,14 @@ def demo_handler(*args, **kwargs) -> dict:

 def process_data(data: list, operation: str = "sum") -> dict:
    """
-    简单数据处理
+    简单数值列表聚合。

-    operation: sum, avg, max, min, count
+    参数:
+    - data (list): 数值列表。
+    - operation (str): sum、avg、max、min、count 之一。
+
+    返回:
+    - dict: 含 operation 与 result，或 error 说明。
    """
    if not data:
        return {"error": "数据为空"}
@@ -96,7 +96,19 @@ class NodeService:
        search: NodeQueryParam | None = None,
        order_by: list[dict[str, str]] | None = None,
    ) -> dict:
-        """分页查询定时任务节点（数据库 OFFSET/LIMIT）。"""
+        """
+        分页查询定时任务节点（数据库 OFFSET/LIMIT）。
+
+        参数:
+        - auth (AuthSchema): 认证信息。
+        - page_no (int): 页码。
+        - page_size (int): 每页条数。
+        - search (NodeQueryParam | None): 查询条件。
+        - order_by (list[dict[str, str]] | None): 排序。
+
+        返回:
+        - dict: 分页结果。
+        """
        offset = (page_no - 1) * page_size
        return await NodeCRUD(auth).page(
            offset=offset,
@@ -157,6 +169,9 @@ class NodeService:
        参数:
        - auth (AuthSchema): 认证信息模型
        - ids (list[int]): 节点ID列表
+
+        返回:
+        - None
        """
        if len(ids) < 1:
            raise CustomException(msg="删除失败，删除对象不能为空")
@@ -178,6 +193,9 @@ class NodeService:

        参数:
        - auth (AuthSchema): 认证信息模型
+
+        返回:
+        - None
        """
        SchedulerUtil.clear_jobs()
        await NodeCRUD(auth).clear_obj_crud()