rust-py-scheduler

Lightweight, performant task scheduler for Python applications, with a Rust core.

Register interval-based jobs ("10s", "5m", "1h") or cron jobs ("0 9 * * 1-5") with a plain function call or a decorator, run them in-process or on a background thread, and inspect their state (run/error counts, last error, next run time) at any point — without a database or an external broker. First-class FastAPI, Django, and Celery integrations are included.

Features

Scheduler — simple API: every(), cron(), list_jobs(), remove_job(), run(), start_background(), shutdown()
Two ways to register a job — a direct call (scheduler.every("5s", fn)) or a decorator (@scheduler.every("5s")); both return the same registration
Interval scheduling — "10s", "5m", "1h" (seconds/minutes/hours)
Cron scheduling — standard 5-field Unix expressions, e.g. scheduler.cron("0 9 * * 1-5", fn) for weekdays at 9am
Framework integrations — start/stop with the app lifecycle on FastAPI and Django, and trigger Celery tasks on a schedule
Run in-process or in the background — block the calling thread with run(), or call start_background() to schedule on a dedicated OS thread and keep going
Per-job retries — max_retries=N retries a failing job up to N extra times, immediately, before counting it as an error
Jobs never crash the loop — an exception in one job is caught, printed, and tracked (error_count, last_error); every other job keeps running on schedule
Rust core — scheduling, timing, retries, and thread management run in Rust via PyO3; the Python API stays small and easy to read

Requirements

Python 3.10+
No required runtime dependencies (the extension is a self-contained native module, built for the stable ABI — one wheel works across 3.10–3.13+)

Installation

pip install rust-py-scheduler

With framework integrations:

pip install "rust-py-scheduler[fastapi]"   # FastAPI + uvicorn
pip install "rust-py-scheduler[django]"    # Django 4.2+
pip install "rust-py-scheduler[celery]"    # Celery

For running the test suite:

pip install "rust-py-scheduler[tests]"

Quick Start

import time

from rust_py_scheduler import Scheduler

scheduler = Scheduler()

# Direct call: registers immediately and returns the job id.
job_id = scheduler.every("2s", lambda: print("tick (direct call)"))


# Decorator form: same registration, but `report` stays a normal,
# directly-callable function afterwards.
@scheduler.every("3s", max_retries=2)
def report():
    print("tick (decorator, with retry budget)")


scheduler.start_background()  # returns immediately, runs on its own OS thread
time.sleep(7)

for job in scheduler.list_jobs():
    print(job)

scheduler.remove_job(job_id)
scheduler.shutdown()

See examples/basic_usage.py for the full, runnable version of this script.

Registering Jobs

scheduler.every("5s", my_function)                 # direct call
scheduler.every("5s", my_function, max_retries=3)   # with a retry budget

@scheduler.every("5s")                              # decorator
def my_function():
    ...

@scheduler.every("5s", max_retries=3)               # decorator, with retries
def my_function():
    ...

interval accepts an integer amount followed by s (seconds), m (minutes), or h (hours) — e.g. "30s", "5m", "2h". Anything else (empty, missing unit, zero, negative, non-numeric) raises ValueError immediately, when every() is called — not later, when the job would have run.
The decorator form always returns the original function unchanged (__name__, behavior, everything) — it's safe to keep calling it directly elsewhere in your code.
max_retries (default 0) works identically in both forms — see Error Handling & Retries.

Cron Scheduling

For calendar-based schedules ("every weekday at 9am", "top of every hour"), use cron() with a standard 5-field Unix expression. It has the exact same dual call/decorator API as every(), including max_retries.

scheduler.cron("0 * * * *", my_function)          # every hour, on the hour
scheduler.cron("*/15 * * * *", my_function)        # every 15 minutes

@scheduler.cron("0 9 * * 1-5")                     # weekdays at 9am
def morning_report():
    ...

@scheduler.cron("30 2 * * *", max_retries=2)       # daily at 02:30, with retries
def nightly_cleanup():
    ...

The five fields are minute hour day-of-month month day-of-week:

Field	Range	Notes
minute	`0–59`
hour	`0–23`
day of month	`1–31`
month	`1–12`
day of week	`0–7`	`0` and `7` both mean Sunday

Each field supports *, a single number (5), a range (9-17), a step (*/15, 9-17/2), and comma-separated lists of those (0,30, 9-11,17). When both day-of-month and day-of-week are restricted (neither is *), a time matches if either field matches — the same rule as Vixie cron.

