faster-cron 0.1.0__tar.gz

faster_cron-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: faster-cron
+Version: 0.1.0
+Summary: 一个轻量、直观、支持异步与同步双模式的定时任务调度器
+Author-email: Bernard Simon <bernardziyi@gmail.com>
+Project-URL: Homepage, https://github.com/BernardSimon/faster-cron
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# FasterCron
+
+**FasterCron** 是一个轻量级、直观且功能强大的 Python 定时任务调度工具库。它完美支持 **Asyncio (异步)** 和 **Threading (多线程)** 双模式，专为需要高可靠性、简单配置和任务并发控制的场景设计。
+
+---
+
+## 🌟 核心特性
+
+* **双模式支持**：一套逻辑同时提供 `AsyncFasterCron`（异步）和 `FasterCron`（同步多线程）两种实现。
+* **任务级并发控制**：通过 `allow_overlap` 参数精准控制同一个任务是否允许重叠执行（单例模式 vs 并发模式）。
+* **智能参数注入**：自动检测任务函数签名，按需注入包含调度时间、任务名称的 `context` 上下文。
+* **标准 Cron 支持**：兼容 5 位（分时日月周）和 6 位（秒分时日月周）Cron 表达式。
+* **健壮性**：内置异常捕获机制，单个任务崩溃不影响调度器运行。
+* **无外部依赖**：仅使用 Python 标准库实现，轻量无负担。
+
+---
+
+## 📦 安装
+
+您可以直接通过 pip 安装：
+
+```bash
+pip install faster-cron
+
+```
+
+或者直接将源码放入您的项目中。
+
+---
+
+## 🚀 快速上手
+
+### 1. 异步模式 (Async Mode)
+
+适用于使用了 `aiohttp`, `httpx` 或 `tortoise-orm` 等异步库的项目。
+
+```python
+import asyncio
+from faster_cron import AsyncFasterCron
+
+cron = AsyncFasterCron()
+
+
+# 示例：每 5 秒执行一次，禁止重叠（若上一个任务没跑完，则跳过本次）
+@cron.schedule("*/5 * * * * *", allow_overlap=False)
+async def my_async_job(context):
+    print(f"正在执行任务: {context['task_name']}, 计划时间: {context['scheduled_at']}")
+    await asyncio.sleep(6)  # 模拟长耗时任务
+
+
+async def main():
+    await cron.start()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### 2. 同步模式 (Sync Mode)
+
+适用于传统的阻塞式脚本或爬虫。
+
+```python
+from faster_cron import FasterCron
+import time
+
+cron = FasterCron()
+
+
+# 示例：每秒执行一次，允许并发执行
+@cron.schedule("* * * * * *", allow_overlap=True)
+def my_sync_job():
+    print("滴答，同步任务正在运行...")
+    time.sleep(2)
+
+
+if __name__ == "__main__":
+    cron.run()
+
+```
+
+---
+
+## 🛠 核心 API 说明
+
+### 调度装饰器 `schedule`
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `expression` | `str` | - | Cron 表达式。支持 `*`, `,`, `-`, `/`。 |
+| `allow_overlap` | `bool` | `True` | **关键参数**。`True`: 时间点到达即执行；`False`: 若该任务的上一个实例未结束，则跳过本次执行循环。 |
+
+### 上下文参数 `context`
+
+如果您的任务函数接收名为 `context` 的参数，FasterCron 会自动注入以下字典：
+
+* `task_name`: 函数名称。
+* `scheduled_at`: 任务触发的精确 `datetime` 对象。
+* `expression`: 该任务使用的 Cron 表达式。
+
+---
+
+## 📅 Cron 表达式参考
+
+FasterCron 支持灵活的表达式定义：
+
+* `* * * * * *` : 每秒执行。
+* `*/5 * * * * *` : 每 5 秒执行。
+* `0 0 * * * *` : 每整小时执行。
+* `0 30 9-17 * * *` : 每天 9:00 到 17:00 之间的每半小时执行。
+* `0 0 0 * * 0` : 每周日凌晨执行。
+
+---
+
+## 🧪 运行测试
+
+本项目包含完善的单元测试。您可以使用 `pytest` 来验证功能：
+
+```bash
+# 安装测试依赖
+pip install pytest pytest-asyncio
+
+# 运行所有测试
+pytest
+
+```
+
+---
+
+## 📄 开源协议
+
+MIT License.
+
+---
+
+**如果您觉得好用，欢迎点一个 Star！🌟**

faster_cron-0.1.0/README.md

@@ -0,0 +1,137 @@
+# FasterCron
+
+**FasterCron** 是一个轻量级、直观且功能强大的 Python 定时任务调度工具库。它完美支持 **Asyncio (异步)** 和 **Threading (多线程)** 双模式，专为需要高可靠性、简单配置和任务并发控制的场景设计。
+
+---
+
+## 🌟 核心特性
+
+* **双模式支持**：一套逻辑同时提供 `AsyncFasterCron`（异步）和 `FasterCron`（同步多线程）两种实现。
+* **任务级并发控制**：通过 `allow_overlap` 参数精准控制同一个任务是否允许重叠执行（单例模式 vs 并发模式）。
+* **智能参数注入**：自动检测任务函数签名，按需注入包含调度时间、任务名称的 `context` 上下文。
+* **标准 Cron 支持**：兼容 5 位（分时日月周）和 6 位（秒分时日月周）Cron 表达式。
+* **健壮性**：内置异常捕获机制，单个任务崩溃不影响调度器运行。
+* **无外部依赖**：仅使用 Python 标准库实现，轻量无负担。
+
+---
+
+## 📦 安装
+
+您可以直接通过 pip 安装：
+
+```bash
+pip install faster-cron
+
+```
+
+或者直接将源码放入您的项目中。
+
+---
+
+## 🚀 快速上手
+
+### 1. 异步模式 (Async Mode)
+
+适用于使用了 `aiohttp`, `httpx` 或 `tortoise-orm` 等异步库的项目。
+
+```python
+import asyncio
+from faster_cron import AsyncFasterCron
+
+cron = AsyncFasterCron()
+
+
+# 示例：每 5 秒执行一次，禁止重叠（若上一个任务没跑完，则跳过本次）
+@cron.schedule("*/5 * * * * *", allow_overlap=False)
+async def my_async_job(context):
+    print(f"正在执行任务: {context['task_name']}, 计划时间: {context['scheduled_at']}")
+    await asyncio.sleep(6)  # 模拟长耗时任务
+
+
+async def main():
+    await cron.start()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### 2. 同步模式 (Sync Mode)
+
+适用于传统的阻塞式脚本或爬虫。
+
+```python
+from faster_cron import FasterCron
+import time
+
+cron = FasterCron()
+
+
+# 示例：每秒执行一次，允许并发执行
+@cron.schedule("* * * * * *", allow_overlap=True)
+def my_sync_job():
+    print("滴答，同步任务正在运行...")
+    time.sleep(2)
+
+
+if __name__ == "__main__":
+    cron.run()
+
+```
+
+---
+
+## 🛠 核心 API 说明
+
+### 调度装饰器 `schedule`
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `expression` | `str` | - | Cron 表达式。支持 `*`, `,`, `-`, `/`。 |
+| `allow_overlap` | `bool` | `True` | **关键参数**。`True`: 时间点到达即执行；`False`: 若该任务的上一个实例未结束，则跳过本次执行循环。 |
+
+### 上下文参数 `context`
+
+如果您的任务函数接收名为 `context` 的参数，FasterCron 会自动注入以下字典：
+
+* `task_name`: 函数名称。
+* `scheduled_at`: 任务触发的精确 `datetime` 对象。
+* `expression`: 该任务使用的 Cron 表达式。
+
+---
+
+## 📅 Cron 表达式参考
+
+FasterCron 支持灵活的表达式定义：
+
+* `* * * * * *` : 每秒执行。
+* `*/5 * * * * *` : 每 5 秒执行。
+* `0 0 * * * *` : 每整小时执行。
+* `0 30 9-17 * * *` : 每天 9:00 到 17:00 之间的每半小时执行。
+* `0 0 0 * * 0` : 每周日凌晨执行。
+
+---
+
+## 🧪 运行测试
+
+本项目包含完善的单元测试。您可以使用 `pytest` 来验证功能：
+
+```bash
+# 安装测试依赖
+pip install pytest pytest-asyncio
+
+# 运行所有测试
+pytest
+
+```
+
+---
+
+## 📄 开源协议
+
+MIT License.
+
+---
+
+**如果您觉得好用，欢迎点一个 Star！🌟**

