matrix-planner 0.1.0__tar.gz

matrix_planner-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

matrix_planner-0.1.0/.gitignore

@@ -0,0 +1,168 @@
+# Personal / local
+uv.lock
+agents.md
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+

matrix_planner-0.1.0/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.

matrix_planner-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+# 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/examples/example.py

@@ -0,0 +1,212 @@
+"""Comprehensive examples covering all matrix-planner features."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timedelta, timezone
+
+from matrix_planner import (
+    CronSchedule,
+    IntervalSchedule,
+    OnceSchedule,
+    Planner,
+    Task,
+    cron,
+    every,
+    once,
+)
+
+# ---------------------------------------------------------------------------
+# 1. Basic interval — sync function
+# ---------------------------------------------------------------------------
+
+planner = Planner()
+
+
+@planner.task(every("2s"))
+def heartbeat() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] heartbeat (sync)")
+
+
+# ---------------------------------------------------------------------------
+# 2. Async function with exponential backoff and per-execution timeout
+# ---------------------------------------------------------------------------
+
+
+@planner.task(
+    every("3s"),
+    max_retries=3,
+    backoff=lambda a: 2 ** a,  # 2, 4, 8… seconds between retries
+    timeout="1.5s",            # kill if a single run exceeds 1.5s
+)
+async def fetch_status() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] fetch_status started")
+    await asyncio.sleep(0.2)
+    print(f"[{datetime.now():%H:%M:%S}] fetch_status done")
+
+
+# ---------------------------------------------------------------------------
+# 3. Cron schedule — fires at specific wall-clock times
+# ---------------------------------------------------------------------------
+
+planner2 = Planner()
+
+
+@planner2.task(cron("*/1 * * * * *"))  # every minute, at second 0
+async def every_minute() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] cron tick")
+
+
+# ---------------------------------------------------------------------------
+# 4. Once schedule — fires a single time
+# ---------------------------------------------------------------------------
+
+
+def startup_message() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] startup: one-time task")
+
+
+planner.add(
+    Task(
+        func=startup_message,
+        schedule=once(datetime.now() + timedelta(seconds=3)),
+    )
+)
+
+
+# ---------------------------------------------------------------------------
+# 5. Interval with anchor="end" — delay measured from execution end
+# ---------------------------------------------------------------------------
+
+planner3 = Planner()
+
+
+@planner3.task(IntervalSchedule(every="2s", anchor="end"))
+async def poll() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] poll (2s after previous finished)")
+
+
+# ---------------------------------------------------------------------------
+# 6. on_error callback — intercept exceptions instead of logging
+# ---------------------------------------------------------------------------
+
+error_log: list[Exception] = []
+
+
+def collect_error(exc: Exception) -> None:
+    error_log.append(exc)
+
+
+@planner.task(every("4s"), max_retries=1, backoff=0.5, on_error=collect_error)
+async def flaky_task() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] flaky_task attempt")
+    raise ValueError("something went wrong")
+
+
+# ---------------------------------------------------------------------------
+# 7. Direct task invocation (bypasses scheduler — useful in tests)
+# ---------------------------------------------------------------------------
+
+
+def add(a: int, b: int) -> int:
+    return a + b
+
+
+direct_task = Task(func=add, schedule=every("10s"), args=(2, 3))
+assert direct_task() == 5
+print(f"[{datetime.now():%H:%M:%S}] direct call: add(2, 3) = {direct_task()}")
+
+
+# ---------------------------------------------------------------------------
+# 8. Fixed backoff (same as old retry_delay)
+# ---------------------------------------------------------------------------
+
+
+@planner.task(every("5s"), max_retries=2, backoff=1.0)
+def cleanup() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] cleanup (fixed 1s backoff)")
+
+
+# ---------------------------------------------------------------------------
+# 9. Custom backoff with cap
+# ---------------------------------------------------------------------------
+
+
+@planner.task(every("6s"), max_retries=4, backoff=lambda a: min(2 ** a, 10))
+async def capped_backoff() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] capped backoff demo")
+    raise RuntimeError("simulated")
+
+
+# ---------------------------------------------------------------------------
+# 10. Using all explicit schedule classes without factory helpers
+# ---------------------------------------------------------------------------
+
+planner4 = Planner()
+
+planner4.add(
+    Task(
+        func=lambda: print("explicit IntervalSchedule"),
+        schedule=IntervalSchedule(every="3s"),
+    )
+)
+
+planner4.add(
+    Task(
+        func=lambda: print("explicit CronSchedule"),
+        schedule=CronSchedule(expr="*/2 * * * * *"),
+    )
+)
+
+planner4.add(
+    Task(
+        func=lambda: print("explicit OnceSchedule"),
+        schedule=OnceSchedule(at=datetime.now(timezone.utc) + timedelta(seconds=5)),
+    )
+)
+
+
+# ---------------------------------------------------------------------------
+# 11. Timeout variants
+# ---------------------------------------------------------------------------
+
+
+@planner.task(every("3s"), timeout=timedelta(seconds=1))
+async def timeout_timedelta() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] timeout with timedelta")
+    await asyncio.sleep(0.1)
+
+
+@planner.task(every("4s"), timeout=2.0)
+async def timeout_float() -> None:
+    print(f"[{datetime.now():%H:%M:%S}] timeout with float")
+    await asyncio.sleep(0.1)
+
+
+# ---------------------------------------------------------------------------
+# Run demo (stop after 10 seconds)
+# ---------------------------------------------------------------------------
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s:%(name)s:%(message)s")
+
+
+async def run_all() -> None:
+    tasks = [
+        asyncio.create_task(planner.run()),
+        asyncio.create_task(planner2.run()),
+        asyncio.create_task(planner3.run()),
+        asyncio.create_task(planner4.run()),
+    ]
+
+    try:
+        await asyncio.wait_for(asyncio.gather(*tasks), timeout=10)
+    except asyncio.TimeoutError:
+        for p in (planner, planner2, planner3, planner4):
+            await p.stop()
+
+    print(f"Error log entries: {len(error_log)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(run_all())

matrix_planner-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matrix-planner"
+version = "0.1.0"
+description = "Lightweight async task scheduler"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { file = "LICENSE" }
+authors = [
+    { name = "dotmatrix" },
+]
+dependencies = [
+    "croniter>=6.2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/matrixd0t/matrix-planner"
+Repository = "https://github.com/matrixd0t/matrix-planner"

matrix_planner-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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})"