matrix-planner 0.1.0__py3-none-any.whl

matrix_planner/__init__.py

@@ -0,0 +1,33 @@
+"""matrix-planner: a lightweight async task scheduler."""
+
+from __future__ import annotations
+
+from .schedules import (
+    CronSchedule,
+    ExecutionTime,
+    IntervalSchedule,
+    MonotonicExecutionTime,
+    OnceSchedule,
+    Schedule,
+    WallClockExecutionTime,
+    interval_seconds,
+)
+from .task import Task
+from .planner import Planner
+from .decorators import every, cron, once
+
+__all__ = [
+    "Schedule",
+    "IntervalSchedule",
+    "CronSchedule",
+    "OnceSchedule",
+    "ExecutionTime",
+    "MonotonicExecutionTime",
+    "WallClockExecutionTime",
+    "interval_seconds",
+    "Task",
+    "Planner",
+    "every",
+    "cron",
+    "once",
+]

matrix_planner/decorators.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, tzinfo
+from typing import Literal
+
+from .schedules import CronSchedule, IntervalSchedule, OnceSchedule
+
+
+def every(
+    value: str | timedelta | float | int,
+    *,
+    anchor: Literal["start", "end"] = "start",
+) -> IntervalSchedule:
+    """Create an IntervalSchedule.
+
+    Usage: every("10s"), every("5m"), every(timedelta(hours=1)).
+    """
+    return IntervalSchedule(every=value, anchor=anchor)
+
+
+def cron(expr: str, *, tz: tzinfo | None = None) -> CronSchedule:
+    """Create a CronSchedule from a cron expression.
+
+    Usage: cron("*/5 * * * *"), cron("0 9 * * 1-5", tz=timezone.utc).
+    """
+    return CronSchedule(expr=expr, tz=tz)
+
+
+def once(at: datetime) -> OnceSchedule:
+    """Create a OnceSchedule that fires at the given datetime.
+
+    Usage: once(datetime(2026, 12, 31, 23, 59)).
+    """
+    return OnceSchedule(at=at)

matrix_planner/planner.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+from typing import Callable
+
+from .schedules import Schedule, interval_seconds
+from .task import Task
+
+logger = logging.getLogger("planner")
+
+
+class Planner:
+    """Lightweight async task scheduler.
+
+    Each registered task runs in its own coroutine:
+        for deadline in task.schedule:
+            sleep(deadline.delay())
+            execute(task)
+
+    Sync functions are offloaded to the default executor to avoid
+    blocking the event loop; async functions are awaited directly.
+    """
+
+    def __init__(self) -> None:
+        self._tasks: list[Task] = []
+        self._runners: list[asyncio.Task] = []
+        self._running = False
+
+    # -- registration ---------------------------------------------------
+
+    def add(self, task: Task) -> Task:
+        """Register a task. Returns the task for chaining."""
+        self._tasks.append(task)
+        return task
+
+    def task(self, schedule: Schedule, **opts) -> Callable[[Callable], Task]:
+        """Decorator shortcut that registers a function as a task.
+
+        @planner.task(every("10s"))
+        def heartbeat(): ...
+        """
+
+        def decorator(func: Callable) -> Task:
+            t = Task(func=func, schedule=schedule, **opts)
+            self.add(t)
+            return t
+
+        return decorator
+
+    # -- lifecycle ------------------------------------------------------
+
+    async def run(self) -> None:
+        """Start all registered tasks and wait until they finish."""
+        if self._running:
+            raise RuntimeError("Planner is already running")
+
+        self._running = True
+        self._runners = [
+            asyncio.create_task(self._run_task(t), name=t.name)
+            for t in self._tasks
+        ]
+
+        try:
+            await asyncio.gather(*self._runners)
+        finally:
+            self._running = False
+
+    def run_forever(self) -> None:
+        """Sync entry point: calls asyncio.run(self.run()) and handles Ctrl+C."""
+        try:
+            asyncio.run(self.run())
+        except KeyboardInterrupt:
+            pass
+
+    async def stop(self) -> None:
+        """Cancel all running tasks and wait for them to finish."""
+        self._running = False
+        for runner in self._runners:
+            runner.cancel()
+        if self._runners:
+            await asyncio.gather(*self._runners, return_exceptions=True)
+        self._runners.clear()
+
+    # -- internals ------------------------------------------------------
+
+    async def _run_task(self, task: Task) -> None:
+        """Execute task on every deadline from its schedule."""
+        for deadline in task.schedule:
+            if not self._running:
+                return
+
+            delay = deadline.delay()
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+            if not self._running:
+                return
+
+            await self._execute(task)
+
+    async def _execute(self, task: Task) -> None:
+        """Call the task function with timeout and retry logic."""
+        attempt = 0
+
+        while True:
+            try:
+                if task.is_async:
+                    coro = task.func(*task.args, **task.kwargs)  # noqa
+                else:
+                    loop = asyncio.get_running_loop()
+                    coro = loop.run_in_executor(
+                        None,
+                        functools.partial(task.func, *task.args, **task.kwargs),
+                    )
+
+                if task.timeout is not None:
+                    coro = asyncio.wait_for(coro, timeout=interval_seconds(task.timeout))
+
+                await coro
+                return
+
+            except asyncio.TimeoutError:
+                logger.warning("Task %r timed out", task.name)
+                return
+
+            except Exception as exc:
+                attempt += 1
+
+                if task.on_error is not None:
+                    task.on_error(exc)
+                elif attempt > task.max_retries:
+                    logger.exception("Task %r failed", task.name)
+
+                if attempt > task.max_retries:
+                    return
+
+                delay = task.backoff(attempt) if callable(task.backoff) else task.backoff
+                if delay:
+                    await asyncio.sleep(delay)