faster_cron-0.1.0/faster_cron/__init__.py

@@ -0,0 +1,9 @@
+"""
+FasterCron: 一个轻量、直观、支持异步与同步双模式的定时任务调度器。
+"""
+
+from .async_cron import AsyncFasterCron
+from .sync_cron import FasterCron
+
+__version__ = "0.1.0"
+__all__ = ["AsyncFasterCron", "FasterCron"]

faster_cron-0.1.0/faster_cron/async_cron.py

@@ -0,0 +1,59 @@
+import asyncio
+import inspect
+import datetime
+import logging
+from typing import Callable, Optional
+from .base import CronBase
+
+
+class AsyncFasterCron:
+    def __init__(self, log_level=logging.INFO):
+        self.tasks = []
+        self.logger = logging.getLogger("FasterCron.Async")
+        self.logger.setLevel(log_level)
+        self._running = False
+
+    def schedule(self, expression: str, allow_overlap: bool = True):
+        def decorator(func: Callable):
+            self.tasks.append({
+                "expression": expression,
+                "func": func,
+                "allow_overlap": allow_overlap,
+                "name": func.__name__
+            })
+            return func
+
+        return decorator
+
+    async def start(self):
+        self._running = True
+        listeners = [self._monitor(task) for task in self.tasks]
+        await asyncio.gather(*listeners)
+
+    async def _monitor(self, task):
+        last_ts = 0
+        current_task: Optional[asyncio.Task] = None
+
+        while self._running:
+            now = datetime.datetime.now()
+            ts = int(now.timestamp())
+
+            if ts != last_ts and CronBase.is_time_match(task["expression"], now):
+                last_ts = ts
+                if not task["allow_overlap"] and current_task and not current_task.done():
+                    self.logger.warning(f"Skip {task['name']}: overlapping blocked.")
+                    continue
+
+                context = {"scheduled_at": now, "task_name": task["name"]}
+                current_task = asyncio.create_task(self._wrapper(task["func"], context))
+
+            await asyncio.sleep(1.0 - (now.microsecond / 1_000_000) + 0.01)
+
+    async def _wrapper(self, func, context):
+        try:
+            sig = inspect.signature(func)
+            kwargs = {"context": context} if "context" in sig.parameters or any(
+                p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()) else {}
+            await func(**kwargs)
+        except Exception as e:
+            self.logger.error(f"Task {func.__name__} failed: {e}", exc_info=True)

