faster-cron 0.1.1__py3-none-any.whl

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/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/base.py

@@ -0,0 +1,93 @@
+import datetime
+import logging
+
+
+class CronBase:
+    """提供符合标准 Cron 规范的解析逻辑"""
+
+    @staticmethod
+    def is_time_match(expression: str, now: datetime.datetime) -> bool:
+        """
+        判断当前时间是否匹配 Cron 表达式
+        逻辑参考标准 Unix Cron：当日期和星期同时被指定时，采用 OR 关系。
+        """
+        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
+
+        # 1. 转换星期逻辑 (Python 0=Mon, 6=Sun -> Cron 0或7=Sun, 1=Mon...)
+        # 转换公式：(now.weekday() + 1) % 7 -> 结果 0=Sun, 1=Mon, ..., 6=Sat
+        cron_weekday = (now.weekday() + 1) % 7
+
+        try:
+            # 2. 基础字段匹配
+            sec_match = CronBase._match_field(sec_part, now.second)
+            min_match = CronBase._match_field(min_part, now.minute)
+            hour_match = CronBase._match_field(hour_part, now.hour)
+            month_match = CronBase._match_field(month_part, now.month)
+
+            day_matches = CronBase._match_field(day_part, now.day)
+            weekday_matches = CronBase._match_field(weekday_part, cron_weekday)
+
+            # 3. 处理 Day 和 Weekday 的特殊关系 (Standard Cron Logic)
+            # 如果两个字段都有限制（不是 *），则为 OR 关系；否则为 AND 关系。
+            day_is_star = (day_part == "*")
+            weekday_is_star = (weekday_part == "*")
+
+            if not day_is_star and not weekday_is_star:
+                day_weekday_ok = (day_matches or weekday_matches)
+            else:
+                day_weekday_ok = (day_matches and weekday_matches)
+
+            return (
+                    sec_match and
+                    min_match and
+                    hour_match and
+                    month_match and
+                    day_weekday_ok
+            )
+        except Exception:
+            # 如果表达式解析失败（如格式错误），返回 False 避免程序崩溃
+            return False
+
+    @staticmethod
+    def _match_field(pattern: str, value: int) -> bool:
+        """解析单个 Cron 字段"""
+        if pattern == "*":
+            return True
+
+        # 处理列表: "1,2,3"
+        if "," in pattern:
+            return any(CronBase._match_field(p, value) for p in pattern.split(","))
+
+        # 处理步长: "*/5" 或 "1-10/2"
+        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
+            # 固定点开始的步长: "5/10"
+            return value >= int(r) and (value - int(r)) % step == 0
+
+        # 处理范围: "10-20"
+        if "-" in pattern:
+            start, end = map(int, pattern.split("-"))
+            return start <= value <= end
+
+        # 处理精确数值: "5"
+        try:
+            target_val = int(pattern)
+            # 兼容性处理：Cron 中 7 经常作为周日的另一种写法
+            if target_val == 7:
+                target_val = 0
+            return target_val == value
+        except ValueError:
+            return False

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.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: faster-cron
+Version: 0.1.1
+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
+
+[English](./README_EN.md) | 中文版
+
+**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.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+faster_cron/__init__.py,sha256=9TQeFkow--g4AlkZpemak_vODrkQI6E2zIrbIdgDg80,243
+faster_cron/async_cron.py,sha256=VMD5BqagBvbfhKI4Eo_T1nyYUlcpdmCEKYwnfoLETeE,2084
+faster_cron/base.py,sha256=lIK0kOnt33DD_H9bXT0pEONbPZthBzinivETbrek5EM,3525
+faster_cron/sync_cron.py,sha256=xbyRDJFo2wUvpmlXI9VB6UWUet3mZngHd5XRrTOKR3k,3775
+faster_cron-0.1.1.dist-info/METADATA,sha256=3kMUQMDawwuDKvfPM8beqswm6SK6GPc7I0DpujCw0BQ,4004
+faster_cron-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+faster_cron-0.1.1.dist-info/top_level.txt,sha256=lQbktVSdGKKyocrLDqk8V_bFLBuWML4squauwEdZuik,12
+faster_cron-0.1.1.dist-info/RECORD,,

faster_cron-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

faster_cron-0.1.1.dist-info/top_level.txt

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