GPScheduler

GPScheduler (General-Purpose Scheduler) is a cron-style Python scheduler that turns functions from any package into scheduled jobs via config files, configures startup arguments, and exposes a decorator to mark schedulable functions.

This documentation is bilingual. Use the language selector in the top bar to switch to 简体中文.

Features

• Config-driven cron jobs — declare schedules, callables, and call arguments in YAML config files; no timers hardcoded in application code. See Configuration.
• Package-agnostic — point a job at any importable function in any installed package, located by dotted path. The @scheduled decorator marks functions as schedulable directly in their source. See API reference.
• Two decorators — @scheduled marks a function as schedulable; @worker_init builds an expensive object (DB connection, network client, …) once and reuses it across a job's runs. See API reference → scheduled and API reference → worker_init.
• Thread and process executors — each job picks its own pool. Threads for I/O-bound work, processes for CPU-bound or isolated work. See Performance.
• Reusable per-job initialization — the @worker_init decorator builds an expensive object (DB connection, network client, …) once and reuses it across a job's runs. See API reference → worker_init.
• Scheduler-wide globals — shared config values (db_url, api_key, …) injected into every job that asks for them. See Configuration → job_globals.
• Graceful, cross-platform shutdown — Ctrl+C on Windows, SIGINT/SIGTERM on Linux, with a configurable shutdown timeout. See CLI.
• Fail-Early validation — invalid config (bad cron, unknown function, argument mismatch, unpicklable process args) fails loudly at load time, never silently at the first trigger. See Overview → Fail-Early.
• Embeddable — run it standalone via the CLI, or embed it inside a host application. See API reference → Embedded usage.

Installation

pip install gpscheduler

For local development from a clone:

source .venv/Scripts/activate   # Git Bash on Windows
pip install -e ".[dev]"

Quick start

1. Install gpscheduler (above).
2. Write a package containing a @scheduled function:

# myjobs/hello.py
from gpscheduler import scheduled

@scheduled
def greet(name: str, *, greeting: str = "Hello") -> None:
    print(f"{greeting}, {name}!")

1. Point a config folder at it:

# configs/scheduler.yaml
cfg_class_name: GPSchedulerConfig
configured_class_name: GPScheduler
executor: thread
packages: [myjobs]

# configs/jobs/hello.yaml
cfg_class_name: GPJobConfig
func: "myjobs.hello.greet"
cron: "*/2 * * * * *"   # every 2 seconds (6-segment, leading seconds field)
args: ["world"]
kwargs:
  greeting: "Hi"

The config folder also needs a global_env.yaml at its root — required by the underlying gpconfig loader. An empty {} is fine:

# configs/global_env.yaml
{}

1. Run it:

gpscheduler run --config configs

See Examples for a complete, annotated demo, or read Configuration for the full config reference.

Documentation

Page	What it covers
Overview	Design purpose, architecture, use cases, limitations
API reference	Public API: decorators, classes, config data classes, exceptions, embedded usage
CLI	The gpscheduler command (run, list-jobs)
Configuration	gpconfig folder layout, config fields, cron format
Examples	End-to-end demo walkthrough
Performance	Thread vs process executors, cross-platform notes