faster_cron-0.1.0/faster_cron/base.py

@@ -0,0 +1,42 @@
+import datetime
+
+
+class CronBase:
+    """提供 Cron 表达式解析的底层逻辑"""
+
+    @staticmethod
+    def is_time_match(expression: str, now: datetime.datetime) -> bool:
+        parts = expression.split()
+        if len(parts) == 5:
+            # 分 时 日 月 周 -> 补齐秒为 0
+            sec_part, min_part, hour_part, day_part, month_part, weekday_part = "0", *parts
+        elif len(parts) == 6:
+            sec_part, min_part, hour_part, day_part, month_part, weekday_part = parts
+        else:
+            return False
+
+        return (
+                CronBase._match_field(sec_part, now.second) and
+                CronBase._match_field(min_part, now.minute) and
+                CronBase._match_field(hour_part, now.hour) and
+                CronBase._match_field(day_part, now.day) and
+                CronBase._match_field(month_part, now.month) and
+                CronBase._match_field(weekday_part, now.weekday())
+        )
+
+    @staticmethod
+    def _match_field(pattern: str, value: int) -> bool:
+        if pattern == "*": return True
+        if "," in pattern: return any(CronBase._match_field(p, value) for p in pattern.split(","))
+        if "/" in pattern:
+            r, s = pattern.split("/")
+            step = int(s)
+            if r in ["*", ""]: return value % step == 0
+            if "-" in r:
+                start, end = map(int, r.split("-"))
+                return start <= value <= end and (value - start) % step == 0
+            return value >= int(r) and (value - int(r)) % step == 0
+        if "-" in pattern:
+            start, end = map(int, pattern.split("-"))
+            return start <= value <= end
+        return int(pattern) == value