Timezone: expressions are evaluated in the system's local timezone.
Resolution: cron has minute resolution; the smallest meaningful interval is one minute. For sub-minute schedules, use every("30s", ...).
An invalid expression (wrong field count, out-of-range value, bad syntax) raises ValueError immediately at registration, just like every().

Framework Integrations

FastAPI

Start the scheduler with the app and stop it on shutdown, via the modern lifespan API:

from fastapi import FastAPI
from rust_py_scheduler import Scheduler
from rust_py_scheduler.fastapi import scheduler_lifespan

scheduler = Scheduler()

@scheduler.every("30s")
def heartbeat():
    ...

app = FastAPI(lifespan=scheduler_lifespan(scheduler))

Already have a lifespan? Compose with it: scheduler_lifespan(scheduler, your_lifespan) — your startup runs after the scheduler is up, your shutdown before it stops. See examples/fastapi_example.py.

Django

Start the scheduler from your app's AppConfig.ready():

# apps.py
from django.apps import AppConfig
from rust_py_scheduler import Scheduler
from rust_py_scheduler.django import start_in_background

scheduler = Scheduler()

@scheduler.every("5m")
def refresh_cache():
    ...

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        start_in_background(scheduler)

start_in_background() is idempotent per process (calling ready() twice won't start a second thread) and registers a best-effort atexit shutdown for normal process exit.

Multi-worker note: under gunicorn/uwsgi with workers > 1, every worker process runs ready() and therefore its own scheduler — jobs run once per worker, with no cross-process coordination. For exactly-once cluster-wide scheduling, run the scheduler in a single dedicated process (e.g. a management command calling scheduler.run()). See examples/django_apps.py.

Celery

There's no rust_py_scheduler.celery module — and that's deliberate. A Celery task's .delay / .apply_async is just a callable, so the existing API schedules it with nothing new to learn:

@app.task
def send_report(name):
    ...

scheduler.every("5m", lambda: send_report.delay("daily-metrics"))
scheduler.cron("0 8 * * 1-5", lambda: send_report.delay("weekday-digest"))

# countdown/eta/routing? use apply_async:
scheduler.every("1h", lambda: send_report.apply_async(args=["hourly"], countdown=10))

The scheduler runs in your process and only enqueues messages; the Celery worker (a separate process) does the work — so Celery keeps owning retries, routing, and concurrency. See examples/celery_example.py.

Background Execution

scheduler.run()  # blocks the calling thread until shutdown() is called

scheduler.start_background()  # returns immediately; scheduling continues on a new OS thread
...
scheduler.shutdown()  # stops the loop and waits for the background thread to finish

run() releases the GIL while idle, so other Python threads (e.g. one calling shutdown()) keep running normally.
start_background() raises RuntimeError if called again while already running.
shutdown() is safe to call even if the scheduler was never started, and safe to call from inside a job callback. It is one-way: once stopped, a Scheduler can't be resumed — start a new one instead. This matches typical usage (start once at application startup, shut down once at teardown).

Inspecting and Removing Jobs

for job in scheduler.list_jobs():
    print(job)
# {'id': '...', 'name': 'report', 'schedule': 'every 3s', 'enabled': True,
#  'run_count': 4, 'error_count': 0, 'last_run_at': '1718721000',
#  'next_run_at': '1718721003', 'max_retries': 2, 'last_error': None}

scheduler.remove_job(job_id)  # raises KeyError if job_id doesn't exist

last_run_at/next_run_at are Unix timestamps (seconds since the epoch) as strings, or None if the job hasn't run yet.

Error Handling & Retries

A job that raises an exception never stops the scheduler or any other job — the traceback is printed to stderr, and the job's own error_count is incremented.

@scheduler.every("10s", max_retries=2)
def flaky():
    ...

max_retries=2 means up to 3 total attempts (the initial one + 2 retries) happen back-to-back, with no delay, before that scheduling tick is counted as a failure. run_count/error_count reflect ticks, not individual attempts: if any attempt within a tick succeeds, the whole tick counts as a success and last_error is cleared. Every failed attempt is still printed to stderr, even if a later attempt in the same tick succeeds.

Situation	Exception
Invalid `interval` passed to `every()`, or invalid cron `expression` passed to `cron()`	`ValueError`
`start_background()` called while already running	`RuntimeError`
`remove_job()` called with an unknown id	`KeyError`
Exception raised inside a job callback	Caught internally — never raised to your code

API Reference

`Scheduler()`

Creates a new, empty scheduler.

`scheduler.every(interval, callback=None, max_retries=0)`

Registers an interval job. Called with callback, registers immediately and returns the job id (str); called without it (as @scheduler.every(interval)), returns a decorator that registers the function it's applied to and hands it back unchanged. Raises ValueError on an invalid interval.

`scheduler.cron(expression, callback=None, max_retries=0)`

Registers a cron job from a 5-field Unix expression (minute hour day-of-month month day-of-week), evaluated in local time. Same dual call/decorator API and return values as every(). Raises ValueError on an invalid expression. See Cron Scheduling.

`scheduler.list_jobs() -> list[dict]`

Snapshot of every registered job.

Key	Type	Description
`id`	`str`	UUID v4
`name`	`str`	The callback's `__name__` (or `"job"` if it has none)
`schedule`	`str`	Human-readable, e.g. `"every 300s"` or `"cron 0 9 * * 1-5"`
`enabled`	`bool`	Always `True` for now (toggling is planned)
`run_count`	`int`	Successful ticks
`error_count`	`int`	Failed ticks (after exhausting retries)
`last_run_at`	`str \| None`	Unix timestamp of the last execution
`next_run_at`	`str \| None`	Unix timestamp of the next scheduled execution
`max_retries`	`int`	Configured retry budget
`last_error`	`str \| None`	Message from the most recent failed attempt; cleared on success

`scheduler.remove_job(job_id)`

Unregisters a job. Raises KeyError if job_id doesn't exist.

`scheduler.run()`

Blocks the calling thread, executing due jobs until shutdown() is called.

`scheduler.start_background()`

Runs the same loop as run() on a dedicated OS thread and returns immediately. Raises RuntimeError if already running.

`scheduler.shutdown()`

Stops the loop (background or not) and waits for the background thread to finish, if any. Safe to call multiple times, or when nothing was ever started.

Building from Source

Requires Rust and maturin.

python3 -m venv .venv
source .venv/bin/activate
pip install maturin

# Development build (installs into the current Python environment)
maturin develop

# Release wheel
maturin build --release

Running tests

# Rust unit tests
PYO3_PYTHON="$(pwd)/.venv/bin/python3" cargo test --no-default-features --lib

# Python integration tests
pip install -e ".[tests]"
pytest

Architecture

Python API (rust_py_scheduler)
    ├── Scheduler(...)               ──► src/scheduler.rs (PyO3 #[pyclass])
    │       ├── every()               ──► src/job.rs       (Job, Schedule model)
    │       │                         ──► src/interval.rs  (parses "10s"/"5m"/"1h")
    │       ├── cron()                ──► src/cron.rs       (parses "0 9 * * 1-5", next run)
    │       ├── list_jobs()           ──► src/registry.rs  (JobRegistry snapshot)
    │       ├── remove_job()          ──► src/registry.rs  (JobRegistry.remove)
    │       ├── run()                 ──► src/executor.rs  (run_loop, StopSignal)
    │       ├── start_background()    ──► run_loop() spawned on its own OS thread
    │       └── shutdown()            ──► StopSignal.stop() + thread join
    ├── rust_py_scheduler.fastapi    ──► scheduler_lifespan() (pure Python)
    └── rust_py_scheduler.django     ──► start_in_background() (pure Python)

src/registry.rs    ──► thread-safe job storage (Arc<Mutex<HashMap<...>>>); calls each
                       callback under the GIL, applies the retry loop, tracks counts
src/cron.rs        ──► 5-field cron parser; computes the next wall-clock occurrence and
                       converts the gap into a monotonic Instant deadline
src/time_utils.rs  ──► wall-clock timestamps for last_run_at/next_run_at (display only;
                       scheduling itself uses a monotonic std::time::Instant)
src/errors.rs      ──► SchedulerError -> PyErr (ValueError / RuntimeError / KeyError)

The core is compiled into a native extension (.so/.pyd) by maturin and PyO3, built against Python's stable ABI (abi3-py310) so a single wheel covers Python 3.10 through 3.13+. The Python layer (python/rust_py_scheduler/__init__.py) just re-exports the compiled module.

Roadmap

Done: cron expressions, FastAPI / Django / Celery integrations, and a CI suite that runs the Rust + Python tests on every push. Still planned:

Per-job enabled toggling (pause/resume without removing)
Configurable cron timezone (today: system local time)
Publish to TestPyPI, then PyPI

License

MIT.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rust_py_scheduler-0.2.3.tar.gz (60.2 kB view details)

Uploaded Aug 12, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

rust_py_scheduler-0.2.3-cp310-abi3-win_arm64.whl (211.6 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+Windows ARM64

rust_py_scheduler-0.2.3-cp310-abi3-win_amd64.whl (221.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+Windows x86-64

rust_py_scheduler-0.2.3-cp310-abi3-win32.whl (210.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+Windows x86

rust_py_scheduler-0.2.3-cp310-abi3-musllinux_1_2_x86_64.whl (536.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+musllinux: musl 1.2+ x86-64

rust_py_scheduler-0.2.3-cp310-abi3-musllinux_1_2_i686.whl (569.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+musllinux: musl 1.2+ i686

rust_py_scheduler-0.2.3-cp310-abi3-musllinux_1_2_armv7l.whl (603.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+musllinux: musl 1.2+ ARMv7l

rust_py_scheduler-0.2.3-cp310-abi3-musllinux_1_2_aarch64.whl (488.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+musllinux: musl 1.2+ ARM64

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (324.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (360.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ s390x

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (359.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ ppc64le

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (327.4 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ ARMv7l

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (311.4 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.17+ ARM64

rust_py_scheduler-0.2.3-cp310-abi3-manylinux_2_12_i686.manylinux2010_i686.whl (353.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+manylinux: glibc 2.12+ i686

rust_py_scheduler-0.2.3-cp310-abi3-macosx_11_0_arm64.whl (293.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+macOS 11.0+ ARM64

rust_py_scheduler-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl (303.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file rust_py_scheduler-0.2.3.tar.gz.

File metadata

Download URL: rust_py_scheduler-0.2.3.tar.gz
Upload date: Aug 12, 2026
Size: 60.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rust_py_scheduler-0.2.3.tar.gz
Algorithm	Hash digest
SHA256	`8f6dcaba355044436faa05dc866113e5d3a35cc0042e65fa017b9cc6f823b3f8`
MD5	`c3256b464a5a48df795fe877ba22bd02`
BLAKE2b-256	`dda2d0a9ebcf2cab8ef16e31c60458ad8bc7e2aee0d23aaf2f254c0df36e8e28`

Algorithm	Hash digest
SHA256	`336ab339b2f0e6ed1967ec701a3628236884aad17cfbc6430639b6975ceb1131`
MD5	`40a3889b6473911471f1ba76736a4d41`
BLAKE2b-256	`a8f665c0a1977123317c8367f5738cd17e723ab703b65b4dde418bc6fe06d242`

Algorithm	Hash digest
SHA256	`00765183454f08bbd1a9cea1286242361d0f62c0839bbff0adb7f78566972e54`
MD5	`7d5bf27c5ec01ec87e0fa97bb57eee96`
BLAKE2b-256	`fca48923a6c596dfab93ca045f49a7f854da6cf7510395c57c9ebd92d1d8074d`

Algorithm	Hash digest
SHA256	`e936e0ad8767151a444a31c25cf627e39727b2986f5808ce9b55c57586e43d46`
MD5	`c98ec39d036b93726e15e6cc8a990918`
BLAKE2b-256	`60216bdbe88bb98d47169c5227ccaf22c30546e876ec5ee7878f86339e2e1c09`

Algorithm	Hash digest
SHA256	`9fd5e4603bef9ae0bb123cd5bc04528ef8e9935c7a1297db17708cfdb3b4c83c`
MD5	`340b3febd269c5994e53c9bfd29e1a2c`
BLAKE2b-256	`c1068f2e0447237513c34d63b9fe4a788de98dc6f3eafb35e7c80c8d045b4a45`

Algorithm	Hash digest
SHA256	`a0247d441a793599f3de76a69d35b543c22e5fee6bcdfd0a4c9029ee49fe8946`
MD5	`74b1dbac09c669ee395e0b0329ed7f80`
BLAKE2b-256	`be9c13f3c824db093e470a097936c6cee3d6e3fb5a513d050601e366e763d074`

Algorithm	Hash digest
SHA256	`49b925c472f68112da5609408cdaf26d4bc5b64ba9b80b872a64e71c95fad681`
MD5	`b2013315afb58faafa3dbff3fcf29e19`
BLAKE2b-256	`6db0b986055479f28d984c3746165e1d9fb457d515605d549ef381ff2a4ad4b8`

Algorithm	Hash digest
SHA256	`73e38e6ea0a30f0f5211fff8863a396611dc954c6a196e0d4d814ba8f93e4568`
MD5	`deb1bfaf2ab099361a5a72361300883b`
BLAKE2b-256	`0e3e356b1af7076e4fc38fa635c959809df714ca3aaa3a73c16b47a79cff52ad`

Algorithm	Hash digest
SHA256	`2ee14ec812b58cdac837969d4de56c22aeefb9867b98eb306962212f288f6b3d`
MD5	`1d4ccbb25fc426c27257d5391995e895`
BLAKE2b-256	`ee81f4bb09cacec694966073fc7d9e0da7e448714cee23e67c25ec154ea2fe50`

Algorithm	Hash digest
SHA256	`f6f096032fecaad378cf7bbb55784c48f0f607f3dc27a694d6f9c569634a525d`
MD5	`b82dd96dbd53fed330d82b256dde9e0c`
BLAKE2b-256	`7b4d275de2b6db2004482ff82230f4bf244a507fc15276af9e00c647e16051ff`

Algorithm	Hash digest
SHA256	`db1a309270c854962d54ad4d78e00eef0c99691d2696e4eb2792c91e1bfe4887`
MD5	`c5f063fdbbab3bae4d79be51d3e98dce`
BLAKE2b-256	`d5116f1e82f3e930e925491b855ac51c3b7ff24100b7056da804625eeeffad75`

Algorithm	Hash digest
SHA256	`fd37e233e4b13ac25bd7736418b4ec2c5769e4799bdc0f13547263fce9508b88`
MD5	`6ee658875c691b11fbfe28011ab8c81c`
BLAKE2b-256	`bf82df1704c95f102171ae05f1f111e4e82dbf1f312e6aa19031385515731eab`

Algorithm	Hash digest
SHA256	`3a66b644482f60b5e9a79e46b1799ab2ca502b35ec7873c310a9b20826ccc42b`
MD5	`b5018b5e8b1eda2aac296398d1cc40bd`
BLAKE2b-256	`26e6116912355954ceaca62e4c464a96b7fd4e9a523f02b85bbba6fbd638c60d`

Algorithm	Hash digest
SHA256	`4c0d0137fe6e4662ce609b46feb43150ed9eb8bde392849d7d98023d953941d4`
MD5	`ee9146b395bafec598b4a3cab4c4a470`
BLAKE2b-256	`ea383176d275a9bb9ad80685000cca9c432cccaa2e60bd431e1ead605baa489e`

Algorithm	Hash digest
SHA256	`724a6aed04be03f12dd956aecf13e1a1be4a35f0f188688236307cc5111def49`
MD5	`348382738b77fed64868540969f9e63d`
BLAKE2b-256	`1c827795362388d9e6828b1d1392c13a06b550609594eb8bb9bbaf9fbe858eb7`

Algorithm	Hash digest
SHA256	`ccc01fe2d70d30008676725a69cd8f716a8032e7128da916f9681174c099d5b0`
MD5	`53399a4df5f298b8eb7196c702c403c3`
BLAKE2b-256	`546291a6d91be47dc4b54c066581d23adcb12c334cb4b493dbf1bf605744c600`

rust-py-scheduler 0.2.3

rust-py-scheduler

Features

Requirements

Installation

Quick Start

Registering Jobs

Cron Scheduling

Framework Integrations

FastAPI

Django

Celery

Background Execution

Inspecting and Removing Jobs

Error Handling & Retries

API Reference

Scheduler()

scheduler.every(interval, callback=None, max_retries=0)

scheduler.cron(expression, callback=None, max_retries=0)

scheduler.list_jobs() -> list[dict]

scheduler.remove_job(job_id)

scheduler.run()

scheduler.start_background()

scheduler.shutdown()

Building from Source

Running tests

Architecture

Roadmap

License

Key dates

1 maintainer

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

`Scheduler()`

`scheduler.every(interval, callback=None, max_retries=0)`

`scheduler.cron(expression, callback=None, max_retries=0)`

`scheduler.list_jobs() -> list[dict]`

`scheduler.remove_job(job_id)`

`scheduler.run()`

`scheduler.start_background()`

`scheduler.shutdown()`