Metadata-Version: 2.5
Name: q0-jobs
Version: 0.1.0
Summary: Add your description here
Author-email: Aziz Berkay Yesilyurt <abyesilyurt@gmail.com>
Requires-Python: >=3.13
Requires-Dist: google-cloud-scheduler>=2.19.0
Description-Content-Type: text/markdown

# q0

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

## Usage

```python
# 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

```bash
# 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.

![Cloud Scheduler jobs](docs/gcloud.png)


## Deployment

Deploy as a Cloud Run Job and sync schedules:

```bash
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>`).