faster_cron-0.1.0/faster_cron/sync_cron.py

@@ -0,0 +1,104 @@
+import threading
+import time
+import datetime
+import logging
+import inspect
+from typing import List, Dict, Any, Callable
+from .base import CronBase
+
+
+class FasterCron:
+    def __init__(self, log_level=logging.INFO):
+        self.tasks: List[Dict[str, Any]] = []
+        self.logger = logging.getLogger("FasterCron.Sync")
+        self.logger.setLevel(log_level)
+        self._running = False
+        self._monitors: List[threading.Thread] = []
+
+    def schedule(self, expression: str, allow_overlap: bool = True):
+        """
+        注册同步任务。
+        allow_overlap 为 True 时，会通过开启新线程来实现并发执行。
+        """
+
+        def decorator(func: Callable):
+            self.tasks.append({
+                "expression": expression,
+                "func": func,
+                "allow_overlap": allow_overlap,
+                "name": func.__name__,
+                "last_worker": None  # 用于追踪此任务的上一个执行线程
+            })
+            return func
+
+        return decorator
+
+    def run(self):
+        """阻塞启动所有任务监控器"""
+        self._running = True
+        self.logger.info(f"FasterCron (Sync Mode) started with {len(self.tasks)} tasks.")
+
+        for task in self.tasks:
+            t = threading.Thread(
+                target=self._monitor_loop,
+                args=(task,),
+                name=f"Monitor-{task['name']}",
+                daemon=True
+            )
+            t.start()
+            self._monitors.append(t)
+
+        try:
+            while self._running:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            self.logger.info("FasterCron stopping...")
+            self._running = False
+
+    def _monitor_loop(self, task: Dict[str, Any]):
+        """每个任务独立的监听循环"""
+        last_trigger_ts = 0
+
+        while self._running:
+            now = datetime.datetime.now()
+            current_ts = int(now.timestamp())
+
+            # 1. 时间匹配检查 (确保每秒只触发一次)
+            if current_ts != last_trigger_ts and CronBase.is_time_match(task["expression"], now):
+                last_trigger_ts = current_ts
+
+                # 2. 并发控制
+                if not task["allow_overlap"]:
+                    # 单例模式：检查上一个工作线程是否还在跑
+                    prev_worker = task.get("last_worker")
+                    if prev_worker and prev_worker.is_alive():
+                        self.logger.warning(f"Task '{task['name']}' is still running. Skipping this cycle.")
+                        continue
+
+                # 3. 执行任务
+                # 无论是并发还是单例，都开启新线程执行工作函数，避免阻塞监控循环
+                context = {"scheduled_at": now, "task_name": task["name"]}
+                worker_thread = threading.Thread(
+                    target=self._execute_task,
+                    args=(task["func"], context),
+                    name=f"Worker-{task['name']}-{current_ts}",
+                    daemon=True
+                )
+                task["last_worker"] = worker_thread  # 记录引用以便下次检查
+                worker_thread.start()
+
+            # 4. 精确对齐到下一秒
+            sleep_time = 1.0 - (now.microsecond / 1_000_000) + 0.01
+            time.sleep(sleep_time)
+
+    def _execute_task(self, func: Callable, context: Dict):
+        """具体的任务执行包装器"""
+        try:
+            # 智能参数注入
+            sig = inspect.signature(func)
+            if 'context' in sig.parameters:
+                func(context=context)
+            else:
+                func()
+        except Exception as e:
+            self.logger.error(f"Error in task '{func.__name__}': {e}", exc_info=True)