matrix_planner/schedules.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import time
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, tzinfo
+from typing import Iterator, Literal, Protocol
+
+from croniter import croniter
+
+
+def interval_seconds(value: str | timedelta | float | int) -> float:
+    """Convert an interval specification to seconds."""
+    if isinstance(value, timedelta):
+        seconds = value.total_seconds()
+
+    elif isinstance(value, (int, float)):
+        seconds = float(value)
+
+    elif isinstance(value, str):
+        unit = value[-1]
+        factor = {
+            "s": 1,
+            "m": 60,
+            "h": 3600,
+            "d": 86400,
+        }.get(unit)
+
+        if factor is None:
+            raise ValueError(
+                f"Invalid interval '{value!r}'. Expected something like '10s', '5m', '2h', '7d'."
+            )
+
+        seconds = float(value[:-1]) * factor
+
+    else:
+        raise TypeError(f"Unsupported interval type: {type(value)!r}")
+
+    if seconds <= 0:
+        raise ValueError("Interval must be greater than zero.")
+
+    return seconds
+
+
+# ---------------------------------------------------------------------------
+# Execution time abstraction
+# ---------------------------------------------------------------------------
+
+
+class ExecutionTime(Protocol):
+    """Protocol for objects that know when to fire next."""
+
+    def delay(self) -> float:
+        """Seconds until the deadline is reached."""
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class MonotonicExecutionTime:
+    """Deadline based on time.monotonic(). Suitable for interval schedules."""
+
+    when: float
+
+    def delay(self) -> float:
+        return max(0.0, self.when - time.monotonic())
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class WallClockExecutionTime:
+    """Deadline based on datetime. Suitable for cron / once schedules."""
+
+    when: datetime
+
+    def delay(self) -> float:
+        return max(
+            0.0,
+            (self.when - datetime.now(self.when.tzinfo)).total_seconds(),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Base schedule
+# ---------------------------------------------------------------------------
+
+
+class Schedule(ABC, Iterator[ExecutionTime]):
+    """Stateful iterator over future dispatch deadlines."""
+
+    def __iter__(self) -> Schedule:
+        return self
+
+    @abstractmethod
+    def __next__(self) -> ExecutionTime:
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Interval
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True, kw_only=True)
+class IntervalSchedule(Schedule):
+    """Schedule that fires at fixed intervals.
+
+    anchor="start" — first tick happens *interval* after creation,
+                     subsequent ticks follow the same cadence.
+    anchor="end"   — interval is measured from the end of each execution
+                     (genuine fixed delay).
+    """
+
+    every: str | timedelta | float | int
+    anchor: Literal["start", "end"] = "start"
+
+    _seconds: float = field(init=False)
+    _next: float | None = field(init=False, default=None)
+
+    def __post_init__(self) -> None:
+        self._seconds = interval_seconds(self.every)
+
+        if self.anchor not in ("start", "end"):
+            raise ValueError("anchor must be 'start' or 'end'")
+
+    # noinspection PyTypeChecker
+    def __next__(self) -> ExecutionTime:
+        now = time.monotonic()
+        if self.anchor == "end":
+            return MonotonicExecutionTime(
+                when=now + self._seconds,
+            )
+
+        if self._next is None:
+            self._next = now + self._seconds
+        else:
+            self._next += self._seconds
+
+        return MonotonicExecutionTime(
+            when=self._next,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Cron
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True, kw_only=True)
+class CronSchedule(Schedule):
+    """Schedule that fires at wall-clock times matching a cron expression."""
+
+    expr: str
+    tz: tzinfo | None = None
+
+    _next: datetime | None = field(init=False, default=None)
+
+    def __next__(self) -> ExecutionTime:
+
+        if self._next is None:
+            base = datetime.now(self.tz)
+        else:
+            base = self._next
+
+        self._next = croniter(
+            self.expr,
+            base,
+        ).get_next(datetime)
+
+        return WallClockExecutionTime(
+            when=self._next,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Once
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True, kw_only=True)
+class OnceSchedule(Schedule):
+    """Schedule that fires exactly once at a given datetime."""
+
+    at: datetime
+
+    _done: bool = field(init=False, default=False)
+
+    def __next__(self) -> ExecutionTime:
+
+        if self._done:
+            raise StopIteration
+
+        self._done = True
+
+        return WallClockExecutionTime(
+            when=self.at,
+        )

