python-library-scheduler 0.1.1__tar.gz

python_library_scheduler-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+config.yaml
+logs/

python_library_scheduler-0.1.1/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,12 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-scheduler"
+version = "0.1.1"
+requires-python = ">=3.10"
+dependencies = ["pydantic>=2.12.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["scheduler"]

python_library_scheduler-0.1.1/scheduler/__init__.py

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

python_library_scheduler-0.1.1/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

python_library_scheduler-0.1.1/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: ...

python_library_scheduler-0.1.1/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

python_library_scheduler-0.1.1/test.bat

@@ -0,0 +1,10 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+python -m unittest discover -s tests -p "test_*.py"

python_library_scheduler-0.1.1/tests/test_scheduler.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import asyncio
+import unittest
+from datetime import datetime
+from pydantic import ValidationError
+
+from scheduler import At, Every
+
+
+class EveryTests(unittest.IsolatedAsyncioTestCase):
+    async def test_every_immediate_max_runs_stops_scheduler(self) -> None:
+        runs: list[int] = []
+
+        sch = Every(seconds=0.01, immediate=True, max_runs=2)
+        sch.add(lambda: runs.append(1))
+
+        await asyncio.wait_for(sch.run(), timeout=5.0)
+
+        self.assertEqual(len(runs), 2)
+
+    async def test_every_decorator_registers_handler(self) -> None:
+        runs: list[int] = []
+
+        sch = Every(seconds=0.01, immediate=True, max_runs=1)
+
+        @sch
+        def tick() -> None:
+            runs.append(1)
+
+        await asyncio.wait_for(sch.run(), timeout=5.0)
+
+        self.assertEqual(runs, [1])
+
+    async def test_async_handler(self) -> None:
+        runs: list[int] = []
+
+        sch = Every(seconds=0.01, immediate=True, max_runs=1)
+
+        async def tick() -> None:
+            runs.append(1)
+
+        sch.add(tick)
+        await asyncio.wait_for(sch.run(), timeout=5.0)
+
+        self.assertEqual(runs, [1])
+
+    async def test_stop(self) -> None:
+        runs: list[int] = []
+        sch = Every(seconds=0.01, immediate=True)
+
+        sch.add(lambda: runs.append(1))
+
+        await sch.start()
+        await asyncio.sleep(0.25)
+        await sch.stop()
+        await sch.wait()
+
+        self.assertGreaterEqual(len(runs), 1)
+
+    async def test_wait_without_start_raises(self) -> None:
+        sch = Every(seconds=1)
+        with self.assertRaises(RuntimeError) as ctx:
+            await sch.wait()
+        self.assertIn("not been started", str(ctx.exception).lower())
+
+    def test_every_zero_period_rejected(self) -> None:
+        with self.assertRaises(ValidationError):
+            Every()
+
+    def test_max_runs_invalid(self) -> None:
+        with self.assertRaises(ValidationError):
+            Every(seconds=1, max_runs=0)
+
+    def test_forbid_unknown_fields(self) -> None:
+        with self.assertRaises(ValidationError):
+            Every(seconds=1, not_a_field=True)  # type: ignore[call-arg]
+
+
+class AtNextTargetTests(unittest.TestCase):
+    def test_same_day_later(self) -> None:
+        sch = At(hour=15, minute=30, second=0)
+        now = datetime(2025, 6, 1, 10, 0, 0)
+        self.assertEqual(
+            sch._next_target(now),
+            datetime(2025, 6, 1, 15, 30, 0),
+        )
+
+    def test_rolls_to_next_calendar_day(self) -> None:
+        sch = At(hour=9, minute=0, second=0)
+        now = datetime(2025, 6, 1, 10, 0, 0)
+        self.assertEqual(
+            sch._next_target(now),
+            datetime(2025, 6, 2, 9, 0, 0),
+        )
+
+    def test_weekday_same_day_still_future(self) -> None:
+        sch = At(hour=12, minute=0, second=0, weekday=0)
+        now = datetime(2025, 1, 6, 8, 0, 0)
+        self.assertEqual(now.weekday(), 0)
+        self.assertEqual(
+            sch._next_target(now),
+            datetime(2025, 1, 6, 12, 0, 0),
+        )
+
+    def test_weekday_same_day_already_passed(self) -> None:
+        sch = At(hour=10, minute=0, second=0, weekday=0)
+        now = datetime(2025, 1, 6, 15, 0, 0)
+        self.assertEqual(
+            sch._next_target(now),
+            datetime(2025, 1, 13, 10, 0, 0),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()