vercel-schedules-bundle 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vercel, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,302 @@
1
+ Metadata-Version: 2.5
2
+ Name: vercel-schedules-bundle
3
+ Version: 0.1.0
4
+ Summary: Python SDK for Vercel Schedules
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: anyio<5,>=4.11.0
9
+ Requires-Dist: pydantic<3,>=2.12.0
10
+ Requires-Dist: vercel-internal-core-bundle<0.4.0,>=0.3.1
11
+ Requires-Dist: vercel-internal-shared-vendored-deps>=0.1.5
12
+ Requires-Dist: vercel-oidc-bundle>=0.12.0
13
+ Description-Content-Type: text/markdown
14
+
15
+ # vercel-schedules-bundle
16
+
17
+ This is a version of `vercel-schedules` with third-party dependencies bundled. For normal use, install the unbundled `vercel-schedules` package instead: https://pypi.org/project/vercel-schedules/
18
+
19
+ # vercel-schedules
20
+
21
+ Python SDK for [Vercel Schedules](https://vercel.com/docs/schedules).
22
+
23
+ ```sh
24
+ pip install vercel-schedules
25
+ ```
26
+
27
+ ## Declare schedules in code
28
+
29
+ `@schedule` declares a function as the handler of a recurring schedule:
30
+
31
+ ```python
32
+ # jobs.py
33
+ from vercel.schedules import Cron, ScheduleMetadata, schedule
34
+
35
+
36
+ @schedule(cron=Cron(hour=3))
37
+ def reindex() -> None:
38
+ ...
39
+
40
+
41
+ @schedule(cron="*/15 * * * *", name="sync-billing", timezone="America/New_York")
42
+ async def sync_billing(metadata: ScheduleMetadata) -> None:
43
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
44
+ ```
45
+
46
+ Deploy them by naming the module in `vercel.json`. The cron, timezone, and
47
+ jitter come from the code, so the entry sets only the `root` the schedule
48
+ runs in and the module path, relative to it:
49
+
50
+ ```json
51
+ {
52
+ "schedules": {
53
+ "jobs": { "root": ".", "entrypoint": "jobs" }
54
+ }
55
+ }
56
+ ```
57
+
58
+ The build imports `jobs` from the root and creates a schedule for each
59
+ `@schedule` it registers, including those in modules it imports. Each schedule is named after
60
+ the entry and the schedule, such as `jobs.reindex` and `jobs.sync-billing`. Use
61
+ that name with `get_schedule()` and the other management functions, and expect
62
+ it in `metadata.name`.
63
+
64
+ The schedule name defaults to the function's name and must be unique among the
65
+ schedules the module registers. Renaming a schedule replaces it. A handler may
66
+ be a coroutine function. A parameter annotated `ScheduleMetadata` receives the
67
+ firing's metadata, under any name. A firing supplies nothing else, so every
68
+ other parameter needs a default.
69
+
70
+ To run one function on several schedules, stack `@schedule` and name each one:
71
+
72
+ ```python
73
+ @schedule(cron="0 3 * * *", name="report-morning")
74
+ @schedule(cron="0 15 * * *", name="report-afternoon")
75
+ def report(metadata: ScheduleMetadata) -> None:
76
+ ...
77
+ ```
78
+
79
+ ### Function settings
80
+
81
+ A schedule can set how long a firing may run and the regions its function is
82
+ deployed to:
83
+
84
+ ```python
85
+ from datetime import timedelta
86
+
87
+
88
+ @schedule(cron=Cron(hour=4), max_duration=timedelta(minutes=15), regions=["fra1"])
89
+ def export_reports() -> None:
90
+ ...
91
+ ```
92
+
93
+ `max_duration` is a whole number of seconds, up to your plan's limit, and
94
+ defaults to the platform's default. Each firing runs once, in one of the
95
+ `regions`: the others are used only if it is unavailable, so pass one region
96
+ to choose where the schedule runs. `regions` defaults to the project's regions.
97
+
98
+ Schedules with the same settings run in one function, and each other
99
+ combination runs in a function of its own. Schedules in different functions do
100
+ not share a process, so they do not share module-level state such as a cache
101
+ or a connection pool.
102
+
103
+ Importing the module registers its schedules. `get_registered_schedules()`
104
+ returns them, and `RegisteredSchedule.run(metadata)` calls the handler for one
105
+ firing: a coroutine function is awaited, and a regular function runs in a
106
+ worker thread, with any awaitable it returns awaited too.
107
+
108
+ To handle a firing in your own route, such as a schedule that targets a path,
109
+ read it from the request headers with `ScheduleMetadata.from_headers()`:
110
+
111
+ ```python
112
+ from fastapi import FastAPI, Request
113
+ from vercel.schedules import ScheduleMetadata
114
+
115
+ app = FastAPI()
116
+
117
+
118
+ @app.post("/api/cleanup")
119
+ async def cleanup(request: Request) -> None:
120
+ metadata = ScheduleMetadata.from_headers(request.headers)
121
+ ...
122
+ ```
123
+
124
+ A request without a schedule CloudEvent, such as a legacy Cron Job, raises
125
+ `NotAScheduleInvocationError`. A path is public, so check
126
+ `authorization: Bearer <CRON_SECRET>` as you would for a Cron Job.
127
+
128
+ ## Manage schedules
129
+
130
+ A schedule fires on a cron cadence or once at a fixed time, and publishes to a
131
+ Vercel Queue topic. It is identified by its name within a namespace, which
132
+ defaults to `"default"`.
133
+
134
+ ```python
135
+ from datetime import timedelta
136
+ from vercel.schedules import Cron, create_schedule, query_schedules
137
+
138
+ schedule = await create_schedule(
139
+ "cleanup",
140
+ topic="scheduled-cleanup",
141
+ cron=Cron(hour=3), # every day at 03:00
142
+ jitter=timedelta(minutes=2),
143
+ payload={"max_age_days": 30},
144
+ )
145
+
146
+ async for schedule in query_schedules():
147
+ print(schedule.name, schedule.expression, schedule.is_active)
148
+ ```
149
+
150
+ `cron=` takes a `Cron` or a crontab string such as `"0 3 * * *"`. Fields you
151
+ leave out of a `Cron` default to `*`, except fields less significant than every
152
+ field you set, which default to their minimum, as in APScheduler's
153
+ `CronTrigger`. `Cron(hour=3)` is `0 3 * * *`, and `Cron(day=1)` is `0 0 1 * *`.
154
+ `str(cron)` renders the crontab expression, and `Cron.from_crontab()` parses one.
155
+
156
+ `jitter` spreads each firing over a random delay of 1 to 15 whole minutes.
157
+
158
+ ### Timezones
159
+
160
+ Cron expressions are evaluated in UTC unless you pass an IANA `timezone`:
161
+
162
+ ```python
163
+ await create_schedule(
164
+ "daily-report",
165
+ topic="send-report",
166
+ cron=Cron(hour=9),
167
+ timezone="America/Los_Angeles",
168
+ )
169
+ ```
170
+
171
+ Pass `at=` instead of `cron=` for a schedule that fires once. An aware
172
+ `datetime` carrying a `ZoneInfo` (or UTC) supplies the timezone itself. A naive
173
+ `datetime` needs an explicit `timezone=`:
174
+
175
+ ```python
176
+ from datetime import datetime, timezone
177
+ from zoneinfo import ZoneInfo
178
+
179
+ await create_schedule(
180
+ "launch",
181
+ topic="launch",
182
+ at=datetime(2026, 9, 16, 9, tzinfo=ZoneInfo("America/Los_Angeles")),
183
+ )
184
+
185
+ await create_schedule(
186
+ "follow-up",
187
+ topic="send-report",
188
+ at=datetime.now(timezone.utc) + timedelta(hours=1),
189
+ )
190
+ ```
191
+
192
+ Given both an aware `at` and `timezone`, `at` is converted into that timezone,
193
+ so the instant is preserved. One-off schedules have minute precision: a time
194
+ with seconds is rounded up to the next minute, so the schedule never fires
195
+ before `at`. Fixed-offset datetimes other than UTC are rejected because they
196
+ carry no IANA name.
197
+
198
+ ### Change, pause, and run schedules
199
+
200
+ `get_schedule`, `update_schedule`, `enable_schedule`, `disable_schedule`,
201
+ `invoke_schedule`, and `delete_schedule` take the schedule name and an optional
202
+ `namespace=`. A missing schedule raises `ScheduleNotFoundError`, which is also a
203
+ `LookupError`.
204
+
205
+ ```python
206
+ from datetime import datetime, timezone
207
+ from vercel.schedules import enable_schedule, invoke_schedule, update_schedule
208
+
209
+ await update_schedule("cleanup", cron="0 2 * * *", jitter=None) # jitter=None clears it
210
+ await invoke_schedule("cleanup") # fire now, outside the cadence
211
+ await enable_schedule("cleanup", until=datetime(2026, 12, 1, tzinfo=timezone.utc))
212
+ ```
213
+
214
+ Schedules declared in `vercel.json` can only be enabled or disabled through the
215
+ API. Other API errors raise `SchedulesApiError`, whose `code` names the reason,
216
+ such as `"schedule_already_exists"`, and whose `retry_after` holds the seconds
217
+ to wait after `"rate_limited"`.
218
+
219
+ The same surface is available synchronously, with identical names and arguments:
220
+
221
+ ```python
222
+ from vercel.schedules.sync import create_schedule, query_schedules
223
+
224
+ schedule = create_schedule("cleanup", topic="scheduled-cleanup", cron="0 * * * *")
225
+ for schedule in query_schedules():
226
+ ...
227
+ ```
228
+
229
+ ### Configuration
230
+
231
+ Requests authenticate with the deployment's Vercel OIDC token and target the
232
+ public Schedules service, overridable with `VERCEL_SCHEDULE_BASE_URL`. Override
233
+ either per session:
234
+
235
+ ```python
236
+ from vercel.api import session
237
+ from vercel.schedules import SchedulesServiceOptions, get_schedule, static_credentials_factory
238
+
239
+ options = SchedulesServiceOptions(
240
+ base_url="...",
241
+ credentials_factory=static_credentials_factory("..."),
242
+ )
243
+ async with session(service_options=[options]):
244
+ schedule = await get_schedule("cleanup")
245
+ ```
246
+
247
+ `credentials_factory` runs before each request, so it can return a refreshed
248
+ token. For sync calls, use `SchedulesServiceOptions` from
249
+ `vercel.schedules.sync` in a plain `with` block. Its `credentials_factory` is a
250
+ plain function, which may block. Mixing an async call into a sync session, or
251
+ the reverse, is rejected.
252
+
253
+ Under `vercel dev`, the SDK uses the local Schedules API that `vercel dev`
254
+ serves, with the token it provides. Elsewhere, run `vercel link` and
255
+ `vercel env pull` so an OIDC token is available, or pass a
256
+ `credentials_factory`.
257
+
258
+ ## Read the firing in a schedule command
259
+
260
+ A schedule with `run` builds the image from the Dockerfile in `root`, and runs
261
+ the command once per firing:
262
+
263
+ ```json
264
+ {
265
+ "schedules": {
266
+ "reindex": {
267
+ "schedule": "0 3 * * *",
268
+ "root": "jobs",
269
+ "entrypoint": "Dockerfile",
270
+ "run": ["python", "reindex.py"]
271
+ }
272
+ }
273
+ }
274
+ ```
275
+
276
+ The firing's metadata is in `VERCEL_SCHEDULE_*` environment variables.
277
+ `ScheduleMetadata.from_env()` reads them:
278
+
279
+ ```python
280
+ # jobs/reindex.py
281
+ from vercel.schedules import ScheduleMetadata
282
+
283
+ metadata = ScheduleMetadata.from_env()
284
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
285
+ ```
286
+
287
+ A non-zero exit status marks the firing as failed. Failed firings are not
288
+ retried.
289
+
290
+ Run by hand, without the variables, `from_env()` raises
291
+ `NotAScheduleInvocationError`. The package is optional here:
292
+ `os.environ["VERCEL_SCHEDULE_NAME"]` works too.
293
+
294
+ | Variable | `ScheduleMetadata` attribute |
295
+ | --- | --- |
296
+ | `VERCEL_SCHEDULE_ID` | `schedule_id` |
297
+ | `VERCEL_SCHEDULE_EXECUTION_ID` | `execution_id` |
298
+ | `VERCEL_SCHEDULE_NAME` | `name` |
299
+ | `VERCEL_SCHEDULE_NAMESPACE` | `namespace` |
300
+ | `VERCEL_SCHEDULE_SCHEDULED_AT` | `scheduled_at`, as an aware UTC `datetime` |
301
+ | `VERCEL_SCHEDULE_SOURCE` | `source` |
302
+ | `VERCEL_SCHEDULE_EXPRESSION` | `expression` |
@@ -0,0 +1,288 @@
1
+ # vercel-schedules-bundle
2
+
3
+ This is a version of `vercel-schedules` with third-party dependencies bundled. For normal use, install the unbundled `vercel-schedules` package instead: https://pypi.org/project/vercel-schedules/
4
+
5
+ # vercel-schedules
6
+
7
+ Python SDK for [Vercel Schedules](https://vercel.com/docs/schedules).
8
+
9
+ ```sh
10
+ pip install vercel-schedules
11
+ ```
12
+
13
+ ## Declare schedules in code
14
+
15
+ `@schedule` declares a function as the handler of a recurring schedule:
16
+
17
+ ```python
18
+ # jobs.py
19
+ from vercel.schedules import Cron, ScheduleMetadata, schedule
20
+
21
+
22
+ @schedule(cron=Cron(hour=3))
23
+ def reindex() -> None:
24
+ ...
25
+
26
+
27
+ @schedule(cron="*/15 * * * *", name="sync-billing", timezone="America/New_York")
28
+ async def sync_billing(metadata: ScheduleMetadata) -> None:
29
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
30
+ ```
31
+
32
+ Deploy them by naming the module in `vercel.json`. The cron, timezone, and
33
+ jitter come from the code, so the entry sets only the `root` the schedule
34
+ runs in and the module path, relative to it:
35
+
36
+ ```json
37
+ {
38
+ "schedules": {
39
+ "jobs": { "root": ".", "entrypoint": "jobs" }
40
+ }
41
+ }
42
+ ```
43
+
44
+ The build imports `jobs` from the root and creates a schedule for each
45
+ `@schedule` it registers, including those in modules it imports. Each schedule is named after
46
+ the entry and the schedule, such as `jobs.reindex` and `jobs.sync-billing`. Use
47
+ that name with `get_schedule()` and the other management functions, and expect
48
+ it in `metadata.name`.
49
+
50
+ The schedule name defaults to the function's name and must be unique among the
51
+ schedules the module registers. Renaming a schedule replaces it. A handler may
52
+ be a coroutine function. A parameter annotated `ScheduleMetadata` receives the
53
+ firing's metadata, under any name. A firing supplies nothing else, so every
54
+ other parameter needs a default.
55
+
56
+ To run one function on several schedules, stack `@schedule` and name each one:
57
+
58
+ ```python
59
+ @schedule(cron="0 3 * * *", name="report-morning")
60
+ @schedule(cron="0 15 * * *", name="report-afternoon")
61
+ def report(metadata: ScheduleMetadata) -> None:
62
+ ...
63
+ ```
64
+
65
+ ### Function settings
66
+
67
+ A schedule can set how long a firing may run and the regions its function is
68
+ deployed to:
69
+
70
+ ```python
71
+ from datetime import timedelta
72
+
73
+
74
+ @schedule(cron=Cron(hour=4), max_duration=timedelta(minutes=15), regions=["fra1"])
75
+ def export_reports() -> None:
76
+ ...
77
+ ```
78
+
79
+ `max_duration` is a whole number of seconds, up to your plan's limit, and
80
+ defaults to the platform's default. Each firing runs once, in one of the
81
+ `regions`: the others are used only if it is unavailable, so pass one region
82
+ to choose where the schedule runs. `regions` defaults to the project's regions.
83
+
84
+ Schedules with the same settings run in one function, and each other
85
+ combination runs in a function of its own. Schedules in different functions do
86
+ not share a process, so they do not share module-level state such as a cache
87
+ or a connection pool.
88
+
89
+ Importing the module registers its schedules. `get_registered_schedules()`
90
+ returns them, and `RegisteredSchedule.run(metadata)` calls the handler for one
91
+ firing: a coroutine function is awaited, and a regular function runs in a
92
+ worker thread, with any awaitable it returns awaited too.
93
+
94
+ To handle a firing in your own route, such as a schedule that targets a path,
95
+ read it from the request headers with `ScheduleMetadata.from_headers()`:
96
+
97
+ ```python
98
+ from fastapi import FastAPI, Request
99
+ from vercel.schedules import ScheduleMetadata
100
+
101
+ app = FastAPI()
102
+
103
+
104
+ @app.post("/api/cleanup")
105
+ async def cleanup(request: Request) -> None:
106
+ metadata = ScheduleMetadata.from_headers(request.headers)
107
+ ...
108
+ ```
109
+
110
+ A request without a schedule CloudEvent, such as a legacy Cron Job, raises
111
+ `NotAScheduleInvocationError`. A path is public, so check
112
+ `authorization: Bearer <CRON_SECRET>` as you would for a Cron Job.
113
+
114
+ ## Manage schedules
115
+
116
+ A schedule fires on a cron cadence or once at a fixed time, and publishes to a
117
+ Vercel Queue topic. It is identified by its name within a namespace, which
118
+ defaults to `"default"`.
119
+
120
+ ```python
121
+ from datetime import timedelta
122
+ from vercel.schedules import Cron, create_schedule, query_schedules
123
+
124
+ schedule = await create_schedule(
125
+ "cleanup",
126
+ topic="scheduled-cleanup",
127
+ cron=Cron(hour=3), # every day at 03:00
128
+ jitter=timedelta(minutes=2),
129
+ payload={"max_age_days": 30},
130
+ )
131
+
132
+ async for schedule in query_schedules():
133
+ print(schedule.name, schedule.expression, schedule.is_active)
134
+ ```
135
+
136
+ `cron=` takes a `Cron` or a crontab string such as `"0 3 * * *"`. Fields you
137
+ leave out of a `Cron` default to `*`, except fields less significant than every
138
+ field you set, which default to their minimum, as in APScheduler's
139
+ `CronTrigger`. `Cron(hour=3)` is `0 3 * * *`, and `Cron(day=1)` is `0 0 1 * *`.
140
+ `str(cron)` renders the crontab expression, and `Cron.from_crontab()` parses one.
141
+
142
+ `jitter` spreads each firing over a random delay of 1 to 15 whole minutes.
143
+
144
+ ### Timezones
145
+
146
+ Cron expressions are evaluated in UTC unless you pass an IANA `timezone`:
147
+
148
+ ```python
149
+ await create_schedule(
150
+ "daily-report",
151
+ topic="send-report",
152
+ cron=Cron(hour=9),
153
+ timezone="America/Los_Angeles",
154
+ )
155
+ ```
156
+
157
+ Pass `at=` instead of `cron=` for a schedule that fires once. An aware
158
+ `datetime` carrying a `ZoneInfo` (or UTC) supplies the timezone itself. A naive
159
+ `datetime` needs an explicit `timezone=`:
160
+
161
+ ```python
162
+ from datetime import datetime, timezone
163
+ from zoneinfo import ZoneInfo
164
+
165
+ await create_schedule(
166
+ "launch",
167
+ topic="launch",
168
+ at=datetime(2026, 9, 16, 9, tzinfo=ZoneInfo("America/Los_Angeles")),
169
+ )
170
+
171
+ await create_schedule(
172
+ "follow-up",
173
+ topic="send-report",
174
+ at=datetime.now(timezone.utc) + timedelta(hours=1),
175
+ )
176
+ ```
177
+
178
+ Given both an aware `at` and `timezone`, `at` is converted into that timezone,
179
+ so the instant is preserved. One-off schedules have minute precision: a time
180
+ with seconds is rounded up to the next minute, so the schedule never fires
181
+ before `at`. Fixed-offset datetimes other than UTC are rejected because they
182
+ carry no IANA name.
183
+
184
+ ### Change, pause, and run schedules
185
+
186
+ `get_schedule`, `update_schedule`, `enable_schedule`, `disable_schedule`,
187
+ `invoke_schedule`, and `delete_schedule` take the schedule name and an optional
188
+ `namespace=`. A missing schedule raises `ScheduleNotFoundError`, which is also a
189
+ `LookupError`.
190
+
191
+ ```python
192
+ from datetime import datetime, timezone
193
+ from vercel.schedules import enable_schedule, invoke_schedule, update_schedule
194
+
195
+ await update_schedule("cleanup", cron="0 2 * * *", jitter=None) # jitter=None clears it
196
+ await invoke_schedule("cleanup") # fire now, outside the cadence
197
+ await enable_schedule("cleanup", until=datetime(2026, 12, 1, tzinfo=timezone.utc))
198
+ ```
199
+
200
+ Schedules declared in `vercel.json` can only be enabled or disabled through the
201
+ API. Other API errors raise `SchedulesApiError`, whose `code` names the reason,
202
+ such as `"schedule_already_exists"`, and whose `retry_after` holds the seconds
203
+ to wait after `"rate_limited"`.
204
+
205
+ The same surface is available synchronously, with identical names and arguments:
206
+
207
+ ```python
208
+ from vercel.schedules.sync import create_schedule, query_schedules
209
+
210
+ schedule = create_schedule("cleanup", topic="scheduled-cleanup", cron="0 * * * *")
211
+ for schedule in query_schedules():
212
+ ...
213
+ ```
214
+
215
+ ### Configuration
216
+
217
+ Requests authenticate with the deployment's Vercel OIDC token and target the
218
+ public Schedules service, overridable with `VERCEL_SCHEDULE_BASE_URL`. Override
219
+ either per session:
220
+
221
+ ```python
222
+ from vercel.api import session
223
+ from vercel.schedules import SchedulesServiceOptions, get_schedule, static_credentials_factory
224
+
225
+ options = SchedulesServiceOptions(
226
+ base_url="...",
227
+ credentials_factory=static_credentials_factory("..."),
228
+ )
229
+ async with session(service_options=[options]):
230
+ schedule = await get_schedule("cleanup")
231
+ ```
232
+
233
+ `credentials_factory` runs before each request, so it can return a refreshed
234
+ token. For sync calls, use `SchedulesServiceOptions` from
235
+ `vercel.schedules.sync` in a plain `with` block. Its `credentials_factory` is a
236
+ plain function, which may block. Mixing an async call into a sync session, or
237
+ the reverse, is rejected.
238
+
239
+ Under `vercel dev`, the SDK uses the local Schedules API that `vercel dev`
240
+ serves, with the token it provides. Elsewhere, run `vercel link` and
241
+ `vercel env pull` so an OIDC token is available, or pass a
242
+ `credentials_factory`.
243
+
244
+ ## Read the firing in a schedule command
245
+
246
+ A schedule with `run` builds the image from the Dockerfile in `root`, and runs
247
+ the command once per firing:
248
+
249
+ ```json
250
+ {
251
+ "schedules": {
252
+ "reindex": {
253
+ "schedule": "0 3 * * *",
254
+ "root": "jobs",
255
+ "entrypoint": "Dockerfile",
256
+ "run": ["python", "reindex.py"]
257
+ }
258
+ }
259
+ }
260
+ ```
261
+
262
+ The firing's metadata is in `VERCEL_SCHEDULE_*` environment variables.
263
+ `ScheduleMetadata.from_env()` reads them:
264
+
265
+ ```python
266
+ # jobs/reindex.py
267
+ from vercel.schedules import ScheduleMetadata
268
+
269
+ metadata = ScheduleMetadata.from_env()
270
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
271
+ ```
272
+
273
+ A non-zero exit status marks the firing as failed. Failed firings are not
274
+ retried.
275
+
276
+ Run by hand, without the variables, `from_env()` raises
277
+ `NotAScheduleInvocationError`. The package is optional here:
278
+ `os.environ["VERCEL_SCHEDULE_NAME"]` works too.
279
+
280
+ | Variable | `ScheduleMetadata` attribute |
281
+ | --- | --- |
282
+ | `VERCEL_SCHEDULE_ID` | `schedule_id` |
283
+ | `VERCEL_SCHEDULE_EXECUTION_ID` | `execution_id` |
284
+ | `VERCEL_SCHEDULE_NAME` | `name` |
285
+ | `VERCEL_SCHEDULE_NAMESPACE` | `namespace` |
286
+ | `VERCEL_SCHEDULE_SCHEDULED_AT` | `scheduled_at`, as an aware UTC `datetime` |
287
+ | `VERCEL_SCHEDULE_SOURCE` | `source` |
288
+ | `VERCEL_SCHEDULE_EXPRESSION` | `expression` |