vercel-schedules-bundle 0.1.0__py3-none-any.whl

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,314 @@
1
+ """Vercel Schedules SDK surface.
2
+
3
+ Schedules fire on a cron cadence or once at a fixed instant, and dispatch to a
4
+ Vercel Queue topic, a function, or a path. A schedule is identified by its name within a
5
+ namespace. Manage them with `create_schedule` and friends.
6
+
7
+ Declare a recurring schedule in code with `@schedule`. A schedule command runs
8
+ once per firing; read the firing with `ScheduleMetadata.from_env()`.
9
+
10
+ Requests authenticate with the deployment's Vercel OIDC token. Locally, run
11
+ `vercel env pull`, or pass
12
+ `SchedulesServiceOptions(credentials_factory=static_credentials_factory(token))`
13
+ in a session.
14
+ """
15
+
16
+ from collections.abc import AsyncIterator
17
+ from datetime import datetime, timedelta
18
+
19
+ from vercel._internal.core.sentinel import UNSET, UnsetType
20
+ from vercel._internal.core.session import get_active_session
21
+ from vercel.schedules._internal.async_runtime import (
22
+ create_schedule as _create_schedule,
23
+ delete_schedule as _delete_schedule,
24
+ disable_schedule as _disable_schedule,
25
+ enable_schedule as _enable_schedule,
26
+ get_schedule as _get_schedule,
27
+ invoke_schedule as _invoke_schedule,
28
+ query_schedules as _query_schedules,
29
+ update_schedule as _update_schedule,
30
+ )
31
+ from vercel.schedules._internal.errors import (
32
+ NotAScheduleInvocationError,
33
+ ScheduleEventParseError,
34
+ ScheduleNotFoundError,
35
+ SchedulesApiError,
36
+ SchedulesCredentialsError,
37
+ SchedulesError,
38
+ SchedulesResponseError,
39
+ SchedulesValidationError,
40
+ )
41
+ from vercel.schedules._internal.metadata import ScheduleMetadata
42
+ from vercel.schedules._internal.models import (
43
+ MAX_JITTER,
44
+ MIN_JITTER,
45
+ Cron,
46
+ CronField,
47
+ FunctionTarget,
48
+ JSONValue,
49
+ OneOffExpression,
50
+ PathTarget,
51
+ QueueTarget,
52
+ Schedule,
53
+ ScheduleExpression,
54
+ ScheduleSource,
55
+ ScheduleState,
56
+ ScheduleTarget,
57
+ )
58
+ from vercel.schedules._internal.options import (
59
+ DEFAULT_SCHEDULES_BASE_URL,
60
+ SchedulesCredentialsFactory,
61
+ SchedulesServiceOptions,
62
+ static_credentials_factory,
63
+ )
64
+ from vercel.schedules._internal.registry import (
65
+ RegisteredSchedule,
66
+ get_registered_schedules,
67
+ schedule,
68
+ )
69
+ from vercel.schedules._internal.service import SchedulesService, get_schedules_service
70
+ from vercel.schedules.version import __version__
71
+
72
+ from . import sync
73
+
74
+
75
+ def _service() -> SchedulesService:
76
+ return get_schedules_service(get_active_session())
77
+
78
+
79
+ async def create_schedule(
80
+ name: str,
81
+ *,
82
+ topic: str,
83
+ cron: str | Cron | None = None,
84
+ at: datetime | None = None,
85
+ timezone: str | None = None,
86
+ namespace: str | None = None,
87
+ jitter: timedelta | None = None,
88
+ payload: JSONValue = UNSET,
89
+ ) -> Schedule:
90
+ """Create a schedule that dispatches to a queue topic.
91
+
92
+ Pass exactly one of `cron` (recurring) or `at` (fires once).
93
+
94
+ Args:
95
+ name: Schedule name, unique within the project and namespace.
96
+ topic: Queue topic each firing is sent to.
97
+ cron: When a recurring schedule fires, as a `Cron` or a five-field
98
+ crontab string such as `"0 3 * * *"`, evaluated in `timezone`.
99
+ at: When a one-off schedule fires. An aware datetime with a `ZoneInfo`
100
+ (or UTC) supplies the timezone itself; a naive datetime needs
101
+ `timezone`. Given both, `at` is converted into `timezone`. One-off
102
+ schedules have minute precision, so a time with seconds is rounded
103
+ up to the next minute.
104
+ timezone: IANA timezone name, such as `"America/Los_Angeles"`. The
105
+ service defaults to UTC.
106
+ namespace: Namespace to group schedules under. The service uses
107
+ `"default"` when omitted.
108
+ jitter: Random delay added to each firing, in whole minutes, between
109
+ one and fifteen minutes inclusive.
110
+ payload: JSON-serializable value delivered with each firing. Passing
111
+ `None` explicitly configures a JSON `null`; omitting it configures
112
+ no payload.
113
+
114
+ Returns:
115
+ The created schedule.
116
+
117
+ Raises:
118
+ SchedulesValidationError: If the arguments are inconsistent, such as
119
+ both `cron` and `at`, a naive `at` without `timezone`, a malformed
120
+ crontab string, or a `jitter` outside the allowed range.
121
+ SchedulesApiError: If the service rejects the request.
122
+ """
123
+ return await _create_schedule(
124
+ _service(),
125
+ name,
126
+ topic=topic,
127
+ cron=cron,
128
+ at=at,
129
+ timezone=timezone,
130
+ namespace=namespace,
131
+ jitter=jitter,
132
+ payload=payload,
133
+ )
134
+
135
+
136
+ def query_schedules(
137
+ *,
138
+ namespace: str | None = None,
139
+ page_size: int | None = None,
140
+ ) -> AsyncIterator[Schedule]:
141
+ """Iterate over the project's schedules.
142
+
143
+ Args:
144
+ namespace: Only schedules in this namespace.
145
+ page_size: Maximum number of schedules fetched per API request.
146
+
147
+ Returns:
148
+ An iterator that transparently follows pagination cursors.
149
+ """
150
+ return _query_schedules(_service(), namespace=namespace, page_size=page_size)
151
+
152
+
153
+ async def get_schedule(name: str, *, namespace: str | None = None) -> Schedule:
154
+ """Fetch one schedule by name.
155
+
156
+ Args:
157
+ name: Schedule name.
158
+ namespace: Namespace the schedule lives in; the service default when
159
+ omitted.
160
+
161
+ Raises:
162
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
163
+ """
164
+ return await _get_schedule(_service(), name, namespace=namespace)
165
+
166
+
167
+ async def update_schedule(
168
+ name: str,
169
+ *,
170
+ namespace: str | None = None,
171
+ cron: str | Cron | None = None,
172
+ at: datetime | None = None,
173
+ timezone: str | None = None,
174
+ topic: str | None = None,
175
+ jitter: timedelta | None | UnsetType = UNSET,
176
+ payload: JSONValue = UNSET,
177
+ ) -> Schedule:
178
+ """Change a schedule's configuration. Omitted fields are left as they are.
179
+
180
+ Args:
181
+ name: Schedule name.
182
+ namespace: Namespace the schedule lives in; the service default when
183
+ omitted.
184
+ cron: New cron expression, as a `Cron` or a crontab string. Mutually
185
+ exclusive with `at`.
186
+ at: New one-off firing time; same rules as in `create_schedule`.
187
+ timezone: New IANA timezone. Also applied when the expression changes.
188
+ topic: New queue topic to dispatch to.
189
+ jitter: New jitter, between one and fifteen minutes inclusive. Pass
190
+ `None` to remove the jitter.
191
+ payload: New payload. Pass `None` to remove the payload.
192
+
193
+ Returns:
194
+ The updated schedule.
195
+
196
+ Raises:
197
+ SchedulesValidationError: If nothing would change, or an argument is
198
+ invalid.
199
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
200
+ """
201
+ return await _update_schedule(
202
+ _service(),
203
+ name,
204
+ namespace=namespace,
205
+ cron=cron,
206
+ at=at,
207
+ timezone=timezone,
208
+ topic=topic,
209
+ jitter=jitter,
210
+ payload=payload,
211
+ )
212
+
213
+
214
+ async def delete_schedule(name: str, *, namespace: str | None = None) -> None:
215
+ """Delete a schedule. Pending firings are dropped.
216
+
217
+ Raises:
218
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
219
+ """
220
+ await _delete_schedule(_service(), name, namespace=namespace)
221
+
222
+
223
+ async def enable_schedule(
224
+ name: str, *, namespace: str | None = None, until: datetime | None = None
225
+ ) -> Schedule:
226
+ """Resume a disabled schedule.
227
+
228
+ Args:
229
+ name: Schedule name.
230
+ namespace: Namespace the schedule lives in; the service default when
231
+ omitted.
232
+ until: Enable the schedule only until this aware datetime, after which
233
+ it is disabled again. It must be in the future, and replaces the
234
+ time on a schedule already enabled until one. Omit it to enable
235
+ the schedule indefinitely, which also clears any existing time.
236
+
237
+ Returns:
238
+ The updated schedule.
239
+
240
+ Raises:
241
+ SchedulesValidationError: If `until` is naive.
242
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
243
+ """
244
+ return await _enable_schedule(_service(), name, namespace=namespace, until=until)
245
+
246
+
247
+ async def disable_schedule(name: str, *, namespace: str | None = None) -> Schedule:
248
+ """Pause a schedule without deleting it.
249
+
250
+ Returns:
251
+ The updated schedule.
252
+
253
+ Raises:
254
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
255
+ """
256
+ return await _disable_schedule(_service(), name, namespace=namespace)
257
+
258
+
259
+ async def invoke_schedule(name: str, *, namespace: str | None = None) -> None:
260
+ """Fire a schedule now, outside its regular cadence.
261
+
262
+ Returns once the service has accepted the firing; the dispatch itself runs
263
+ asynchronously.
264
+
265
+ Raises:
266
+ ScheduleNotFoundError: If no schedule has this name in the namespace.
267
+ """
268
+ await _invoke_schedule(_service(), name, namespace=namespace)
269
+
270
+
271
+ # Only add public symbols to __all__; internal helpers must stay unexported.
272
+ __all__ = [
273
+ "DEFAULT_SCHEDULES_BASE_URL",
274
+ "MAX_JITTER",
275
+ "MIN_JITTER",
276
+ "UNSET",
277
+ "Cron",
278
+ "CronField",
279
+ "FunctionTarget",
280
+ "JSONValue",
281
+ "NotAScheduleInvocationError",
282
+ "OneOffExpression",
283
+ "PathTarget",
284
+ "QueueTarget",
285
+ "RegisteredSchedule",
286
+ "Schedule",
287
+ "ScheduleEventParseError",
288
+ "ScheduleExpression",
289
+ "ScheduleMetadata",
290
+ "ScheduleNotFoundError",
291
+ "ScheduleSource",
292
+ "ScheduleState",
293
+ "ScheduleTarget",
294
+ "SchedulesApiError",
295
+ "SchedulesCredentialsError",
296
+ "SchedulesCredentialsFactory",
297
+ "SchedulesError",
298
+ "SchedulesResponseError",
299
+ "SchedulesServiceOptions",
300
+ "SchedulesValidationError",
301
+ "__version__",
302
+ "create_schedule",
303
+ "delete_schedule",
304
+ "disable_schedule",
305
+ "enable_schedule",
306
+ "get_registered_schedules",
307
+ "get_schedule",
308
+ "invoke_schedule",
309
+ "query_schedules",
310
+ "schedule",
311
+ "static_credentials_factory",
312
+ "sync",
313
+ "update_schedule",
314
+ ]