faster_cron-0.1.0/faster_cron.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: faster-cron
+Version: 0.1.0
+Summary: 一个轻量、直观、支持异步与同步双模式的定时任务调度器
+Author-email: Bernard Simon <bernardziyi@gmail.com>
+Project-URL: Homepage, https://github.com/BernardSimon/faster-cron
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# FasterCron
+
+**FasterCron** 是一个轻量级、直观且功能强大的 Python 定时任务调度工具库。它完美支持 **Asyncio (异步)** 和 **Threading (多线程)** 双模式，专为需要高可靠性、简单配置和任务并发控制的场景设计。
+
+---
+
+## 🌟 核心特性
+
+* **双模式支持**：一套逻辑同时提供 `AsyncFasterCron`（异步）和 `FasterCron`（同步多线程）两种实现。
+* **任务级并发控制**：通过 `allow_overlap` 参数精准控制同一个任务是否允许重叠执行（单例模式 vs 并发模式）。
+* **智能参数注入**：自动检测任务函数签名，按需注入包含调度时间、任务名称的 `context` 上下文。
+* **标准 Cron 支持**：兼容 5 位（分时日月周）和 6 位（秒分时日月周）Cron 表达式。
+* **健壮性**：内置异常捕获机制，单个任务崩溃不影响调度器运行。
+* **无外部依赖**：仅使用 Python 标准库实现，轻量无负担。
+
+---
+
+## 📦 安装
+
+您可以直接通过 pip 安装：
+
+```bash
+pip install faster-cron
+
+```
+
+或者直接将源码放入您的项目中。
+
+---
+
+## 🚀 快速上手
+
+### 1. 异步模式 (Async Mode)
+
+适用于使用了 `aiohttp`, `httpx` 或 `tortoise-orm` 等异步库的项目。
+
+```python
+import asyncio
+from faster_cron import AsyncFasterCron
+
+cron = AsyncFasterCron()
+
+
+# 示例：每 5 秒执行一次，禁止重叠（若上一个任务没跑完，则跳过本次）
+@cron.schedule("*/5 * * * * *", allow_overlap=False)
+async def my_async_job(context):
+    print(f"正在执行任务: {context['task_name']}, 计划时间: {context['scheduled_at']}")
+    await asyncio.sleep(6)  # 模拟长耗时任务
+
+
+async def main():
+    await cron.start()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### 2. 同步模式 (Sync Mode)
+
+适用于传统的阻塞式脚本或爬虫。
+
+```python
+from faster_cron import FasterCron
+import time
+
+cron = FasterCron()
+
+
+# 示例：每秒执行一次，允许并发执行
+@cron.schedule("* * * * * *", allow_overlap=True)
+def my_sync_job():
+    print("滴答，同步任务正在运行...")
+    time.sleep(2)
+
+
+if __name__ == "__main__":
+    cron.run()
+
+```
+
+---
+
+## 🛠 核心 API 说明
+
+### 调度装饰器 `schedule`
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `expression` | `str` | - | Cron 表达式。支持 `*`, `,`, `-`, `/`。 |
+| `allow_overlap` | `bool` | `True` | **关键参数**。`True`: 时间点到达即执行；`False`: 若该任务的上一个实例未结束，则跳过本次执行循环。 |
+
+### 上下文参数 `context`
+
+如果您的任务函数接收名为 `context` 的参数，FasterCron 会自动注入以下字典：
+
+* `task_name`: 函数名称。
+* `scheduled_at`: 任务触发的精确 `datetime` 对象。
+* `expression`: 该任务使用的 Cron 表达式。
+
+---
+
+## 📅 Cron 表达式参考
+
+FasterCron 支持灵活的表达式定义：
+
+* `* * * * * *` : 每秒执行。
+* `*/5 * * * * *` : 每 5 秒执行。
+* `0 0 * * * *` : 每整小时执行。
+* `0 30 9-17 * * *` : 每天 9:00 到 17:00 之间的每半小时执行。
+* `0 0 0 * * 0` : 每周日凌晨执行。
+
+---
+
+## 🧪 运行测试
+
+本项目包含完善的单元测试。您可以使用 `pytest` 来验证功能：
+
+```bash
+# 安装测试依赖
+pip install pytest pytest-asyncio
+
+# 运行所有测试
+pytest
+
+```
+
+---
+
+## 📄 开源协议
+
+MIT License.
+
+---
+
+**如果您觉得好用，欢迎点一个 Star！🌟**

faster_cron-0.1.0/faster_cron.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+faster_cron/__init__.py
+faster_cron/async_cron.py
+faster_cron/base.py
+faster_cron/sync_cron.py
+faster_cron.egg-info/PKG-INFO
+faster_cron.egg-info/SOURCES.txt
+faster_cron.egg-info/dependency_links.txt
+faster_cron.egg-info/top_level.txt
+test/test_async.py
+test/test_sync.py

faster_cron-0.1.0/faster_cron.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

faster_cron-0.1.0/faster_cron.egg-info/top_level.txt

@@ -0,0 +1 @@
+faster_cron

faster_cron-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "faster-cron"
+version = "0.1.0"
+authors = [
+  { name="Bernard Simon", email="bernardziyi@gmail.com" },
+]
+description = "一个轻量、直观、支持异步与同步双模式的定时任务调度器"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+]
+
+[project.urls]
+"Homepage" = "https://github.com/BernardSimon/faster-cron"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["faster_cron*"]

faster_cron-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

faster_cron-0.1.0/test/test_async.py

@@ -0,0 +1,50 @@
+import asyncio
+import pytest
+from datetime import datetime
+from faster_cron.async_cron import AsyncFastCron
+
+@pytest.mark.asyncio
+async def test_async_overlap_prevention():
+    """
+    测试异步模式下的重叠控制：
+    注册一个每秒触发一次的任务，但任务耗时 1.5 秒且 allow_overlap=False。
+    在运行 3 秒的时间内，该任务应该只执行 2 次（第 1 秒触发，第 2 秒因为第 1 秒的没跑完被跳过）。
+    """
+    cron = AsyncFastCron()
+    execution_counter = 0
+
+    @cron.schedule("* * * * * *", allow_overlap=False)
+    async def slow_task():
+        nonlocal execution_counter
+        execution_counter += 1
+        await asyncio.sleep(1.5)
+
+    # 启动调度器并运行 3.2 秒后停止
+    cron_task = asyncio.create_task(cron.start())
+    await asyncio.sleep(3.2)
+    cron._running = False
+    cron_task.cancel()
+
+    # 预期执行次数应为 2 (触发点: T+1, T+3)
+    # 如果允许重叠，3.2秒内会触发 3 次
+    assert execution_counter == 2, f"预期执行 2 次，实际执行了 {execution_counter} 次"
+
+@pytest.mark.asyncio
+async def test_async_context_injection():
+    """测试上下文参数是否能正确注入"""
+    cron = AsyncFastCron()
+    received_context = None
+
+    @cron.schedule("* * * * * *")
+    async def task_with_ctx(context):
+        nonlocal received_context
+        received_context = context
+
+    cron_task = asyncio.create_task(cron.start())
+    await asyncio.sleep(1.1)
+    cron._running = False
+    cron_task.cancel()
+
+    assert received_context is not None
+    assert "task_name" in received_context
+    assert received_context["task_name"] == "task_with_ctx"

faster_cron-0.1.0/test/test_sync.py

@@ -0,0 +1,60 @@
+import time
+import threading
+import pytest
+from faster_cron.sync_cron import FastCron
+
+
+def test_sync_overlap_prevention():
+    """
+    测试同步模式下的重叠控制：
+    任务耗时 1.2 秒，触发间隔 1 秒，禁止重叠。
+    """
+    cron = FastCron()
+    execution_counter = 0
+    lock = threading.Lock()
+
+    @cron.schedule("* * * * * *", allow_overlap=False)
+    def slow_sync_task():
+        nonlocal execution_counter
+        with lock:
+            execution_counter += 1
+        time.sleep(1.2)
+
+    # 在后台线程运行调度器
+    cron_thread = threading.Thread(target=cron.run, daemon=True)
+    cron_thread.start()
+
+    # 观察 2.5 秒
+    time.sleep(2.5)
+    cron._running = False
+
+    # 预期：第 1 秒启动，第 2 秒检测到线程 alive 于是跳过
+    with lock:
+        assert execution_counter < 3, "同步模式下禁止重叠失败，执行次数过多"
+
+
+def test_sync_no_overlap_allowed():
+    """
+    测试同步模式下的并发：
+    允许重叠时，即使任务慢，触发点到了也应该立即启动新线程。
+    """
+    cron = FastCron()
+    execution_counter = 0
+    lock = threading.Lock()
+
+    @cron.schedule("* * * * * *", allow_overlap=True)
+    def slow_concurrent_task():
+        nonlocal execution_counter
+        with lock:
+            execution_counter += 1
+        time.sleep(2)
+
+    cron_thread = threading.Thread(target=cron.run, daemon=True)
+    cron_thread.start()
+
+    time.sleep(2.5)
+    cron._running = False
+
+    # 允许重叠，2.5秒内应该触发 2-3 次
+    with lock:
+        assert execution_counter >= 2