aury-boot 0.0.19__tar.gz → 0.0.20__tar.gz

{aury_boot-0.0.19 → aury_boot-0.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.19
+Version: 0.0.20
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.19 → aury_boot-0.0.20}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.19'
-__version_tuple__ = version_tuple = (0, 0, 19)
+__version__ = version = '0.0.20'
+__version_tuple__ = version_tuple = (0, 0, 20)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.19 → aury_boot-0.0.20}/aury/boot/commands/templates/project/aury_docs/08-scheduler.md.tpl

@@ -1,6 +1,6 @@
 # 定时任务（Scheduler）
 
-基于 APScheduler，完全透传原生 API。
+基于 APScheduler，支持两种触发器语法：字符串模式和原生对象模式。
 
 ## 基本用法
 
@@ -9,31 +9,38 @@
 ```python
 """定时任务模块。"""
 
-from apscheduler.triggers.cron import CronTrigger
-from apscheduler.triggers.interval import IntervalTrigger
-
 from aury.boot.common.logging import logger
 from aury.boot.infrastructure.scheduler import SchedulerManager
 
 scheduler = SchedulerManager.get_instance()
 
 
-@scheduler.scheduled_job(IntervalTrigger(seconds=60))
+# === 字符串模式（推荐，简洁）===
+@scheduler.scheduled_job("interval", seconds=60)
 async def every_minute():
     """每 60 秒执行。"""
     logger.info("定时任务执行中...")
 
 
-@scheduler.scheduled_job(CronTrigger(hour=0, minute=0))
+@scheduler.scheduled_job("cron", hour=0, minute=0)
 async def daily_task():
     """每天凌晨执行。"""
     logger.info("每日任务执行中...")
 
 
-@scheduler.scheduled_job(CronTrigger(day_of_week="mon", hour=9))
+@scheduler.scheduled_job("cron", day_of_week="mon", hour=9)
 async def weekly_report():
     """每周一 9 点执行。"""
     logger.info("周报任务执行中...")
+
+
+# === 原生对象模式（完整功能）===
+from apscheduler.triggers.cron import CronTrigger
+
+@scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))
+async def crontab_task():
+    """每天凌晨 2 点执行（使用 crontab 表达式）。"""
+    logger.info("每日任务执行中...")
 ```
 
 启用方式：配置 `SCHEDULER__ENABLED=true`，框架自动加载 `{package_name}/schedules/` 模块。
@@ -50,40 +57,57 @@ SCHEDULER__MISFIRE_GRACE_TIME=60                 # 错过容忍时间(秒)
 SCHEDULER__JOBSTORE_URL=redis://localhost:6379/0 # 分布式存储（可选）
 ```
 
-## 触发器类型
+## 触发器语法
 
-### CronTrigger - 定时触发
+支持两种语法：
 
-```python
-from apscheduler.triggers.cron import CronTrigger
+| 语法 | 适用场景 | 示例 |
+|------|---------|------|
+| 字符串模式 | 日常使用，简洁 | `"cron", hour="*", minute=0` |
+| 原生对象 | crontab 表达式、复杂配置 | `CronTrigger.from_crontab("0 * * * *")` |
 
+### cron - 定时触发
+
+```python
+# === 字符串模式 ===
 # 每天凌晨 2:30
-CronTrigger(hour=2, minute=30)
+@scheduler.scheduled_job("cron", hour=2, minute=30)
 
 # 每小时整点
-CronTrigger(hour="*", minute=0)
+@scheduler.scheduled_job("cron", hour="*", minute=0)
 
 # 工作日 9:00
-CronTrigger(day_of_week="mon-fri", hour=9)
+@scheduler.scheduled_job("cron", day_of_week="mon-fri", hour=9)
 
 # 每月 1 号
-CronTrigger(day=1, hour=0)
+@scheduler.scheduled_job("cron", day=1, hour=0)
+
+# === 原生对象模式 ===
+from apscheduler.triggers.cron import CronTrigger
 
 # 使用 crontab 表达式
-CronTrigger.from_crontab("0 2 * * *")  # 每天 2:00
+@scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))  # 每天 2:00
 ```
 
