q0

Decorator-based cron job scheduling for Google Cloud Run + Cloud Scheduler.

Usage

# app.py
from q0 import Q0

app = Q0(
    prefix="q0-demo-",
    project_id="my-project",
    project_number="123456789",
    region="europe-west1",
)

@app.cron("*/5 * * * *")
def hello():
    print("hello from cron job")

@app.cron("0 0 1 * *")
def monthly_cleanup():
    print("monthly cleanup")

@app.cron("0 9 * * 1", timeout="3600s")
def weekly_report():
    print("weekly report sent")

if __name__ == "__main__":
    app.cli()

CLI

# run a job locally
python app.py run hello

# sync job definitions to Cloud Scheduler
python app.py sync

sync creates, updates, or deletes Cloud Scheduler jobs to match the decorated functions. Each job triggers the Cloud Run Job with a container override that calls run <func_name>. Tasks default to a 10-minute (600s) timeout; set timeout on an individual @app.cron decorator to override it.

Deployment

Deploy as a Cloud Run Job and sync schedules:

gcloud run jobs deploy q0-$(SERVICE_NAME) \
    --image $(IMAGE_TAG) \
    --region $(GCP_REGION) \
    --project $(GCP_PROJECT_ID) \
    --command python,-m,$(SERVICE_NAME).app
gcloud run jobs execute q0-$(SERVICE_NAME) \
    --region $(GCP_REGION) \
    --project $(GCP_PROJECT_ID) \
    --args sync \
    --wait

The --command is set on the job, not in the Dockerfile, so the same image can be shared with a web server or other Cloud Run services. Cloud Scheduler invokes individual functions via container arg overrides (run <func_name>).