vercel-schedules 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,132 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+
5
+ # C extensions
6
+ *.so
7
+
8
+ # Distribution / packaging
9
+ .Python
10
+ build/
11
+ develop-eggs/
12
+ dist/
13
+ downloads/
14
+ eggs/
15
+ .eggs/
16
+ lib/
17
+ lib64/
18
+ parts/
19
+ sdist/
20
+ var/
21
+ wheels/
22
+ share/python-wheels/
23
+ *.egg-info/
24
+ .installed.cfg
25
+ *.egg
26
+ MANIFEST
27
+
28
+ # PyInstallerhave
29
+ *.manifest
30
+ *.spec
31
+
32
+ # Installer logs
33
+ pip-log.txt
34
+ pip-delete-this-directory.txt
35
+
36
+ # Unit test / coverage reports
37
+ .benchmarks/
38
+ htmlcov/
39
+ .tox/
40
+ .nox/
41
+ .coverage
42
+ .coverage.*
43
+ .cache
44
+ nosetests.xml
45
+ coverage.xml
46
+ *.cover
47
+ *.py,cover
48
+ .hypothesis/
49
+ .pytest_cache/
50
+ .ruff_cache/
51
+
52
+ # Translations
53
+ *.mo
54
+ *.pot
55
+
56
+ # Scrapy
57
+ .scrapy
58
+
59
+ # Sphinx documentation
60
+ docs/_build/
61
+
62
+ # PyBuilder
63
+ target/
64
+
65
+ # Jupyter Notebook
66
+ .ipynb_checkpoints
67
+
68
+ # IPython
69
+ profile_default/
70
+ ipython_config.py
71
+
72
+ # pyenv
73
+ .python-version
74
+
75
+ # pipenv
76
+ Pipfile.lock
77
+
78
+ # poetry
79
+ poetry.lock
80
+
81
+ # PDM
82
+ pdm.lock
83
+ .pdm.toml
84
+
85
+ # Hatch
86
+ .hatch/
87
+
88
+ # pyright/mypy
89
+ .mypy_cache/
90
+ .dmypy.json
91
+ dmypy.json
92
+
93
+ # pyre
94
+ .pyre/
95
+
96
+ # pytype
97
+ .pytype/
98
+
99
+ # Caches
100
+ __pypackages__/
101
+
102
+ # Editor/project files
103
+ .DS_Store
104
+ .idea/
105
+ .vscode/
106
+ .zed/
107
+ *.swp
108
+ *.swo
109
+
110
+ # Virtual environments
111
+ .env
112
+ .venv
113
+ .venv.*
114
+ env/
115
+ venv/
116
+ **/.env
117
+ **/.venv
118
+ **/.venv.*
119
+ **/env/
120
+ **/venv/
121
+ ENV/
122
+ env.bak/
123
+ venv.bak/
124
+ # dotenv anywhere
125
+ **/.env
126
+ **/.env.*
127
+ **/*.env
128
+
129
+ .claude
130
+ .lat-build
131
+ .mcp.json
132
+ .codex
@@ -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,298 @@
1
+ Metadata-Version: 2.5
2
+ Name: vercel-schedules
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: httpx2>=2
10
+ Requires-Dist: pydantic<3,>=2.12.0
11
+ Requires-Dist: vercel-internal-core<0.4.0,>=0.3.1
12
+ Requires-Dist: vercel-oidc>=0.12.0
13
+ Description-Content-Type: text/markdown
14
+
15
+ # vercel-schedules
16
+
17
+ Python SDK for [Vercel Schedules](https://vercel.com/docs/schedules).
18
+
19
+ ```sh
20
+ pip install vercel-schedules
21
+ ```
22
+
23
+ ## Declare schedules in code
24
+
25
+ `@schedule` declares a function as the handler of a recurring schedule:
26
+
27
+ ```python
28
+ # jobs.py
29
+ from vercel.schedules import Cron, ScheduleMetadata, schedule
30
+
31
+
32
+ @schedule(cron=Cron(hour=3))
33
+ def reindex() -> None:
34
+ ...
35
+
36
+
37
+ @schedule(cron="*/15 * * * *", name="sync-billing", timezone="America/New_York")
38
+ async def sync_billing(metadata: ScheduleMetadata) -> None:
39
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
40
+ ```
41
+
42
+ Deploy them by naming the module in `vercel.json`. The cron, timezone, and
43
+ jitter come from the code, so the entry sets only the `root` the schedule
44
+ runs in and the module path, relative to it:
45
+
46
+ ```json
47
+ {
48
+ "schedules": {
49
+ "jobs": { "root": ".", "entrypoint": "jobs" }
50
+ }
51
+ }
52
+ ```
53
+
54
+ The build imports `jobs` from the root and creates a schedule for each
55
+ `@schedule` it registers, including those in modules it imports. Each schedule is named after
56
+ the entry and the schedule, such as `jobs.reindex` and `jobs.sync-billing`. Use
57
+ that name with `get_schedule()` and the other management functions, and expect
58
+ it in `metadata.name`.
59
+
60
+ The schedule name defaults to the function's name and must be unique among the
61
+ schedules the module registers. Renaming a schedule replaces it. A handler may
62
+ be a coroutine function. A parameter annotated `ScheduleMetadata` receives the
63
+ firing's metadata, under any name. A firing supplies nothing else, so every
64
+ other parameter needs a default.
65
+
66
+ To run one function on several schedules, stack `@schedule` and name each one:
67
+
68
+ ```python
69
+ @schedule(cron="0 3 * * *", name="report-morning")
70
+ @schedule(cron="0 15 * * *", name="report-afternoon")
71
+ def report(metadata: ScheduleMetadata) -> None:
72
+ ...
73
+ ```
74
+
75
+ ### Function settings
76
+
77
+ A schedule can set how long a firing may run and the regions its function is
78
+ deployed to:
79
+
80
+ ```python
81
+ from datetime import timedelta
82
+
83
+
84
+ @schedule(cron=Cron(hour=4), max_duration=timedelta(minutes=15), regions=["fra1"])
85
+ def export_reports() -> None:
86
+ ...
87
+ ```
88
+
89
+ `max_duration` is a whole number of seconds, up to your plan's limit, and
90
+ defaults to the platform's default. Each firing runs once, in one of the
91
+ `regions`: the others are used only if it is unavailable, so pass one region
92
+ to choose where the schedule runs. `regions` defaults to the project's regions.
93
+
94
+ Schedules with the same settings run in one function, and each other
95
+ combination runs in a function of its own. Schedules in different functions do
96
+ not share a process, so they do not share module-level state such as a cache
97
+ or a connection pool.
98
+
99
+ Importing the module registers its schedules. `get_registered_schedules()`
100
+ returns them, and `RegisteredSchedule.run(metadata)` calls the handler for one
101
+ firing: a coroutine function is awaited, and a regular function runs in a
102
+ worker thread, with any awaitable it returns awaited too.
103
+
104
+ To handle a firing in your own route, such as a schedule that targets a path,
105
+ read it from the request headers with `ScheduleMetadata.from_headers()`:
106
+
107
+ ```python
108
+ from fastapi import FastAPI, Request
109
+ from vercel.schedules import ScheduleMetadata
110
+
111
+ app = FastAPI()
112
+
113
+
114
+ @app.post("/api/cleanup")
115
+ async def cleanup(request: Request) -> None:
116
+ metadata = ScheduleMetadata.from_headers(request.headers)
117
+ ...
118
+ ```
119
+
120
+ A request without a schedule CloudEvent, such as a legacy Cron Job, raises
121
+ `NotAScheduleInvocationError`. A path is public, so check
122
+ `authorization: Bearer <CRON_SECRET>` as you would for a Cron Job.
123
+
124
+ ## Manage schedules
125
+
126
+ A schedule fires on a cron cadence or once at a fixed time, and publishes to a
127
+ Vercel Queue topic. It is identified by its name within a namespace, which
128
+ defaults to `"default"`.
129
+
130
+ ```python
131
+ from datetime import timedelta
132
+ from vercel.schedules import Cron, create_schedule, query_schedules
133
+
134
+ schedule = await create_schedule(
135
+ "cleanup",
136
+ topic="scheduled-cleanup",
137
+ cron=Cron(hour=3), # every day at 03:00
138
+ jitter=timedelta(minutes=2),
139
+ payload={"max_age_days": 30},
140
+ )
141
+
142
+ async for schedule in query_schedules():
143
+ print(schedule.name, schedule.expression, schedule.is_active)
144
+ ```
145
+
146
+ `cron=` takes a `Cron` or a crontab string such as `"0 3 * * *"`. Fields you
147
+ leave out of a `Cron` default to `*`, except fields less significant than every
148
+ field you set, which default to their minimum, as in APScheduler's
149
+ `CronTrigger`. `Cron(hour=3)` is `0 3 * * *`, and `Cron(day=1)` is `0 0 1 * *`.
150
+ `str(cron)` renders the crontab expression, and `Cron.from_crontab()` parses one.
151
+
152
+ `jitter` spreads each firing over a random delay of 1 to 15 whole minutes.
153
+
154
+ ### Timezones
155
+
156
+ Cron expressions are evaluated in UTC unless you pass an IANA `timezone`:
157
+
158
+ ```python
159
+ await create_schedule(
160
+ "daily-report",
161
+ topic="send-report",
162
+ cron=Cron(hour=9),
163
+ timezone="America/Los_Angeles",
164
+ )
165
+ ```
166
+
167
+ Pass `at=` instead of `cron=` for a schedule that fires once. An aware
168
+ `datetime` carrying a `ZoneInfo` (or UTC) supplies the timezone itself. A naive
169
+ `datetime` needs an explicit `timezone=`:
170
+
171
+ ```python
172
+ from datetime import datetime, timezone
173
+ from zoneinfo import ZoneInfo
174
+
175
+ await create_schedule(
176
+ "launch",
177
+ topic="launch",
178
+ at=datetime(2026, 9, 16, 9, tzinfo=ZoneInfo("America/Los_Angeles")),
179
+ )
180
+
181
+ await create_schedule(
182
+ "follow-up",
183
+ topic="send-report",
184
+ at=datetime.now(timezone.utc) + timedelta(hours=1),
185
+ )
186
+ ```
187
+
188
+ Given both an aware `at` and `timezone`, `at` is converted into that timezone,
189
+ so the instant is preserved. One-off schedules have minute precision: a time
190
+ with seconds is rounded up to the next minute, so the schedule never fires
191
+ before `at`. Fixed-offset datetimes other than UTC are rejected because they
192
+ carry no IANA name.
193
+
194
+ ### Change, pause, and run schedules
195
+
196
+ `get_schedule`, `update_schedule`, `enable_schedule`, `disable_schedule`,
197
+ `invoke_schedule`, and `delete_schedule` take the schedule name and an optional
198
+ `namespace=`. A missing schedule raises `ScheduleNotFoundError`, which is also a
199
+ `LookupError`.
200
+
201
+ ```python
202
+ from datetime import datetime, timezone
203
+ from vercel.schedules import enable_schedule, invoke_schedule, update_schedule
204
+
205
+ await update_schedule("cleanup", cron="0 2 * * *", jitter=None) # jitter=None clears it
206
+ await invoke_schedule("cleanup") # fire now, outside the cadence
207
+ await enable_schedule("cleanup", until=datetime(2026, 12, 1, tzinfo=timezone.utc))
208
+ ```
209
+
210
+ Schedules declared in `vercel.json` can only be enabled or disabled through the
211
+ API. Other API errors raise `SchedulesApiError`, whose `code` names the reason,
212
+ such as `"schedule_already_exists"`, and whose `retry_after` holds the seconds
213
+ to wait after `"rate_limited"`.
214
+
215
+ The same surface is available synchronously, with identical names and arguments:
216
+
217
+ ```python
218
+ from vercel.schedules.sync import create_schedule, query_schedules
219
+
220
+ schedule = create_schedule("cleanup", topic="scheduled-cleanup", cron="0 * * * *")
221
+ for schedule in query_schedules():
222
+ ...
223
+ ```
224
+
225
+ ### Configuration
226
+
227
+ Requests authenticate with the deployment's Vercel OIDC token and target the
228
+ public Schedules service, overridable with `VERCEL_SCHEDULE_BASE_URL`. Override
229
+ either per session:
230
+
231
+ ```python
232
+ from vercel.api import session
233
+ from vercel.schedules import SchedulesServiceOptions, get_schedule, static_credentials_factory
234
+
235
+ options = SchedulesServiceOptions(
236
+ base_url="...",
237
+ credentials_factory=static_credentials_factory("..."),
238
+ )
239
+ async with session(service_options=[options]):
240
+ schedule = await get_schedule("cleanup")
241
+ ```
242
+
243
+ `credentials_factory` runs before each request, so it can return a refreshed
244
+ token. For sync calls, use `SchedulesServiceOptions` from
245
+ `vercel.schedules.sync` in a plain `with` block. Its `credentials_factory` is a
246
+ plain function, which may block. Mixing an async call into a sync session, or
247
+ the reverse, is rejected.
248
+
249
+ Under `vercel dev`, the SDK uses the local Schedules API that `vercel dev`
250
+ serves, with the token it provides. Elsewhere, run `vercel link` and
251
+ `vercel env pull` so an OIDC token is available, or pass a
252
+ `credentials_factory`.
253
+
254
+ ## Read the firing in a schedule command
255
+
256
+ A schedule with `run` builds the image from the Dockerfile in `root`, and runs
257
+ the command once per firing:
258
+
259
+ ```json
260
+ {
261
+ "schedules": {
262
+ "reindex": {
263
+ "schedule": "0 3 * * *",
264
+ "root": "jobs",
265
+ "entrypoint": "Dockerfile",
266
+ "run": ["python", "reindex.py"]
267
+ }
268
+ }
269
+ }
270
+ ```
271
+
272
+ The firing's metadata is in `VERCEL_SCHEDULE_*` environment variables.
273
+ `ScheduleMetadata.from_env()` reads them:
274
+
275
+ ```python
276
+ # jobs/reindex.py
277
+ from vercel.schedules import ScheduleMetadata
278
+
279
+ metadata = ScheduleMetadata.from_env()
280
+ print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")
281
+ ```
282
+
283
+ A non-zero exit status marks the firing as failed. Failed firings are not
284
+ retried.
285
+
286
+ Run by hand, without the variables, `from_env()` raises
287
+ `NotAScheduleInvocationError`. The package is optional here:
288
+ `os.environ["VERCEL_SCHEDULE_NAME"]` works too.
289
+
290
+ | Variable | `ScheduleMetadata` attribute |
291
+ | --- | --- |
292
+ | `VERCEL_SCHEDULE_ID` | `schedule_id` |
293
+ | `VERCEL_SCHEDULE_EXECUTION_ID` | `execution_id` |
294
+ | `VERCEL_SCHEDULE_NAME` | `name` |
295
+ | `VERCEL_SCHEDULE_NAMESPACE` | `namespace` |
296
+ | `VERCEL_SCHEDULE_SCHEDULED_AT` | `scheduled_at`, as an aware UTC `datetime` |
297
+ | `VERCEL_SCHEDULE_SOURCE` | `source` |
298
+ | `VERCEL_SCHEDULE_EXPRESSION` | `expression` |