python-library-scheduler 0.1.1__py3-none-any.whl

python_library_scheduler-0.1.1.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: python-library-scheduler
+Version: 0.1.1
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.12.5

python_library_scheduler-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+scheduler/__init__.py,sha256=XkjAnTIAJxvC4rr8G55UJ0ObcNsC6SPznMEIAQ4ax34,87
+scheduler/at.py,sha256=97gnzAJKoivqeVTsiN3CIgfK81Q0b8QUCscuVSwWv_0,1317
+scheduler/base.py,sha256=ZYWbsQDE1_GKVwmxboLWg6oJeHvRzJ4j0wAF1bedfUs,3952
+scheduler/every.py,sha256=uDKKQG8lYkiU6Xpf4wtUddDuNDo5XPhy60iYQ3qxIuA,1171
+python_library_scheduler-0.1.1.dist-info/METADATA,sha256=-o5XDa6rOpq3Qts62mVcLrMuX3J175uVzbLtPFvnW5I,124
+python_library_scheduler-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_library_scheduler-0.1.1.dist-info/RECORD,,

python_library_scheduler-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scheduler/__init__.py

@@ -0,0 +1,7 @@
+from .at import At
+from .every import Every
+
+__all__ = [
+    "At",
+    "Every",
+]

scheduler/at.py

@@ -0,0 +1,44 @@
+from datetime import datetime, timedelta
+
+from pydantic import Field
+
+from .base import BaseScheduler
+
+
+class At(BaseScheduler):
+    hour: int = Field(0, ge=0, le=23, description="小时")
+    minute: int = Field(0, ge=0, le=59, description="分钟")
+    second: int = Field(0, ge=0, le=59, description="秒")
+    weekday: int | None = Field(None, ge=0, le=6, description="星期几 (0=周一, 6=周日)")
+
+    def _next_target(self, now: datetime) -> datetime:
+        target = now.replace(
+            hour=self.hour,
+            minute=self.minute,
+            second=self.second,
+            microsecond=0,
+        )
+
+        if self.weekday is None:
+            if target <= now:
+                target += timedelta(days=1)
+            return target
+
+        days = (self.weekday - now.weekday()) % 7
+        if days == 0 and target <= now:
+            days = 7
+
+        return target + timedelta(days=days)
+
+    def _next_delay(self) -> float:
+        now = datetime.now()
+        return max((self._next_target(now) - now).total_seconds(), 0)
+
+    def _condition(self) -> bool:
+        now = datetime.now()
+        last = self._last_fire_at
+        if last is None:
+            return False
+
+        target = self._next_target(last)
+        return last < target <= now

scheduler/base.py

@@ -0,0 +1,128 @@
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Callable, Any
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, model_validator
+
+Handler = Callable[[], Any]
+
+logger = logging.getLogger(__name__)
+
+
+class BaseScheduler(BaseModel, ABC):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="forbid",
+        validate_assignment=True,
+    )
+
+    immediate: bool = Field(False, description="是否立即执行")
+    max_runs: int | None = Field(None,description="最大触发次数，不填则表示不限制")
+
+    _handlers: list[Handler] = PrivateAttr(default_factory=list)
+    _runner_task: asyncio.Task | None = PrivateAttr(None)
+    _stop_event: asyncio.Event = PrivateAttr(default_factory=asyncio.Event)
+    _running: bool = PrivateAttr(False)
+    _last_fire_at: datetime | None = PrivateAttr(None)
+    _run_count: int = PrivateAttr(0)
+    _first_tick: bool = PrivateAttr(True)
+
+    @model_validator(mode="after")
+    def _validate_max_runs(self):
+        if self.max_runs is not None and self.max_runs < 1:
+            raise ValueError("max_runs must be >= 1 when set")
+        return self
+
+    def _next_delay(self) -> float:
+        """距离下次触发的推荐等待秒数，子类可覆盖以实现动态间隔"""
+        return 0.5
+
+    def add(self, fn: Handler):
+        self._handlers.append(fn)
+        return fn
+
+    def __call__(self, fn: Handler):
+        return self.add(fn)
+
+    async def start(self):
+        if self._runner_task and not self._runner_task.done():
+            return self
+
+        loop = asyncio.get_running_loop()
+        self._stop_event.clear()
+        self._first_tick = True
+        self._run_count = 0
+        self._last_fire_at = None if self.immediate else datetime.now()
+        self._runner_task = loop.create_task(self._serve())
+        return self
+
+    async def wait(self):
+        if self._runner_task is None:
+            raise RuntimeError("scheduler has not been started")
+        await self._runner_task
+        return self
+
+    async def stop(self):
+        self._stop_event.set()
+        return self
+
+    async def run(self):
+        await self.start()
+        await self.wait()
+        return self
+
+    async def _serve(self):
+        self._running = True
+        try:
+            while not self._stop_event.is_set():
+                if self._should_fire():
+                    await self._fire_all()
+
+                self._first_tick = False
+
+                delay = max(self._next_delay(), 0.1)
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(),
+                        timeout=delay,
+                    )
+                except asyncio.TimeoutError:
+                    pass
+        finally:
+            self._running = False
+
+    def _should_fire(self) -> bool:
+        if not self._handlers:
+            return False
+
+        if self._first_tick:
+            return self.immediate
+
+        return self._condition()
+
+    async def _fire_all(self):
+        self._last_fire_at = datetime.now()
+        self._run_count += 1
+
+        results = await asyncio.gather(
+            *(self._invoke(fn) for fn in self._handlers),
+            return_exceptions=True,
+        )
+
+        for fn, result in zip(self._handlers, results):
+            if isinstance(result, Exception):
+                logger.exception("scheduler handler failed: %r", fn, exc_info=result)
+
+        if self.max_runs is not None and self._run_count >= self.max_runs:
+            self._stop_event.set()
+
+    async def _invoke(self, fn: Handler):
+        if asyncio.iscoroutinefunction(fn):
+            await fn()
+        else:
+            await asyncio.to_thread(fn)
+
+    @abstractmethod
+    def _condition(self) -> bool: ...

scheduler/every.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from pydantic import Field, model_validator
+
+from .base import BaseScheduler
+
+
+class Every(BaseScheduler):
+    seconds: float = Field(0, ge=0, description="秒")
+    minutes: float = Field(0, ge=0, description="分钟")
+    hours: float = Field(0, ge=0, description="小时")
+    days: float = Field(0, ge=0, description="天")
+
+    @model_validator(mode="after")
+    def _validate_period(self):
+        if self.period <= 0:
+            raise ValueError("Every period must be greater than 0")
+        return self
+
+    @property
+    def period(self) -> float:
+        return (
+            self.seconds
+            + self.minutes * 60
+            + self.hours * 3600
+            + self.days * 86400
+        )
+
+    def _next_delay(self) -> float:
+        if self._last_fire_at is None:
+            return 0
+        elapsed = (datetime.now() - self._last_fire_at).total_seconds()
+        return max(self.period - elapsed, 0)
+
+    def _condition(self) -> bool:
+        if self._last_fire_at is None:
+            return False
+        return (datetime.now() - self._last_fire_at).total_seconds() >= self.period