Metadata-Version: 2.5
Name: vercel-schedules
Version: 0.1.0
Summary: Python SDK for Vercel Schedules
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: anyio<5,>=4.11.0
Requires-Dist: httpx2>=2
Requires-Dist: pydantic<3,>=2.12.0
Requires-Dist: vercel-internal-core<0.4.0,>=0.3.1
Requires-Dist: vercel-oidc>=0.12.0
Description-Content-Type: text/markdown

# vercel-schedules

Python SDK for [Vercel Schedules](https://vercel.com/docs/schedules).

```sh
pip install vercel-schedules
```

## Declare schedules in code

`@schedule` declares a function as the handler of a recurring schedule:

```python
# jobs.py
from vercel.schedules import Cron, ScheduleMetadata, schedule


@schedule(cron=Cron(hour=3))
def reindex() -> None:
    ...


@schedule(cron="*/15 * * * *", name="sync-billing", timezone="America/New_York")
async def sync_billing(metadata: ScheduleMetadata) -> None:
    print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
```

Deploy them by naming the module in `vercel.json`. The cron, timezone, and
jitter come from the code, so the entry sets only the `root` the schedule
runs in and the module path, relative to it:

```json
{
  "schedules": {
    "jobs": { "root": ".", "entrypoint": "jobs" }
  }
}
```

The build imports `jobs` from the root and creates a schedule for each
`@schedule` it registers, including those in modules it imports. Each schedule is named after
the entry and the schedule, such as `jobs.reindex` and `jobs.sync-billing`. Use
that name with `get_schedule()` and the other management functions, and expect
it in `metadata.name`.

The schedule name defaults to the function's name and must be unique among the
schedules the module registers. Renaming a schedule replaces it. A handler may
be a coroutine function. A parameter annotated `ScheduleMetadata` receives the
firing's metadata, under any name. A firing supplies nothing else, so every
other parameter needs a default.

To run one function on several schedules, stack `@schedule` and name each one:

```python
@schedule(cron="0 3 * * *", name="report-morning")
@schedule(cron="0 15 * * *", name="report-afternoon")
def report(metadata: ScheduleMetadata) -> None:
    ...
```

### Function settings

A schedule can set how long a firing may run and the regions its function is
deployed to:

```python
from datetime import timedelta


@schedule(cron=Cron(hour=4), max_duration=timedelta(minutes=15), regions=["fra1"])
def export_reports() -> None:
    ...
```

`max_duration` is a whole number of seconds, up to your plan's limit, and
defaults to the platform's default. Each firing runs once, in one of the
`regions`: the others are used only if it is unavailable, so pass one region
to choose where the schedule runs. `regions` defaults to the project's regions.

Schedules with the same settings run in one function, and each other
combination runs in a function of its own. Schedules in different functions do
not share a process, so they do not share module-level state such as a cache
or a connection pool.

Importing the module registers its schedules. `get_registered_schedules()`
returns them, and `RegisteredSchedule.run(metadata)` calls the handler for one
firing: a coroutine function is awaited, and a regular function runs in a
worker thread, with any awaitable it returns awaited too.

To handle a firing in your own route, such as a schedule that targets a path,
read it from the request headers with `ScheduleMetadata.from_headers()`:

```python
from fastapi import FastAPI, Request
from vercel.schedules import ScheduleMetadata

app = FastAPI()


@app.post("/api/cleanup")
async def cleanup(request: Request) -> None:
    metadata = ScheduleMetadata.from_headers(request.headers)
    ...
```

A request without a schedule CloudEvent, such as a legacy Cron Job, raises
`NotAScheduleInvocationError`. A path is public, so check
`authorization: Bearer <CRON_SECRET>` as you would for a Cron Job.

## Manage schedules

A schedule fires on a cron cadence or once at a fixed time, and publishes to a
Vercel Queue topic. It is identified by its name within a namespace, which
defaults to `"default"`.

```python
from datetime import timedelta
from vercel.schedules import Cron, create_schedule, query_schedules

schedule = await create_schedule(
    "cleanup",
    topic="scheduled-cleanup",
    cron=Cron(hour=3),  # every day at 03:00
    jitter=timedelta(minutes=2),
    payload={"max_age_days": 30},
)

async for schedule in query_schedules():
    print(schedule.name, schedule.expression, schedule.is_active)
```

`cron=` takes a `Cron` or a crontab string such as `"0 3 * * *"`. Fields you
leave out of a `Cron` default to `*`, except fields less significant than every
field you set, which default to their minimum, as in APScheduler's
`CronTrigger`. `Cron(hour=3)` is `0 3 * * *`, and `Cron(day=1)` is `0 0 1 * *`.
`str(cron)` renders the crontab expression, and `Cron.from_crontab()` parses one.

`jitter` spreads each firing over a random delay of 1 to 15 whole minutes.

### Timezones

Cron expressions are evaluated in UTC unless you pass an IANA `timezone`:

```python
await create_schedule(
    "daily-report",
    topic="send-report",
    cron=Cron(hour=9),
    timezone="America/Los_Angeles",
)
```

Pass `at=` instead of `cron=` for a schedule that fires once. An aware
`datetime` carrying a `ZoneInfo` (or UTC) supplies the timezone itself. A naive
`datetime` needs an explicit `timezone=`:

```python
from datetime import datetime, timezone
from zoneinfo import ZoneInfo

await create_schedule(
    "launch",
    topic="launch",
    at=datetime(2026, 9, 16, 9, tzinfo=ZoneInfo("America/Los_Angeles")),
)

await create_schedule(
    "follow-up",
    topic="send-report",
    at=datetime.now(timezone.utc) + timedelta(hours=1),
)
```

Given both an aware `at` and `timezone`, `at` is converted into that timezone,
so the instant is preserved. One-off schedules have minute precision: a time
with seconds is rounded up to the next minute, so the schedule never fires
before `at`. Fixed-offset datetimes other than UTC are rejected because they
carry no IANA name.

### Change, pause, and run schedules

`get_schedule`, `update_schedule`, `enable_schedule`, `disable_schedule`,
`invoke_schedule`, and `delete_schedule` take the schedule name and an optional
`namespace=`. A missing schedule raises `ScheduleNotFoundError`, which is also a
`LookupError`.

```python
from datetime import datetime, timezone
from vercel.schedules import enable_schedule, invoke_schedule, update_schedule

await update_schedule("cleanup", cron="0 2 * * *", jitter=None)  # jitter=None clears it
await invoke_schedule("cleanup")  # fire now, outside the cadence
await enable_schedule("cleanup", until=datetime(2026, 12, 1, tzinfo=timezone.utc))
```

Schedules declared in `vercel.json` can only be enabled or disabled through the
API. Other API errors raise `SchedulesApiError`, whose `code` names the reason,
such as `"schedule_already_exists"`, and whose `retry_after` holds the seconds
to wait after `"rate_limited"`.

The same surface is available synchronously, with identical names and arguments:

```python
from vercel.schedules.sync import create_schedule, query_schedules

schedule = create_schedule("cleanup", topic="scheduled-cleanup", cron="0 * * * *")
for schedule in query_schedules():
    ...
```

### Configuration

Requests authenticate with the deployment's Vercel OIDC token and target the
public Schedules service, overridable with `VERCEL_SCHEDULE_BASE_URL`. Override
either per session:

```python
from vercel.api import session
from vercel.schedules import SchedulesServiceOptions, get_schedule, static_credentials_factory

options = SchedulesServiceOptions(
    base_url="...",
    credentials_factory=static_credentials_factory("..."),
)
async with session(service_options=[options]):
    schedule = await get_schedule("cleanup")
```

`credentials_factory` runs before each request, so it can return a refreshed
token. For sync calls, use `SchedulesServiceOptions` from
`vercel.schedules.sync` in a plain `with` block. Its `credentials_factory` is a
plain function, which may block. Mixing an async call into a sync session, or
the reverse, is rejected.

Under `vercel dev`, the SDK uses the local Schedules API that `vercel dev`
serves, with the token it provides. Elsewhere, run `vercel link` and
`vercel env pull` so an OIDC token is available, or pass a
`credentials_factory`.

## Read the firing in a schedule command

A schedule with `run` builds the image from the Dockerfile in `root`, and runs
the command once per firing:

```json
{
  "schedules": {
    "reindex": {
      "schedule": "0 3 * * *",
      "root": "jobs",
      "entrypoint": "Dockerfile",
      "run": ["python", "reindex.py"]
    }
  }
}
```

The firing's metadata is in `VERCEL_SCHEDULE_*` environment variables.
`ScheduleMetadata.from_env()` reads them:

```python
# jobs/reindex.py
from vercel.schedules import ScheduleMetadata

metadata = ScheduleMetadata.from_env()
print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
```

A non-zero exit status marks the firing as failed. Failed firings are not
retried.

Run by hand, without the variables, `from_env()` raises
`NotAScheduleInvocationError`. The package is optional here:
`os.environ["VERCEL_SCHEDULE_NAME"]` works too.

| Variable | `ScheduleMetadata` attribute |
| --- | --- |
| `VERCEL_SCHEDULE_ID` | `schedule_id` |
| `VERCEL_SCHEDULE_EXECUTION_ID` | `execution_id` |
| `VERCEL_SCHEDULE_NAME` | `name` |
| `VERCEL_SCHEDULE_NAMESPACE` | `namespace` |
| `VERCEL_SCHEDULE_SCHEDULED_AT` | `scheduled_at`, as an aware UTC `datetime` |
| `VERCEL_SCHEDULE_SOURCE` | `source` |
| `VERCEL_SCHEDULE_EXPRESSION` | `expression` |
