vercel-workflow 0.9.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,67 @@
1
+ from vercel.workflow._internal.core import (
2
+ BaseHook,
3
+ HookEvent,
4
+ Workflows,
5
+ now,
6
+ random,
7
+ sleep,
8
+ time_ns,
9
+ )
10
+ from vercel.workflow._internal.runtime import (
11
+ Run,
12
+ StepInfo,
13
+ get_step_metadata,
14
+ get_writable,
15
+ read_stream,
16
+ start,
17
+ )
18
+ from vercel.workflow._internal.serde import register_serializable, serializable
19
+ from vercel.workflow._internal.streams import (
20
+ WorkflowStreamHandle,
21
+ WorkflowStreamWriter,
22
+ WorkflowWritable,
23
+ )
24
+
25
+ from . import sandbox
26
+ from .errors import (
27
+ EntityConflictError,
28
+ FatalError,
29
+ HookNotFoundError,
30
+ RunExpiredError,
31
+ SerializationError,
32
+ ThrottleError,
33
+ TooEarlyError,
34
+ WorkflowWorldError,
35
+ )
36
+ from .sandbox import SandboxPolicy
37
+
38
+ __all__ = [
39
+ "Workflows",
40
+ "now",
41
+ "random",
42
+ "sleep",
43
+ "start",
44
+ "time_ns",
45
+ "Run",
46
+ "BaseHook",
47
+ "HookEvent",
48
+ "get_step_metadata",
49
+ "get_writable",
50
+ "read_stream",
51
+ "WorkflowWritable",
52
+ "WorkflowStreamWriter",
53
+ "WorkflowStreamHandle",
54
+ "StepInfo",
55
+ "serializable",
56
+ "register_serializable",
57
+ "EntityConflictError",
58
+ "FatalError",
59
+ "HookNotFoundError",
60
+ "RunExpiredError",
61
+ "SerializationError",
62
+ "ThrottleError",
63
+ "TooEarlyError",
64
+ "WorkflowWorldError",
65
+ "sandbox",
66
+ "SandboxPolicy",
67
+ ]
File without changes
@@ -0,0 +1,328 @@
1
+ from __future__ import annotations
2
+
3
+ import dataclasses
4
+ import datetime
5
+ import functools
6
+ import inspect
7
+ import random as _random
8
+ from collections.abc import AsyncIterator, Callable, Coroutine, Generator
9
+ from typing import TYPE_CHECKING, Any, Generic, ParamSpec, TypeVar, overload
10
+
11
+ import pydantic
12
+
13
+ from vercel._internal.core.polyfills import Self
14
+
15
+ from . import py_sandbox
16
+ from .world import validate_queue_namespace
17
+
18
+ if TYPE_CHECKING:
19
+ from . import world as w
20
+
21
+
22
+ P = ParamSpec("P")
23
+ T = TypeVar("T")
24
+
25
+ DEFAULT_MAX_RETRIES = 3
26
+
27
+
28
+ def _bind_arguments(
29
+ signature: inspect.Signature,
30
+ qualname: str,
31
+ args: tuple[Any, ...],
32
+ kwargs: dict[str, Any],
33
+ ) -> tuple[tuple[Any, ...], dict[str, Any]]:
34
+ """Split a call by what the callee's parameters can be *named*.
35
+
36
+ A value whose parameter has a usable name is recorded by name; only a
37
+ parameter that cannot be named -- positional-only (before a `/`) or
38
+ `*args` -- is recorded by position. So against
39
+ `async def charge(amount=1, currency="usd", *, tier="basic")`:
40
+
41
+ charge(21) -> [{"amount": 21}]
42
+ charge(amount=21) -> [{"amount": 21}]
43
+ charge(21, "eur") -> [{"amount": 21, "currency": "eur"}]
44
+ charge(21, currency="eur") -> [{"amount": 21, "currency": "eur"}]
45
+ charge(currency="eur") -> [{"currency": "eur"}]
46
+
47
+ ...and against `async def notify(total, /, *rest)`:
48
+
49
+ notify(42) -> [42]
50
+ notify(42, "now") -> [42, "now"]
51
+
52
+ So the same values record the same bytes however the call was spelled, which
53
+ matters because the step-input determinism check compares recorded bytes
54
+ against freshly encoded ones: rewriting `charge(21)` as `charge(amount=21)`
55
+ stays cosmetic instead of failing an in-flight run.
56
+
57
+ Recording by name also survives a reorder -- swapping two parameters cannot
58
+ silently swap the values of a run already in flight, and a rename fails
59
+ loudly. Recording by position gives that up in exchange for the shape
60
+ TypeScript writes, which is why it takes a `/` to ask for.
61
+
62
+ Defaults are deliberately not applied, so an omitted default stays off the
63
+ wire and adding a parameter with one remains replay-safe.
64
+
65
+ `bind` is here to resolve values to parameter names, and for its arity check,
66
+ which reports a bad call as an ordinary `TypeError` here rather than inside
67
+ the decoder or during replay. The split below is recomputed from each
68
+ parameter's kind rather than taken from `BoundArguments.args` / `.kwargs`,
69
+ which split on position instead.
70
+ """
71
+ try:
72
+ bound = signature.bind(*args, **kwargs)
73
+ except TypeError as error:
74
+ # `bind` phrases these as "missing a required argument: 'amount'"; the
75
+ # name is what the caller lacks, since `start(wf, ...)` and a step call
76
+ # both put the traceback frame somewhere other than the definition.
77
+ raise TypeError(f"{qualname}() {error}") from None
78
+
79
+ positional: list[Any] = []
80
+ keyword: dict[str, Any] = {}
81
+ # Signature order, so a positional-only parameter keeps its slot ahead of
82
+ # whatever `*args` contributes.
83
+ for name, param in signature.parameters.items():
84
+ if name not in bound.arguments:
85
+ continue
86
+ value = bound.arguments[name]
87
+ if param.kind is param.POSITIONAL_ONLY:
88
+ positional.append(value)
89
+ elif param.kind is param.VAR_POSITIONAL:
90
+ positional.extend(value)
91
+ elif param.kind is param.VAR_KEYWORD:
92
+ keyword.update(value)
93
+ else:
94
+ keyword[name] = value
95
+ return tuple(positional), keyword
96
+
97
+
98
+ class Workflow(Generic[P, T]):
99
+ def __init__(
100
+ self,
101
+ func: Callable[P, Coroutine[Any, Any, T]],
102
+ *,
103
+ registry: Workflows,
104
+ ):
105
+ self.func = func
106
+ self._registry = registry
107
+ self.module = func.__module__
108
+ self.qualname = func.__qualname__
109
+ self.workflow_id = f"workflow//{self.module}//{self.qualname}"
110
+ self._signature = inspect.signature(func)
111
+
112
+ def bind_arguments(
113
+ self, args: tuple[Any, ...], kwargs: dict[str, Any]
114
+ ) -> tuple[tuple[Any, ...], dict[str, Any]]:
115
+ return _bind_arguments(self._signature, self.qualname, args, kwargs)
116
+
117
+ def _resolve_queue_namespace(self) -> str | None:
118
+ return self._registry.namespace
119
+
120
+
121
+ class Step(Generic[P, T]):
122
+ def __init__(
123
+ self, func: Callable[P, Coroutine[Any, Any, T]], *, max_retries: int = DEFAULT_MAX_RETRIES
124
+ ):
125
+ self.func = func
126
+ self.name = f"step//{func.__module__}//{func.__qualname__}"
127
+ self.max_retries = max_retries
128
+ self._signature = inspect.signature(func)
129
+ functools.update_wrapper(self, func)
130
+
131
+ def bind_arguments(
132
+ self, args: tuple[Any, ...], kwargs: dict[str, Any]
133
+ ) -> tuple[tuple[Any, ...], dict[str, Any]]:
134
+ return _bind_arguments(self._signature, self.func.__qualname__, args, kwargs)
135
+
136
+ async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
137
+ from . import runtime
138
+
139
+ try:
140
+ ctx = runtime.WorkflowOrchestratorContext.current()
141
+ except LookupError:
142
+ raise RuntimeError(
143
+ "cannot call step outside workflow; use a wrapper function instead"
144
+ ) from None
145
+
146
+ return await ctx.run_step(self, *args, **kwargs)
147
+
148
+
149
+ async def sleep(param: int | float | datetime.datetime | str) -> None:
150
+ from . import runtime
151
+
152
+ try:
153
+ ctx = runtime.WorkflowOrchestratorContext.current()
154
+ except LookupError:
155
+ raise RuntimeError("cannot call sleep outside workflow") from None
156
+
157
+ await ctx.run_wait(param)
158
+
159
+
160
+ def now() -> datetime.datetime:
161
+ from . import runtime
162
+
163
+ try:
164
+ ctx = runtime.WorkflowOrchestratorContext.current()
165
+ except LookupError:
166
+ raise RuntimeError("cannot call now() outside workflow") from None
167
+
168
+ return ctx.now()
169
+
170
+
171
+ def time_ns() -> int:
172
+ from . import runtime
173
+
174
+ try:
175
+ ctx = runtime.WorkflowOrchestratorContext.current()
176
+ except LookupError:
177
+ raise RuntimeError("cannot call time_ns() outside workflow") from None
178
+
179
+ return ctx.time_ns()
180
+
181
+
182
+ def random() -> _random.Random:
183
+ from . import runtime
184
+
185
+ try:
186
+ ctx = runtime.WorkflowOrchestratorContext.current()
187
+ except LookupError:
188
+ raise RuntimeError("cannot call random() outside workflow") from None
189
+
190
+ return ctx.random()
191
+
192
+
193
+ class HookEvent(Generic[T]):
194
+ def __init__(self, *, correlation_id: str, token: str) -> None:
195
+ self._correlation_id = correlation_id
196
+ self._token = token
197
+ self._disposed = False
198
+
199
+ def __await__(self) -> Generator[Any, None, T | None]:
200
+ async def next_or_none() -> T | None:
201
+ try:
202
+ return await self.__anext__()
203
+ except StopAsyncIteration:
204
+ return None
205
+
206
+ return next_or_none().__await__()
207
+
208
+ def __aiter__(self) -> AsyncIterator[T]:
209
+ return self
210
+
211
+ async def __anext__(self) -> T:
212
+ from . import runtime
213
+
214
+ try:
215
+ ctx = runtime.WorkflowOrchestratorContext.current()
216
+ except LookupError:
217
+ raise RuntimeError("cannot iterate HookEvent outside workflow") from None
218
+
219
+ return await ctx.run_hook(correlation_id=self._correlation_id)
220
+
221
+ def dispose(self) -> None:
222
+ if self._disposed:
223
+ return
224
+
225
+ from . import runtime
226
+
227
+ try:
228
+ ctx = runtime.WorkflowOrchestratorContext.current()
229
+ except LookupError:
230
+ raise RuntimeError("cannot call dispose() outside workflow") from None
231
+
232
+ self._disposed = True
233
+ ctx.dispose_hook(correlation_id=self._correlation_id)
234
+
235
+
236
+ class BaseHook:
237
+ @classmethod
238
+ def wait(cls, *, token: str | None = None) -> HookEvent[Self]:
239
+ from . import runtime
240
+
241
+ try:
242
+ ctx = runtime.WorkflowOrchestratorContext.current()
243
+ except LookupError:
244
+ raise RuntimeError("cannot call wait() outside workflow") from None
245
+ else:
246
+ return ctx.create_hook(token, cls)
247
+
248
+ async def resume(self, token_or_hook: str | w.Hook, **kwargs) -> w.Hook:
249
+ from . import runtime
250
+
251
+ try:
252
+ runtime.WorkflowOrchestratorContext.current()
253
+ except LookupError:
254
+ pass
255
+ else:
256
+ raise RuntimeError("cannot call resume() inside workflow")
257
+
258
+ if isinstance(self, pydantic.BaseModel):
259
+ payload = self.model_dump(**{"mode": "python", **kwargs})
260
+ elif dataclasses.is_dataclass(self):
261
+ payload = dataclasses.asdict(self, **kwargs)
262
+ else:
263
+ raise TypeError("resume only supports pydantic models or dataclasses")
264
+
265
+ return await runtime.resume_hook(token_or_hook, payload)
266
+
267
+
268
+ class Workflows:
269
+ def __init__(
270
+ self,
271
+ *,
272
+ as_vercel_job: bool = True,
273
+ namespace: str | None = None,
274
+ sandbox_policy: py_sandbox.SandboxPolicy | None = None,
275
+ ):
276
+ validate_queue_namespace(namespace)
277
+
278
+ self._namespace = namespace
279
+ self._workflows: dict[str, Workflow] = {}
280
+ self._steps: dict[str, Step] = {}
281
+ if sandbox_policy is None:
282
+ sandbox_policy = py_sandbox.SandboxPolicy()
283
+ self._sandbox_policy = sandbox_policy
284
+ if as_vercel_job and not py_sandbox.in_sandbox():
285
+ from . import runtime
286
+
287
+ runtime.workflow_entrypoint(self)
288
+
289
+ @property
290
+ def namespace(self) -> str | None:
291
+ """The immutable queue namespace for this registry."""
292
+ return self._namespace
293
+
294
+ def workflow(self, func: Callable[P, Coroutine[Any, Any, T]]) -> Workflow[P, T]:
295
+ rv = Workflow(func, registry=self)
296
+ assert rv.workflow_id not in self._workflows, f"Duplicate workflow ID: {rv.workflow_id}"
297
+ self._workflows[rv.workflow_id] = rv
298
+ return rv
299
+
300
+ def _get_workflow(self, workflow_id: str) -> Workflow[Any, Any]:
301
+ return self._workflows[workflow_id]
302
+
303
+ @overload
304
+ def step(self, func: Callable[P, Coroutine[Any, Any, T]]) -> Step[P, T]: ...
305
+
306
+ @overload
307
+ def step(
308
+ self, *, max_retries: int = ...
309
+ ) -> Callable[[Callable[P, Coroutine[Any, Any, T]]], Step[P, T]]: ...
310
+
311
+ def step(
312
+ self,
313
+ func: Callable[P, Coroutine[Any, Any, T]] | None = None,
314
+ *,
315
+ max_retries: int = DEFAULT_MAX_RETRIES,
316
+ ) -> Step[P, T] | Callable[[Callable[P, Coroutine[Any, Any, T]]], Step[P, T]]:
317
+ def register(f: Callable[P, Coroutine[Any, Any, T]]) -> Step[P, T]:
318
+ rv = Step(f, max_retries=max_retries)
319
+ assert rv.name not in self._steps, f"Duplicate step name: {rv.name}"
320
+ self._steps[rv.name] = rv
321
+ return rv
322
+
323
+ if func is None:
324
+ return register
325
+ return register(func)
326
+
327
+ def _get_step(self, step_name: str) -> Step[Any, Any]:
328
+ return self._steps[step_name]
@@ -0,0 +1,21 @@
1
+ """Minimal Python port of the JavaScript *devalue* serialization library.
2
+
3
+ Wire-format compatible with https://github.com/sveltejs/devalue — values
4
+ serialized by Python ``stringify`` can be parsed by JS ``devalue.parse`` and
5
+ vice-versa.
6
+ """
7
+
8
+ from .parse import parse, unflatten
9
+ from .stringify import stringify
10
+ from .utils import DevalueError, Hole, JsBigInt, JsRegExp, Undefined
11
+
12
+ __all__ = [
13
+ "DevalueError",
14
+ "Hole",
15
+ "JsBigInt",
16
+ "JsRegExp",
17
+ "Undefined",
18
+ "parse",
19
+ "stringify",
20
+ "unflatten",
21
+ ]
@@ -0,0 +1,26 @@
1
+ """Constants matching the JavaScript devalue library wire format."""
2
+
3
+ UNDEFINED = -1
4
+ HOLE = -2
5
+ NAN = -3
6
+ POSITIVE_INFINITY = -4
7
+ NEGATIVE_INFINITY = -5
8
+ NEGATIVE_ZERO = -6
9
+ SPARSE = -7
10
+
11
+ # The largest valid value for a JavaScript array's `length` property,
12
+ # and the largest valid array index (one less than the max length).
13
+ MAX_ARRAY_LEN = 2**32 - 1
14
+ MAX_ARRAY_INDEX = MAX_ARRAY_LEN - 1
15
+
16
+ # The largest exactly-representable integer in a JS `number`. Python ints
17
+ # beyond this range are serialized as `["BigInt", …]` so that JS `parse`
18
+ # recovers the exact value instead of a rounded float.
19
+ MAX_SAFE_INTEGER = 2**53 - 1
20
+
21
+ # JS hydrates a sparse array into a dictionary-mode array, so a declared
22
+ # length costs nothing until the slots are populated. Python lists are
23
+ # dense, so `[Undefined] * length` allocates eagerly and a tiny payload such
24
+ # as `[[-7,4294967295]]` would demand tens of gigabytes. Reject declared
25
+ # lengths above this bound rather than trying to honour them.
26
+ MAX_SPARSE_ARRAY_LENGTH = 2**22