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.
- vercel/schedules/__init__.py +314 -0
- vercel/schedules/_internal/api_client.py +500 -0
- vercel/schedules/_internal/async_runtime.py +124 -0
- vercel/schedules/_internal/base.py +47 -0
- vercel/schedules/_internal/errors.py +105 -0
- vercel/schedules/_internal/metadata.py +138 -0
- vercel/schedules/_internal/models.py +303 -0
- vercel/schedules/_internal/options.py +227 -0
- vercel/schedules/_internal/registry.py +354 -0
- vercel/schedules/_internal/service.py +328 -0
- vercel/schedules/_internal/sync_runtime.py +123 -0
- vercel/schedules/_vendor/__init__.py +1 -0
- vercel/schedules/py.typed +0 -0
- vercel/schedules/sync.py +319 -0
- vercel/schedules/version.py +1 -0
- vercel_schedules_bundle-0.1.0.dist-info/METADATA +302 -0
- vercel_schedules_bundle-0.1.0.dist-info/RECORD +19 -0
- vercel_schedules_bundle-0.1.0.dist-info/WHEEL +4 -0
- vercel_schedules_bundle-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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
|
+
]
|