matrix_planner/task.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any
+
+from .schedules import Schedule
+
+BackoffValue = float | int | Callable[[int], float]
+
+
+@dataclass(slots=True, kw_only=True)
+class Task:
+    """Function bound to a schedule.
+
+    Task does not run itself — the scheduler does that. Task only
+    describes *what* to call, *with what arguments*, and *how to
+    react to failures*.
+    """
+
+    func: Callable[..., Any]
+    schedule: Schedule
+    name: str | None = None
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+
+    # Retry policy for exceptions raised inside func.
+    max_retries: int = 0
+    backoff: BackoffValue = 0.0
+
+    # If set, exceptions are forwarded here instead of being re-raised.
+    on_error: Callable[[Exception], None] | None = None
+
+    # Per-execution timeout. Accepts 15, timedelta(seconds=15), "15s", etc.
+    timeout: str | timedelta | float | int | None = None
+
+    def __post_init__(self) -> None:
+        if self.name is None:
+            self.name = getattr(self.func, "__name__", repr(self.func))
+
+    @property
+    def is_async(self) -> bool:
+        """True if the wrapped function is a coroutine function."""
+        return inspect.iscoroutinefunction(self.func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the task function directly, bypassing the scheduler."""
+        return self.func(*(args or self.args), **(kwargs or self.kwargs))
+
+    def __repr__(self) -> str:
+        return f"Task(name={self.name!r}, schedule={self.schedule!r})"

matrix_planner-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: matrix-planner
+Version: 0.1.0
+Summary: Lightweight async task scheduler
+Project-URL: Homepage, https://github.com/matrixd0t/matrix-planner
+Project-URL: Repository, https://github.com/matrixd0t/matrix-planner
+Author: dotmatrix
+License: MIT License
+        
+        Copyright (c) 2026
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: croniter>=6.2.3
+Description-Content-Type: text/markdown
+
+# matrix-planner
+
+Lightweight async task scheduler for Python 3.13+. Single dependency: `croniter`.
+
+```python
+import asyncio
+from matrix_planner import Planner, every
+
+planner = Planner()
+
+
+@planner.task(every("10s"))
+def heartbeat() -> None:
+    print("tick")
+
+
+@planner.task(
+    every("30s"),
+    max_retries=3,
+    backoff=lambda a: 2 ** a,   # 2, 4, 8… seconds between retries
+    timeout="15s",               # cancel and log if execution exceeds 15s
+)
+async def fetch() -> None:
+    ...
+
+
+planner.run_forever()
+```
+
+## Key features
+
+| Feature | API |
+|---|---|
+| Fixed-interval schedule | `every("10s")`, `every(timedelta(minutes=5))` |
+| Cron schedule | `cron("*/5 * * * *")` |
+| One-shot schedule | `once(datetime(2026, 12, 31))` |
+| Decorator registration | `@planner.task(every("2s"))` |
+| Manual registration | `planner.add(Task(func=..., schedule=...))` |
+| Retry policy | `max_retries=N`, `backoff=float \| Callable[[int], float]` |
+| Per-execution timeout | `timeout="15s" \| timedelta \| float` |
+| Error callback | `on_error=my_handler` |
+| Sync + async functions | sync dispatched via `run_in_executor` |
+| Direct task invocation | `task()` bypasses scheduler (useful in tests) |
+| `anchor="start"` | first tick *interval* after creation, steady cadence |
+| `anchor="end"` | interval measured from end of each execution |
+
+## Schedules
+
+```python
+# Every 10 seconds (first tick after 10s from now)
+s = every("10s")
+
+# Every 5 minutes, anchored to end of execution
+s = every("5m", anchor="end")
+
+# Cron expression (fires at 09:00 every weekday)
+s = cron("0 9 * * 1-5")
+
+# Cron with timezone
+s = cron("0 9 * * *", tz=timezone.utc)
+
+# Fire once at a specific datetime
+s = once(datetime(2026, 12, 31, 23, 59))
+```
+
+## Task parameters
+
+```python
+Task(
+    func=my_fn,
+    schedule=every("10s"),
+    name="my-task",              # defaults to func.__name__
+    args=(1, 2),
+    kwargs={"key": "val"},
+    max_retries=2,
+    backoff=1.0,                 # fixed delay, or lambda a: 2 ** a
+    timeout="15s",               # None = no limit
+    on_error=lambda e: ...,      # called instead of logging on failure
+)
+```
+
+## Requirements
+
+Python 3.13+. Single dependency: `croniter>=6.2.3`.
+
+Install: `uv add matrix-planner` or `pip install matrix-planner`.
+
+---
+
+Written with love by dotmatrix.

matrix_planner-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+matrix_planner/__init__.py,sha256=Obd5pNdkL7xBkhqoG67Daegyw7o0tjcOSKvPZKYTBto,649
+matrix_planner/decorators.py,sha256=WprTORIW6Ul7PsHyqpmRZqO5j6NXqCiPaLjZbk5_Myw,914
+matrix_planner/planner.py,sha256=y4PUwakNpQfYXE3ZfVnLKsnutq0Jxe4-_JktXzzQgBc,4297
+matrix_planner/schedules.py,sha256=uqTxrzKmRkLPUnvSbV6BUohDajTZXOyY2htWhfgyo_I,5204
+matrix_planner/task.py,sha256=6t7R9rWOEvA74PgFFV1hu9zoZKmSGmPlLjFOHfUEX-Q,1664
+matrix_planner-0.1.0.dist-info/METADATA,sha256=GeKDQqLKhRSK-ZhSPgJTuBMh1e7EV-uuxqimLwKwRno,3904
+matrix_planner-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+matrix_planner-0.1.0.dist-info/licenses/LICENSE,sha256=JuDRkpJ1tG2YXCjsW0iF9Ob8IH0K2Sd3c9WMTBPfO7o,1055
+matrix_planner-0.1.0.dist-info/RECORD,,

matrix_planner-0.1.0.dist-info/WHEEL

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

matrix_planner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.