-### IntervalTrigger - 间隔触发
+**cron 参数**：`year`, `month`, `day`, `week`, `day_of_week`, `hour`, `minute`, `second`, `start_date`, `end_date`, `timezone`, `jitter`
+
+### interval - 间隔触发
 
 ```python
+# === 字符串模式 ===
+@scheduler.scheduled_job("interval", seconds=30)   # 每 30 秒
+@scheduler.scheduled_job("interval", minutes=5)    # 每 5 分钟
+@scheduler.scheduled_job("interval", hours=1)      # 每小时
+@scheduler.scheduled_job("interval", days=1)       # 每天
+
+# === 原生对象模式 ===
 from apscheduler.triggers.interval import IntervalTrigger
 
-IntervalTrigger(seconds=30)   # 每 30 秒
-IntervalTrigger(minutes=5)    # 每 5 分钟
-IntervalTrigger(hours=1)      # 每小时
-IntervalTrigger(days=1)       # 每天
+@scheduler.scheduled_job(IntervalTrigger(hours=1, jitter=60))  # 每小时，随机抖动 60 秒
 ```
 
+**interval 参数**：`weeks`, `days`, `hours`, `minutes`, `seconds`, `start_date`, `end_date`, `timezone`, `jitter`
+
 ### DateTrigger - 一次性触发
 
 ```python
@@ -91,7 +115,7 @@ from apscheduler.triggers.date import DateTrigger
 from datetime import datetime, timedelta
 
 # 10 秒后执行
-DateTrigger(run_date=datetime.now() + timedelta(seconds=10))
+scheduler.add_job(my_task, DateTrigger(run_date=datetime.now() + timedelta(seconds=10)))
 ```
 
 ## 多实例支持
@@ -136,7 +160,11 @@ scheduler = SchedulerManager.get_instance(
 ## 任务管理
 
 ```python
-# 添加任务
+# 添加任务（字符串模式）
+scheduler.add_job(my_task, "cron", hour=2, minute=0, id="my_task")
+
+# 添加任务（原生对象模式）
+from apscheduler.triggers.cron import CronTrigger
 scheduler.add_job(my_task, CronTrigger(hour=2), id="my_task")
 
 # 获取任务
@@ -150,7 +178,10 @@ scheduler.resume_job("my_task")
 # 移除
 scheduler.remove_job("my_task")
 
-# 重新调度
+# 重新调度（字符串模式）
+scheduler.reschedule_job("my_task", "cron", hour=3)
+
+# 重新调度（原生对象模式）
 scheduler.reschedule_job("my_task", CronTrigger(hour=3))
 ```
 

aury_boot-0.0.20/aury/boot/commands/templates/project/modules/schedules.py.tpl

@@ -0,0 +1,38 @@
+"""定时任务模块（Scheduler）。
+
+在此文件中定义定时任务，使用 @scheduler.scheduled_job() 装饰器。
+
+框架会自动发现并加载本模块，无需在 main.py 中手动导入。
+也可通过 SCHEDULER_SCHEDULE_MODULES 环境变量指定自定义模块。
+
+触发器支持两种语法：
+- 字符串模式（推荐）：@scheduler.scheduled_job("cron", hour="*", minute=0)
+- 原生对象模式：@scheduler.scheduled_job(CronTrigger(hour="*"))
+"""
+
+# from aury.boot.common.logging import logger
+# from aury.boot.infrastructure.scheduler import SchedulerManager
+#
+# scheduler = SchedulerManager.get_instance()
+#
+#
+# # === 字符串模式（推荐，简洁）===
+# @scheduler.scheduled_job("interval", seconds=60)
+# async def example_job():
+#     """示例定时任务，每 60 秒执行一次。"""
+#     logger.info("定时任务执行中...")
+#
+#
+# @scheduler.scheduled_job("cron", hour="*", minute=0)
+# async def hourly_job():
+#     """每小时整点执行。"""
+#     logger.info("整点任务执行")
+#
+#
+# # === 原生对象模式（完整功能）===
+# # from apscheduler.triggers.cron import CronTrigger
+# #
+# # @scheduler.scheduled_job(CronTrigger.from_crontab("0 2 * * *"))
+# # async def daily_job():
+# #     """每天凌晨 2 点执行（使用 crontab 表达式）。"""
+# #     logger.info("每日任务执行")

{aury_boot-0.0.19 → aury_boot-0.0.20}/aury/boot/infrastructure/scheduler/manager.py

@@ -7,6 +7,7 @@
 - 自动设置日志上下文（调度器任务日志自动写入 scheduler_xxx.log）
 - 支持多个命名实例
 - 支持 APScheduler 完整配置（jobstores、executors、job_defaults、timezone）
+- 支持两种触发器语法：字符串模式和原生对象模式
 """
 
 from __future__ import annotations
@@ -14,20 +15,32 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Callable
 from functools import wraps
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from aury.boot.common.logging import logger, set_service_context
 
 # 延迟导入 apscheduler（可选依赖）
 try:
     from apscheduler.schedulers.asyncio import AsyncIOScheduler
+    from apscheduler.triggers.base import BaseTrigger
+    from apscheduler.triggers.cron import CronTrigger
+    from apscheduler.triggers.interval import IntervalTrigger
     _APSCHEDULER_AVAILABLE = True
 except ImportError:
     _APSCHEDULER_AVAILABLE = False
     if TYPE_CHECKING:
         from apscheduler.schedulers.asyncio import AsyncIOScheduler
+        from apscheduler.triggers.base import BaseTrigger
+        from apscheduler.triggers.cron import CronTrigger
+        from apscheduler.triggers.interval import IntervalTrigger
     else:
         AsyncIOScheduler = None
+        BaseTrigger = None
+        CronTrigger = None
+        IntervalTrigger = None
+
+# 触发器类型别名
+TriggerType = Literal["cron", "interval"]
 
 
 class SchedulerManager:
@@ -39,6 +52,16 @@ class SchedulerManager:
     - job_defaults: 任务默认配置（coalesce/max_instances/misfire_grace_time）
     - timezone: 时区
     
+    触发器支持两种语法：
+    
+    1. 字符串模式（简洁）:
+        @scheduler.scheduled_job("cron", hour="*", minute=0)
+        @scheduler.scheduled_job("interval", seconds=60)
+        
+    2. 原生对象模式（完整功能）:
+        @scheduler.scheduled_job(CronTrigger(hour="*"))
+        @scheduler.scheduled_job(IntervalTrigger(seconds=60))
+    
     使用示例:
         from apscheduler.triggers.cron import CronTrigger
         from apscheduler.triggers.interval import IntervalTrigger
@@ -57,11 +80,16 @@ class SchedulerManager:
             timezone="Asia/Shanghai",
         )
         
-        # 注册任务
-        @scheduler.scheduled_job(IntervalTrigger(seconds=60))
+        # 字符串模式注册任务
+        @scheduler.scheduled_job("interval", seconds=60)
         async def my_task():
             ...
         
+        # 原生对象模式
+        @scheduler.scheduled_job(CronTrigger.from_crontab("0 * * * *"))
+        async def hourly_task():
+            ...
+        
         # 启动调度器
         scheduler.start()
     """
@@ -200,46 +228,88 @@ class SchedulerManager:
             raise RuntimeError("调度器未初始化，请先调用 initialize()")
         return self._scheduler
     
+    def _build_trigger(self, trigger: TriggerType | BaseTrigger, **trigger_kwargs: Any) -> BaseTrigger:
+        """构建触发器对象。
+        
+        Args:
+            trigger: 触发器类型字符串（"cron"/"interval"）或原生触发器对象
+            **trigger_kwargs: 触发器参数（仅字符串模式时有效）
+            
+        Returns:
+            APScheduler 触发器对象
+        """
+        # 如果已经是触发器对象，直接返回
+        if isinstance(trigger, BaseTrigger):
+            return trigger
+        
+        # 字符串模式，构建触发器
+        if trigger == "cron":
+            return CronTrigger(**trigger_kwargs)
+        elif trigger == "interval":
+            return IntervalTrigger(**trigger_kwargs)
+        else:
+            raise ValueError(f"不支持的触发器类型: {trigger}，支持 'cron' 或 'interval'")
+    
     def add_job(
         self,
         func: Callable,
-        trigger: Any,
+        trigger: TriggerType | BaseTrigger,
         *,
         id: str | None = None,
         **kwargs: Any,
     ) -> None:
         """添加任务。
         
-        直接使用 APScheduler 原生 trigger 对象，不做任何封装。
+        支持两种触发器语法：
+        
+        1. 字符串模式：trigger 为 "cron" 或 "interval"，触发器参数通过 kwargs 传递
+        2. 原生对象模式：trigger 为 APScheduler 触发器对象
         
         Args:
             func: 任务函数
-            trigger: APScheduler 触发器对象，如：
-                - IntervalTrigger(seconds=60)
-                - CronTrigger(hour="*")
-                - CronTrigger.from_crontab("0 * * * *")
+            trigger: 触发器类型或触发器对象
+                - 字符串: "cron" 或 "interval"
+                - 对象: CronTrigger(...) 或 IntervalTrigger(...)
             id: 任务ID（可选，默认使用函数完整路径）
-            **kwargs: 其他 APScheduler add_job 参数
+            **kwargs: 触发器参数（字符串模式）或其他 APScheduler add_job 参数（对象模式）
         
         示例:
-            from apscheduler.triggers.cron import CronTrigger
-            from apscheduler.triggers.interval import IntervalTrigger
-            
-            # 每小时执行
-            scheduler.add_job(my_task, CronTrigger(hour="*"))
+            # === 字符串模式 ===
+            # 每小时整点执行
+            scheduler.add_job(my_task, "cron", hour="*", minute=0)
             
             # 每 30 分钟执行
-            scheduler.add_job(my_task, IntervalTrigger(minutes=30))
+            scheduler.add_job(my_task, "interval", minutes=30)
             
             # 每天凌晨 2 点执行
-            scheduler.add_job(my_task, CronTrigger(hour=2, minute=0))
+            scheduler.add_job(my_task, "cron", hour=2, minute=0)
+            
+            # 每周一 9:00 执行
+            scheduler.add_job(my_task, "cron", day_of_week="mon", hour=9, minute=0)
+            
+            # === 原生对象模式 ===
+            from apscheduler.triggers.cron import CronTrigger
+            from apscheduler.triggers.interval import IntervalTrigger
             
             # 使用 crontab 表达式
             scheduler.add_job(my_task, CronTrigger.from_crontab("0 2 * * *"))
+            
+            # 原生触发器对象
+            scheduler.add_job(my_task, IntervalTrigger(seconds=60))
         """
         if not self._initialized:
             raise RuntimeError("调度器未初始化")
         
+        # 分离触发器参数和其他 add_job 参数
+        if isinstance(trigger, str):
+            # 字符串模式：需要从 kwargs 中分离触发器参数
+            trigger_params, job_params = self._separate_trigger_params(trigger, kwargs)
+            trigger_obj = self._build_trigger(trigger, **trigger_params)
+        else:
+            # 对象模式：kwargs 全部是 add_job 参数
+            trigger_obj = trigger
+            job_params = kwargs
+        
         # 包装任务函数，自动设置日志上下文
         wrapped_func = self._wrap_with_context(func)
 
@@ -247,12 +317,52 @@ class SchedulerManager:
         job_id = id or f"{func.__module__}.{func.__name__}"
         self._scheduler.add_job(
             func=wrapped_func,
-            trigger=trigger,
+            trigger=trigger_obj,
             id=job_id,
-            **kwargs,
+            **job_params,
         )
         
-        logger.info(f"任务已注册: {job_id} | 触发器: {type(trigger).__name__}")
+        logger.info(f"任务已注册: {job_id} | 触发器: {type(trigger_obj).__name__}")
+    
+    def _separate_trigger_params(
+        self,
+        trigger_type: str,
+        kwargs: dict[str, Any]
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """分离触发器参数和 add_job 参数。
+        
+        Args:
+            trigger_type: 触发器类型
+            kwargs: 混合参数
+            
+        Returns:
+            (trigger_params, job_params) 元组
+        """
+        # CronTrigger 支持的参数
+        cron_params = {
+            "year", "month", "day", "week", "day_of_week",
+            "hour", "minute", "second", "start_date", "end_date",
+            "timezone", "jitter"
+        }
+        # IntervalTrigger 支持的参数
+        interval_params = {
+            "weeks", "days", "hours", "minutes", "seconds",
+            "start_date", "end_date", "timezone", "jitter"
+        }
+        
+        # 根据触发器类型选择参数集
+        trigger_param_names = cron_params if trigger_type == "cron" else interval_params
+        
+        trigger_params: dict[str, Any] = {}
+        job_params: dict[str, Any] = {}
+        
+        for key, value in kwargs.items():
+            if key in trigger_param_names:
+                trigger_params[key] = value
+            else:
+                job_params[key] = value
+        
+        return trigger_params, job_params
     
     def _wrap_with_context(self, func: Callable) -> Callable:
         """包装任务函数，自动设置 scheduler 日志上下文。"""
@@ -339,19 +449,35 @@ class SchedulerManager:
     def reschedule_job(
         self,
         job_id: str,
-        trigger: Any,
+        trigger: TriggerType | BaseTrigger,
+        **trigger_kwargs: Any,
     ) -> None:
         """重新调度任务。
         
+        支持两种触发器语法：
+        
+        1. 字符串模式：trigger 为 "cron" 或 "interval"，触发器参数通过 kwargs 传递
+        2. 原生对象模式：trigger 为 APScheduler 触发器对象
+        
         Args:
             job_id: 任务ID
-            trigger: APScheduler 触发器对象
+            trigger: 触发器类型或触发器对象
+            **trigger_kwargs: 触发器参数（仅字符串模式时有效）
+        
+        示例:
+            # 字符串模式
+            scheduler.reschedule_job("my_job", "cron", hour="*/2")
+            scheduler.reschedule_job("my_job", "interval", minutes=15)
+            
+            # 原生对象模式
+            scheduler.reschedule_job("my_job", CronTrigger(hour="*/2"))
         """
         if not self._scheduler:
             raise RuntimeError("调度器未初始化")
         
-        self._scheduler.reschedule_job(job_id, trigger=trigger)
-        logger.info(f"任务已重新调度: {job_id} | 触发器: {type(trigger).__name__}")
+        trigger_obj = self._build_trigger(trigger, **trigger_kwargs)
+        self._scheduler.reschedule_job(job_id, trigger=trigger_obj)
+        logger.info(f"任务已重新调度: {job_id} | 触发器: {type(trigger_obj).__name__}")
     
     def pause_job(self, job_id: str) -> None:
         """暂停单个任务。
@@ -414,35 +540,52 @@ class SchedulerManager:
     
     def scheduled_job(
         self,
-        trigger: Any,
+        trigger: TriggerType | BaseTrigger,
         *,
         id: str | None = None,
         **kwargs: Any,
     ) -> Callable[[Callable], Callable]:
         """任务注册装饰器。
         
+        支持两种触发器语法：
+        
+        1. 字符串模式（推荐，简洁）:
+            @scheduler.scheduled_job("cron", hour="*", minute=0)
+            @scheduler.scheduled_job("interval", seconds=60)
+        
+        2. 原生对象模式（完整功能）:
+            @scheduler.scheduled_job(CronTrigger(hour="*"))
+            @scheduler.scheduled_job(IntervalTrigger(seconds=60))
+        
         使用示例:
-            from apscheduler.triggers.cron import CronTrigger
-            from apscheduler.triggers.interval import IntervalTrigger
-            
             scheduler = SchedulerManager.get_instance()
             
-            @scheduler.scheduled_job(IntervalTrigger(seconds=60))
+            # === 字符串模式 ===
+            @scheduler.scheduled_job("interval", seconds=60)
             async def my_task():
-                print("Task executed")
+                print("每分钟执行")
             
-            @scheduler.scheduled_job(CronTrigger(hour="*"))
+            @scheduler.scheduled_job("cron", hour="*", minute=0)
             async def hourly_task():
-                print("Hourly task")
+                print("每小时整点执行")
+            
+            @scheduler.scheduled_job("cron", day_of_week="mon-fri", hour=9)
+            async def workday_task():
+                print("工作日 9 点执行")
+            
+            # === 原生对象模式 ===
+            from apscheduler.triggers.cron import CronTrigger
             
             @scheduler.scheduled_job(CronTrigger.from_crontab("0 0 * * *"))
             async def daily_task():
-                print("Daily task")
+                print("每天 0 点执行")
         
         Args:
-            trigger: APScheduler 触发器对象
-            id: 任务ID
-            **kwargs: 其他 APScheduler add_job 参数
+            trigger: 触发器类型或触发器对象
+                - 字符串: "cron" 或 "interval"
+                - 对象: CronTrigger(...) 或 IntervalTrigger(...)
+            id: 任务ID（可选，默认使用函数完整路径）
+            **kwargs: 触发器参数（字符串模式）或其他 APScheduler add_job 参数
         
         Returns:
             装饰器函数

aury_boot-0.0.19/aury/boot/commands/templates/project/modules/schedules.py.tpl

@@ -1,21 +0,0 @@
-"""定时任务模块（Scheduler）。
-
-在此文件中定义定时任务，使用 @scheduler.scheduled_job() 装饰器。
-
-框架会自动发现并加载本模块，无需在 main.py 中手动导入。
-也可通过 SCHEDULER_SCHEDULE_MODULES 环境变量指定自定义模块。
-"""
-
-# from apscheduler.triggers.cron import CronTrigger
-# from apscheduler.triggers.interval import IntervalTrigger
-#
-# from aury.boot.common.logging import logger
-# from aury.boot.infrastructure.scheduler import SchedulerManager
-#
-# scheduler = SchedulerManager.get_instance()
-#
-#
-# @scheduler.scheduled_job(IntervalTrigger(seconds=60))
-# async def example_job():
-#     """示例定时任务，每 60 秒执行一次。"""
-#     logger.info("定时任务执行中...")