peffect 0.1.2__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.
peffect/core.py ADDED
@@ -0,0 +1,1273 @@
1
+ """The kernel: Effect nodes, stack frames, and the combinators derived from them.
2
+
3
+ An Effect is a *description*. Nothing runs until a Fiber (fiber.py) evaluates it. The fiber's run
4
+ loop calls ``node._eval(fiber)``, which returns the NEXT node to evaluate (or None: "parked").
5
+ Combinators never call each other recursively; they push frames on the fiber's stack. That's what
6
+ keeps a million ``flat_map``s from blowing Python's recursion limit.
7
+
8
+ Seven nodes (Effect v4: internal/core.ts, internal/effect.ts):
9
+
10
+ Success(a) done: hand a to the next on_ok frame
11
+ Failure(cause) done: hand cause to the next on_err frame
12
+ Sync(thunk) run a side effect now
13
+ Suspend(thunk) build the next effect lazily
14
+ Async(register) park until resume(effect) is called, once
15
+ WithFiber(f) look at / change the running fiber
16
+ YieldNow queue the next step on the fiber's dispatcher
17
+
18
+ Frames (pushed on the stack; up to three hooks):
19
+
20
+ on_ok(value) success arrives
21
+ on_err(cause) failure arrives
22
+ on_any(ok) runs whenever the frame is popped, even if it's being skipped
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import asyncio
28
+ import inspect
29
+ from collections.abc import Awaitable, Callable, Generator, Mapping
30
+ from functools import wraps
31
+ from types import MappingProxyType
32
+ from typing import TYPE_CHECKING, Any, ClassVar, Generic, Never, TypeVar, cast, final, overload
33
+
34
+ from peffect.cause import Cause, Interrupt
35
+
36
+ if TYPE_CHECKING:
37
+ from peffect.fiber import Fiber, SchedulerDispatcher
38
+
39
+ A_co = TypeVar("A_co", covariant=True)
40
+ E_co = TypeVar("E_co", covariant=True)
41
+ R_co = TypeVar("R_co", covariant=True)
42
+
43
+ type AnyEffect = Effect[Any, Any, Any]
44
+ type AnyFiber = Fiber[Any, Any]
45
+ type _F[X, Y] = Callable[[X], Y]
46
+ """One pipe step: what `Effect.pipe` and the pipeables take."""
47
+ type ContextMap = Mapping[str, Any]
48
+ """A fiber's services, keyed by tag key string. Read-only: update_context installs a fresh copy."""
49
+
50
+ EMPTY_CONTEXT: ContextMap = MappingProxyType({})
51
+
52
+
53
+ class Effect(Generic[A_co, E_co, R_co]):
54
+ """A program that succeeds with A, fails with E, and needs services R. Lazy and reusable."""
55
+
56
+ __slots__ = ()
57
+
58
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
59
+ raise NotImplementedError
60
+
61
+ # `x = yield from eff` inside @gen: yield this effect, receive its success value.
62
+ def __iter__(self) -> Generator[Effect[A_co, E_co, R_co], Any, A_co]:
63
+ return cast(A_co, (yield self))
64
+
65
+ # pipe(f1, ..., fn): each step gets the previous result, left to right. 0-20 steps, like
66
+ # upstream's Pipeable overloads (Pipeable.ts:46-526); nest a second pipe for more.
67
+ @overload
68
+ def pipe(self, /) -> Effect[A_co, E_co, R_co]: ...
69
+ @overload
70
+ def pipe[T1](self, f1: _F[Effect[A_co, E_co, R_co], T1], /) -> T1: ...
71
+ @overload
72
+ def pipe[T1, T2](self, f1: _F[Effect[A_co, E_co, R_co], T1], f2: _F[T1, T2], /) -> T2: ...
73
+ @overload
74
+ def pipe[T1, T2, T3](
75
+ self,
76
+ f1: _F[Effect[A_co, E_co, R_co], T1],
77
+ f2: _F[T1, T2],
78
+ f3: _F[T2, T3],
79
+ /,
80
+ ) -> T3: ...
81
+ @overload
82
+ def pipe[T1, T2, T3, T4](
83
+ self,
84
+ f1: _F[Effect[A_co, E_co, R_co], T1],
85
+ f2: _F[T1, T2],
86
+ f3: _F[T2, T3],
87
+ f4: _F[T3, T4],
88
+ /,
89
+ ) -> T4: ...
90
+ @overload
91
+ def pipe[T1, T2, T3, T4, T5](
92
+ self,
93
+ f1: _F[Effect[A_co, E_co, R_co], T1],
94
+ f2: _F[T1, T2],
95
+ f3: _F[T2, T3],
96
+ f4: _F[T3, T4],
97
+ f5: _F[T4, T5],
98
+ /,
99
+ ) -> T5: ...
100
+ @overload
101
+ def pipe[T1, T2, T3, T4, T5, T6](
102
+ self,
103
+ f1: _F[Effect[A_co, E_co, R_co], T1],
104
+ f2: _F[T1, T2],
105
+ f3: _F[T2, T3],
106
+ f4: _F[T3, T4],
107
+ f5: _F[T4, T5],
108
+ f6: _F[T5, T6],
109
+ /,
110
+ ) -> T6: ...
111
+ @overload
112
+ def pipe[T1, T2, T3, T4, T5, T6, T7](
113
+ self,
114
+ f1: _F[Effect[A_co, E_co, R_co], T1],
115
+ f2: _F[T1, T2],
116
+ f3: _F[T2, T3],
117
+ f4: _F[T3, T4],
118
+ f5: _F[T4, T5],
119
+ f6: _F[T5, T6],
120
+ f7: _F[T6, T7],
121
+ /,
122
+ ) -> T7: ...
123
+ @overload
124
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8](
125
+ self,
126
+ f1: _F[Effect[A_co, E_co, R_co], T1],
127
+ f2: _F[T1, T2],
128
+ f3: _F[T2, T3],
129
+ f4: _F[T3, T4],
130
+ f5: _F[T4, T5],
131
+ f6: _F[T5, T6],
132
+ f7: _F[T6, T7],
133
+ f8: _F[T7, T8],
134
+ /,
135
+ ) -> T8: ...
136
+ @overload
137
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9](
138
+ self,
139
+ f1: _F[Effect[A_co, E_co, R_co], T1],
140
+ f2: _F[T1, T2],
141
+ f3: _F[T2, T3],
142
+ f4: _F[T3, T4],
143
+ f5: _F[T4, T5],
144
+ f6: _F[T5, T6],
145
+ f7: _F[T6, T7],
146
+ f8: _F[T7, T8],
147
+ f9: _F[T8, T9],
148
+ /,
149
+ ) -> T9: ...
150
+ @overload
151
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10](
152
+ self,
153
+ f1: _F[Effect[A_co, E_co, R_co], T1],
154
+ f2: _F[T1, T2],
155
+ f3: _F[T2, T3],
156
+ f4: _F[T3, T4],
157
+ f5: _F[T4, T5],
158
+ f6: _F[T5, T6],
159
+ f7: _F[T6, T7],
160
+ f8: _F[T7, T8],
161
+ f9: _F[T8, T9],
162
+ f10: _F[T9, T10],
163
+ /,
164
+ ) -> T10: ...
165
+ @overload
166
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11](
167
+ self,
168
+ f1: _F[Effect[A_co, E_co, R_co], T1],
169
+ f2: _F[T1, T2],
170
+ f3: _F[T2, T3],
171
+ f4: _F[T3, T4],
172
+ f5: _F[T4, T5],
173
+ f6: _F[T5, T6],
174
+ f7: _F[T6, T7],
175
+ f8: _F[T7, T8],
176
+ f9: _F[T8, T9],
177
+ f10: _F[T9, T10],
178
+ f11: _F[T10, T11],
179
+ /,
180
+ ) -> T11: ...
181
+ @overload
182
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12](
183
+ self,
184
+ f1: _F[Effect[A_co, E_co, R_co], T1],
185
+ f2: _F[T1, T2],
186
+ f3: _F[T2, T3],
187
+ f4: _F[T3, T4],
188
+ f5: _F[T4, T5],
189
+ f6: _F[T5, T6],
190
+ f7: _F[T6, T7],
191
+ f8: _F[T7, T8],
192
+ f9: _F[T8, T9],
193
+ f10: _F[T9, T10],
194
+ f11: _F[T10, T11],
195
+ f12: _F[T11, T12],
196
+ /,
197
+ ) -> T12: ...
198
+ @overload
199
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13](
200
+ self,
201
+ f1: _F[Effect[A_co, E_co, R_co], T1],
202
+ f2: _F[T1, T2],
203
+ f3: _F[T2, T3],
204
+ f4: _F[T3, T4],
205
+ f5: _F[T4, T5],
206
+ f6: _F[T5, T6],
207
+ f7: _F[T6, T7],
208
+ f8: _F[T7, T8],
209
+ f9: _F[T8, T9],
210
+ f10: _F[T9, T10],
211
+ f11: _F[T10, T11],
212
+ f12: _F[T11, T12],
213
+ f13: _F[T12, T13],
214
+ /,
215
+ ) -> T13: ...
216
+ @overload
217
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14](
218
+ self,
219
+ f1: _F[Effect[A_co, E_co, R_co], T1],
220
+ f2: _F[T1, T2],
221
+ f3: _F[T2, T3],
222
+ f4: _F[T3, T4],
223
+ f5: _F[T4, T5],
224
+ f6: _F[T5, T6],
225
+ f7: _F[T6, T7],
226
+ f8: _F[T7, T8],
227
+ f9: _F[T8, T9],
228
+ f10: _F[T9, T10],
229
+ f11: _F[T10, T11],
230
+ f12: _F[T11, T12],
231
+ f13: _F[T12, T13],
232
+ f14: _F[T13, T14],
233
+ /,
234
+ ) -> T14: ...
235
+ @overload
236
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15](
237
+ self,
238
+ f1: _F[Effect[A_co, E_co, R_co], T1],
239
+ f2: _F[T1, T2],
240
+ f3: _F[T2, T3],
241
+ f4: _F[T3, T4],
242
+ f5: _F[T4, T5],
243
+ f6: _F[T5, T6],
244
+ f7: _F[T6, T7],
245
+ f8: _F[T7, T8],
246
+ f9: _F[T8, T9],
247
+ f10: _F[T9, T10],
248
+ f11: _F[T10, T11],
249
+ f12: _F[T11, T12],
250
+ f13: _F[T12, T13],
251
+ f14: _F[T13, T14],
252
+ f15: _F[T14, T15],
253
+ /,
254
+ ) -> T15: ...
255
+ @overload
256
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16](
257
+ self,
258
+ f1: _F[Effect[A_co, E_co, R_co], T1],
259
+ f2: _F[T1, T2],
260
+ f3: _F[T2, T3],
261
+ f4: _F[T3, T4],
262
+ f5: _F[T4, T5],
263
+ f6: _F[T5, T6],
264
+ f7: _F[T6, T7],
265
+ f8: _F[T7, T8],
266
+ f9: _F[T8, T9],
267
+ f10: _F[T9, T10],
268
+ f11: _F[T10, T11],
269
+ f12: _F[T11, T12],
270
+ f13: _F[T12, T13],
271
+ f14: _F[T13, T14],
272
+ f15: _F[T14, T15],
273
+ f16: _F[T15, T16],
274
+ /,
275
+ ) -> T16: ...
276
+ @overload
277
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17](
278
+ self,
279
+ f1: _F[Effect[A_co, E_co, R_co], T1],
280
+ f2: _F[T1, T2],
281
+ f3: _F[T2, T3],
282
+ f4: _F[T3, T4],
283
+ f5: _F[T4, T5],
284
+ f6: _F[T5, T6],
285
+ f7: _F[T6, T7],
286
+ f8: _F[T7, T8],
287
+ f9: _F[T8, T9],
288
+ f10: _F[T9, T10],
289
+ f11: _F[T10, T11],
290
+ f12: _F[T11, T12],
291
+ f13: _F[T12, T13],
292
+ f14: _F[T13, T14],
293
+ f15: _F[T14, T15],
294
+ f16: _F[T15, T16],
295
+ f17: _F[T16, T17],
296
+ /,
297
+ ) -> T17: ...
298
+ @overload
299
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18](
300
+ self,
301
+ f1: _F[Effect[A_co, E_co, R_co], T1],
302
+ f2: _F[T1, T2],
303
+ f3: _F[T2, T3],
304
+ f4: _F[T3, T4],
305
+ f5: _F[T4, T5],
306
+ f6: _F[T5, T6],
307
+ f7: _F[T6, T7],
308
+ f8: _F[T7, T8],
309
+ f9: _F[T8, T9],
310
+ f10: _F[T9, T10],
311
+ f11: _F[T10, T11],
312
+ f12: _F[T11, T12],
313
+ f13: _F[T12, T13],
314
+ f14: _F[T13, T14],
315
+ f15: _F[T14, T15],
316
+ f16: _F[T15, T16],
317
+ f17: _F[T16, T17],
318
+ f18: _F[T17, T18],
319
+ /,
320
+ ) -> T18: ...
321
+ @overload
322
+ def pipe[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19](
323
+ self,
324
+ f1: _F[Effect[A_co, E_co, R_co], T1],
325
+ f2: _F[T1, T2],
326
+ f3: _F[T2, T3],
327
+ f4: _F[T3, T4],
328
+ f5: _F[T4, T5],
329
+ f6: _F[T5, T6],
330
+ f7: _F[T6, T7],
331
+ f8: _F[T7, T8],
332
+ f9: _F[T8, T9],
333
+ f10: _F[T9, T10],
334
+ f11: _F[T10, T11],
335
+ f12: _F[T11, T12],
336
+ f13: _F[T12, T13],
337
+ f14: _F[T13, T14],
338
+ f15: _F[T14, T15],
339
+ f16: _F[T15, T16],
340
+ f17: _F[T16, T17],
341
+ f18: _F[T17, T18],
342
+ f19: _F[T18, T19],
343
+ /,
344
+ ) -> T19: ...
345
+ @overload
346
+ def pipe[
347
+ T1,
348
+ T2,
349
+ T3,
350
+ T4,
351
+ T5,
352
+ T6,
353
+ T7,
354
+ T8,
355
+ T9,
356
+ T10,
357
+ T11,
358
+ T12,
359
+ T13,
360
+ T14,
361
+ T15,
362
+ T16,
363
+ T17,
364
+ T18,
365
+ T19,
366
+ T20,
367
+ ](
368
+ self,
369
+ f1: _F[Effect[A_co, E_co, R_co], T1],
370
+ f2: _F[T1, T2],
371
+ f3: _F[T2, T3],
372
+ f4: _F[T3, T4],
373
+ f5: _F[T4, T5],
374
+ f6: _F[T5, T6],
375
+ f7: _F[T6, T7],
376
+ f8: _F[T7, T8],
377
+ f9: _F[T8, T9],
378
+ f10: _F[T9, T10],
379
+ f11: _F[T10, T11],
380
+ f12: _F[T11, T12],
381
+ f13: _F[T12, T13],
382
+ f14: _F[T13, T14],
383
+ f15: _F[T14, T15],
384
+ f16: _F[T15, T16],
385
+ f17: _F[T16, T17],
386
+ f18: _F[T17, T18],
387
+ f19: _F[T18, T19],
388
+ f20: _F[T19, T20],
389
+ /,
390
+ ) -> T20: ...
391
+ def pipe(self, /, *fs: _F[Any, Any]) -> Any:
392
+ """Apply each function to the previous result, eagerly (pipeArguments, Pipeable.ts:567)."""
393
+ out: Any = self
394
+ for f in fs:
395
+ out = f(out)
396
+ return out
397
+
398
+ def map[B](self, f: Callable[[A_co], B]) -> Effect[B, E_co, R_co]:
399
+ return OnSuccess(self, lambda a: Success(f(a)))
400
+
401
+ def flat_map[B, E2, R2](
402
+ self, f: Callable[[A_co], Effect[B, E2, R2]]
403
+ ) -> Effect[B, E_co | E2, R_co | R2]:
404
+ return OnSuccess(self, f)
405
+
406
+ def as_[B](self, value: B) -> Effect[B, E_co, R_co]:
407
+ return OnSuccess(self, lambda _: Success(value))
408
+
409
+ def tap[B, E2, R2](
410
+ self, f: Callable[[A_co], Effect[B, E2, R2]] | Effect[B, E2, R2]
411
+ ) -> Effect[A_co, E_co | E2, R_co | R2]:
412
+ """After success run ``f(a)``, or the effect ``f``, then succeed with ``a`` again; its
413
+ failure fails the whole (internal/effect.ts:1607-1613, :1654-1675)."""
414
+ return _tap(self, f)
415
+
416
+ def catch_all[B, E2 = Never, R2 = Never](
417
+ self, handler: Callable[[E_co], Effect[B, E2, R2]]
418
+ ) -> Effect[A_co | B, E2, R_co | R2]:
419
+ return _catch_all(self, handler)
420
+
421
+ def catch_cause[B, E2 = Never, R2 = Never](
422
+ self, handler: Callable[[Cause[E_co]], Effect[B, E2, R2]]
423
+ ) -> Effect[A_co | B, E2, R_co | R2]:
424
+ return OnFailure(self, handler)
425
+
426
+ def on_exit[E2 = Never, R2 = Never](
427
+ self, f: Callable[[Exit[A_co, E_co]], Effect[Any, E2, R2]]
428
+ ) -> Effect[A_co, E_co | E2, R_co | R2]:
429
+ return OnExit.of(self, f)
430
+
431
+ def ensuring[R2 = Never](
432
+ self, finalizer: Effect[Any, Never, R2]
433
+ ) -> Effect[A_co, E_co, R_co | R2]:
434
+ return OnExit.of(self, lambda _exit: finalizer)
435
+
436
+
437
+ # ================================================================================================
438
+ # Exit = Success | Failure. An Exit is an effect that is already done.
439
+ # ================================================================================================
440
+
441
+
442
+ @final
443
+ class Success(Effect[A_co, Never, Never]):
444
+ __slots__ = ("value",)
445
+ __match_args__ = ("value",)
446
+
447
+ def __init__(self, value: A_co) -> None:
448
+ self.value = value
449
+
450
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
451
+ k = fiber._pop(ok=True) # pyright: ignore[reportPrivateUsage]
452
+ return k.on_ok(self.value, fiber) if k is not None else fiber._done(self) # pyright: ignore[reportPrivateUsage]
453
+
454
+ def __repr__(self) -> str:
455
+ return f"Success({self.value!r})"
456
+
457
+
458
+ @final
459
+ class Failure(Effect[Never, E_co, Never]):
460
+ __slots__ = ("cause",)
461
+ __match_args__ = ("cause",)
462
+
463
+ def __init__(self, cause: Cause[E_co]) -> None:
464
+ self.cause = cause
465
+
466
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
467
+ cause: Cause[Any] = self.cause
468
+ k = fiber._pop(ok=False) # pyright: ignore[reportPrivateUsage]
469
+ if fiber.interrupted is not None and fiber.interruptible:
470
+ # Interrupted: skip every handler until something masks the fiber (a finalizer frame
471
+ # does, as it's popped). Recovering from an interrupt must not be possible.
472
+ # Effect v4: internal/core.ts:601-629
473
+ skipped = False
474
+ while k is not None and fiber.interruptible:
475
+ skipped = skipped or not k.restoring
476
+ k = fiber._pop(ok=False) # pyright: ignore[reportPrivateUsage]
477
+ if skipped:
478
+ cause = cause.without_fails()
479
+ cause = cause + fiber.take_interrupt()
480
+ return k.on_err(cause, fiber) if k is not None else fiber._done(Failure(cause)) # pyright: ignore[reportPrivateUsage]
481
+
482
+ def __repr__(self) -> str:
483
+ return f"Failure({self.cause!r})"
484
+
485
+
486
+ type Exit[A, E] = Success[A] | Failure[E]
487
+
488
+ UNIT: Success[None] = Success(None)
489
+
490
+
491
+ # ================================================================================================
492
+ # Other nodes
493
+ # ================================================================================================
494
+
495
+
496
+ @final
497
+ class Sync(Effect[A_co, Never, Never]):
498
+ __slots__ = ("thunk",)
499
+
500
+ def __init__(self, thunk: Callable[[], A_co]) -> None:
501
+ self.thunk = thunk
502
+
503
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
504
+ return Success(self.thunk()) # a raise is caught by the run loop -> Die
505
+
506
+
507
+ @final
508
+ class Suspend(Effect[A_co, E_co, R_co]):
509
+ __slots__ = ("thunk",)
510
+
511
+ def __init__(self, thunk: Callable[[], Effect[A_co, E_co, R_co]]) -> None:
512
+ self.thunk = thunk
513
+
514
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
515
+ return self.thunk()
516
+
517
+
518
+ @final
519
+ class SuspendExit(Effect[A_co, E_co, R_co]):
520
+ """Queue.ts:2042-2049: deliver a terminal result in the thunk's own step."""
521
+
522
+ __slots__ = ("thunk",)
523
+
524
+ def __init__(self, thunk: Callable[[], Effect[A_co, E_co, R_co]]) -> None:
525
+ self.thunk = thunk
526
+
527
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
528
+ effect = self.thunk()
529
+ if type(effect) in (Success, Failure):
530
+ return effect._eval(fiber)
531
+ return effect
532
+
533
+
534
+ @final
535
+ class WithFiber(Effect[A_co, E_co, R_co]):
536
+ __slots__ = ("f",)
537
+
538
+ def __init__(self, f: Callable[[AnyFiber], Effect[A_co, E_co, R_co]]) -> None:
539
+ self.f = f
540
+
541
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
542
+ return self.f(fiber)
543
+
544
+
545
+ fiber_id: Effect[int, Never, Never] = WithFiber(lambda fiber: succeed(fiber.id))
546
+ """The executing fiber's id, read on every run (Effect v4 internal/effect.ts:1196-1204)."""
547
+
548
+
549
+ @final
550
+ class YieldNow(Effect[None, Never, Never]):
551
+ __slots__ = ()
552
+
553
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
554
+ fiber.yield_now(UNIT)
555
+ return None
556
+
557
+
558
+ type Resume[A, E, R] = Callable[[Effect[A, E, R]], None]
559
+ type Register[A, E, R] = Callable[[Resume[A, E, R]], Effect[Any, Any, Any] | None]
560
+
561
+
562
+ class Park:
563
+ """One parked Async or queued step. ``done`` flips once: by resume or the queued step, or by
564
+ an interrupt that got there first."""
565
+
566
+ __slots__ = ("done", "registering", "sync")
567
+
568
+ def __init__(self) -> None:
569
+ self.done = False
570
+ self.registering = True
571
+ self.sync: AnyEffect | None = None
572
+
573
+
574
+ @final
575
+ class Async(Effect[A_co, E_co, R_co]):
576
+ """Suspend the fiber. ``register(resume)`` starts the work and may return a cancel effect.
577
+
578
+ resume(effect) continues the fiber with that effect. Only the first call counts.
579
+ Effect v4: internal/effect.ts:1206-1273
580
+ """
581
+
582
+ __slots__ = ("register",)
583
+
584
+ def __init__(self, register: Register[A_co, E_co, R_co]) -> None:
585
+ self.register = register
586
+
587
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
588
+ park = Park()
589
+
590
+ def resume(eff: Effect[A_co, E_co, R_co]) -> None:
591
+ if park.done:
592
+ return
593
+ park.done = True
594
+ if park.registering:
595
+ park.sync = eff # resumed before register returned: no need to park
596
+ else:
597
+ fiber.evaluate(eff) # runs the fiber now, before resume returns
598
+
599
+ cancel = self.register(resume)
600
+ park.registering = False
601
+ if park.sync is not None:
602
+ return park.sync
603
+ fiber._park(park) # pyright: ignore[reportPrivateUsage]
604
+ if cancel is not None:
605
+ fiber.stack.append(_AsyncCancel(cancel))
606
+ return None
607
+
608
+
609
+ # ================================================================================================
610
+ # Frames
611
+ # ================================================================================================
612
+
613
+ OK, ERR, ANY = 1, 2, 4
614
+
615
+
616
+ class Frame:
617
+ __slots__ = ()
618
+ kind: ClassVar[int] = 0
619
+ restoring: ClassVar[bool] = False # True = bookkeeping, not a user handler
620
+
621
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
622
+ raise NotImplementedError
623
+
624
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
625
+ raise NotImplementedError
626
+
627
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
628
+ return None
629
+
630
+
631
+ @final
632
+ class Then(Frame):
633
+ """Whatever arrives, continue with ``eff``. Produced when an on_any hook takes over."""
634
+
635
+ __slots__ = ("eff",)
636
+ kind = OK | ERR
637
+ restoring = True
638
+
639
+ def __init__(self, eff: AnyEffect) -> None:
640
+ self.eff = eff
641
+
642
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
643
+ return self.eff
644
+
645
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
646
+ return self.eff
647
+
648
+
649
+ @final
650
+ class OnSuccess(Effect[A_co, E_co, R_co], Frame):
651
+ __slots__ = ("eff", "f")
652
+ kind = OK
653
+
654
+ def __init__(self, eff: AnyEffect, f: Callable[[Any], AnyEffect]) -> None:
655
+ self.eff = eff
656
+ self.f = f
657
+
658
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
659
+ fiber.stack.append(self)
660
+ return self.eff
661
+
662
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
663
+ return self.f(value)
664
+
665
+
666
+ @final
667
+ class OnFailure(Effect[A_co, E_co, R_co], Frame):
668
+ __slots__ = ("eff", "f")
669
+ kind = ERR
670
+
671
+ def __init__(self, eff: AnyEffect, f: Callable[[Cause[Any]], AnyEffect]) -> None:
672
+ self.eff = eff
673
+ self.f = f
674
+
675
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
676
+ fiber.stack.append(self)
677
+ return self.eff
678
+
679
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
680
+ return self.f(cause)
681
+
682
+
683
+ @final
684
+ class ExitFrame(Effect[Any, Never, R_co], Frame):
685
+ """``exit_``'s frame: either outcome of ``eff`` becomes the success value, as an Exit. Not a
686
+ restoring frame, so an interrupt delivered while interruptible skips it like any other
687
+ handler (``Failure._eval``). Effect v4: exitPrimitive, internal/effect.ts:3876-3889."""
688
+
689
+ __slots__ = ("eff",)
690
+ kind = OK | ERR
691
+
692
+ def __init__(self, eff: AnyEffect) -> None:
693
+ self.eff = eff
694
+
695
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
696
+ fiber.stack.append(self)
697
+ return self.eff
698
+
699
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
700
+ return Success(Success(value))
701
+
702
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
703
+ return Success(Failure(cause))
704
+
705
+
706
+ def _mask_while_popping(fiber: AnyFiber) -> None:
707
+ """Make the fiber uninterruptible for the handler about to run; restore it afterwards."""
708
+ if fiber.interruptible:
709
+ fiber.interruptible = False
710
+ fiber.stack.append(RESTORE_INTERRUPTIBLE)
711
+
712
+
713
+ @final
714
+ class OnExit(Effect[A_co, E_co, R_co], Frame):
715
+ """Run ``f(exit, fiber)`` after ``eff`` however it ends, uninterruptibly, then re-emit the exit.
716
+
717
+ on_any masks the fiber as the frame is popped. That is what stops Failure's skip-loop from
718
+ skipping this frame when the fiber is being interrupted. ``f`` returns the finalizer effect,
719
+ or None when its work is already done (upstream's ``| undefined``). It gets the fiber for
720
+ on_exit_with_dispatcher; everything else builds through OnExit.of.
721
+ Effect v4: internal/effect.ts:4270-4319
722
+ """
723
+
724
+ __slots__ = ("eff", "f")
725
+ kind = OK | ERR | ANY
726
+
727
+ def __init__(
728
+ self, eff: AnyEffect, f: Callable[[Exit[Any, Any], AnyFiber], AnyEffect | None]
729
+ ) -> None:
730
+ self.eff = eff
731
+ self.f = f
732
+
733
+ @staticmethod
734
+ def of(eff: AnyEffect, f: Callable[[Exit[Any, Any]], AnyEffect]) -> OnExit[Any, Any, Any]:
735
+ return OnExit(eff, lambda exit_, _fiber: f(exit_))
736
+
737
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
738
+ fiber.stack.append(self)
739
+ return self.eff
740
+
741
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
742
+ _mask_while_popping(fiber)
743
+ return None
744
+
745
+ def _finalizer(self, exit_: Exit[Any, Any], fiber: AnyFiber) -> AnyEffect | None:
746
+ try:
747
+ return self.f(exit_, fiber)
748
+ except Exception as e: # f raised instead of returning: a defect of the finalizer
749
+ return Failure(Cause.die(e))
750
+
751
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
752
+ exit_ = Success(value)
753
+ fin = self._finalizer(exit_, fiber)
754
+ return exit_ if fin is None else OnSuccess(fin, lambda _: exit_)
755
+
756
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
757
+ exit_: Failure[Any] = Failure(cause)
758
+ fin = self._finalizer(exit_, fiber)
759
+ if fin is None:
760
+ return exit_
761
+ # a failing finalizer adds its cause to the original, then defects are elected
762
+ # (combineFinalizerCause, internal/effect.ts:4069-4075)
763
+ combined: AnyEffect = OnFailure(fin, lambda c2: Failure((cause + c2).elect_defects()))
764
+ return OnSuccess(combined, lambda _: exit_)
765
+
766
+
767
+ def on_exit_with_dispatcher[A, E, R](
768
+ eff: Effect[A, E, R], f: Callable[[Exit[A, E], SchedulerDispatcher], None]
769
+ ) -> Effect[A, E, R]:
770
+ """Run the synchronous ``f(exit, dispatcher)`` as the frame pops, masked, with the running
771
+ fiber's dispatcher: upstream onExitPrimitive with a callback that returns undefined and reads
772
+ getCurrentFiber() (internal/effect.ts:4270-4319; Semaphore.ts:365-368). Work ``f`` queues on
773
+ the dispatcher is published in the same step as its state changes. A raising ``f`` is a
774
+ defect, combined like any failing finalizer (OnExit)."""
775
+
776
+ def run(exit_: Exit[Any, Any], fiber: AnyFiber) -> None:
777
+ f(exit_, fiber.current_dispatcher)
778
+
779
+ return OnExit(eff, run)
780
+
781
+
782
+ @final
783
+ class SetInterruptible(Frame):
784
+ """Restore interruptibility when popped; deliver an interrupt that waited for it."""
785
+
786
+ __slots__ = ("value",)
787
+ kind = ANY
788
+ restoring = True
789
+
790
+ def __init__(self, value: bool) -> None:
791
+ self.value = value
792
+
793
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
794
+ fiber.interruptible = self.value
795
+ if self.value and fiber.interrupted is not None:
796
+ return Failure(fiber.take_interrupt())
797
+ return None
798
+
799
+
800
+ RESTORE_INTERRUPTIBLE = SetInterruptible(True)
801
+ RESTORE_UNINTERRUPTIBLE = SetInterruptible(False)
802
+
803
+
804
+ @final
805
+ class RestoreContext(Frame):
806
+ """Put back the context from before update_context, however the effect ends (on_any runs
807
+ on success, failure, and when an interrupt skips the frame)."""
808
+
809
+ __slots__ = ("context",)
810
+ kind = ANY
811
+ restoring = True
812
+
813
+ def __init__(self, context: ContextMap) -> None:
814
+ self.context = context
815
+
816
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
817
+ fiber.swap_context(self.context)
818
+ return None
819
+
820
+
821
+ @final
822
+ class _AsyncCancel(Frame):
823
+ """Sits under a parked Async. If the fiber is interrupted while parked, run the cancel effect
824
+ (masked) before the interrupt continues upward. Passes successes straight through."""
825
+
826
+ __slots__ = ("cancel",)
827
+ kind = ERR | ANY
828
+ restoring = True
829
+
830
+ def __init__(self, cancel: AnyEffect) -> None:
831
+ self.cancel = cancel
832
+
833
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
834
+ _mask_while_popping(fiber)
835
+ return None
836
+
837
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
838
+ if not cause.is_interrupted:
839
+ return Failure(cause)
840
+ # asyncFinalizer uses combineFinalizerCause: original interrupt first,
841
+ # then cancellation failures, electing typed failures when a defect exists.
842
+ finalizer: AnyEffect = OnFailure(
843
+ self.cancel, lambda cleanup: Failure((cause + cleanup).elect_defects())
844
+ )
845
+ return OnSuccess(finalizer, lambda _: Failure(cause))
846
+
847
+
848
+ @final
849
+ class GenFrame(Effect[Any, Any, Any], Frame):
850
+ """Drives a generator: send each success in, run whatever it yields next.
851
+
852
+ A failure never re-enters the generator (no .throw(), like Effect v4 internal/effect.ts:1487).
853
+ Python adaptation: upstream never closes the iterator, so a JS ``finally`` doesn't run on
854
+ failure. We .close() it so ``finally`` blocks run now rather than at garbage collection. If
855
+ that cleanup raises (or yields: Python then raises RuntimeError), the original cause is kept
856
+ and the error is added as a defect, the rule for a failing finalizer (combineFinalizerCause,
857
+ :4069-4075); see _CloseFailed and tests/test_gen_cleanup.py.
858
+ """
859
+
860
+ __slots__ = ("gen",)
861
+ kind = OK | ANY
862
+
863
+ def __init__(self, gen: Generator[AnyEffect, Any, Any]) -> None:
864
+ self.gen = gen
865
+
866
+ def _eval(self, fiber: AnyFiber) -> AnyEffect | None:
867
+ return self.on_ok(None, fiber)
868
+
869
+ def on_ok(self, value: Any, fiber: AnyFiber) -> AnyEffect | None:
870
+ while True:
871
+ try:
872
+ nxt = self.gen.send(value)
873
+ except StopIteration as stop:
874
+ return Success(stop.value)
875
+ if isinstance(nxt, Success): # already done: skip the push/pop round trip
876
+ value = nxt.value
877
+ continue
878
+ if not isinstance(nxt, Effect): # pyright: ignore[reportUnnecessaryIsInstance]
879
+ self.gen.close()
880
+ raise TypeError(f"@gen body yielded {nxt!r}; use `yield from` on an Effect")
881
+ fiber.stack.append(self)
882
+ return nxt
883
+
884
+ def on_any(self, fiber: AnyFiber, ok: bool) -> AnyEffect | None:
885
+ if not ok:
886
+ try:
887
+ self.gen.close()
888
+ except Exception as e: # the body's cleanup failed: handled next, masked like OnExit
889
+ _mask_while_popping(fiber)
890
+ fiber.stack.append(_CloseFailed(e))
891
+ return None
892
+
893
+
894
+ @final
895
+ class _CloseFailed(Frame):
896
+ """Pushed by GenFrame.on_any while a failure pops it, and popped straight after by the same
897
+ _pop: the failure that closed the generator, plus the cleanup's defect, defects elected.
898
+ GenFrame's mask stops Failure's interrupt skip-loop here, so an Interrupt is kept too."""
899
+
900
+ __slots__ = ("defect",)
901
+ kind = ERR
902
+
903
+ def __init__(self, defect: Exception) -> None:
904
+ self.defect = defect
905
+
906
+ def on_err(self, cause: Cause[Any], fiber: AnyFiber) -> AnyEffect | None:
907
+ return Failure((cause + Cause.die(self.defect)).elect_defects())
908
+
909
+
910
+ # ================================================================================================
911
+ # Constructors
912
+ # ================================================================================================
913
+
914
+
915
+ def succeed[A](value: A) -> Effect[A, Never, Never]:
916
+ return Success(value)
917
+
918
+
919
+ def fail[E](error: E) -> Effect[Never, E, Never]:
920
+ return Failure(Cause.fail(error))
921
+
922
+
923
+ def fail_cause[E](cause: Cause[E]) -> Effect[Never, E, Never]:
924
+ return Failure(cause)
925
+
926
+
927
+ def die(defect: BaseException) -> Effect[Never, Never, Never]:
928
+ return Failure(Cause.die(defect))
929
+
930
+
931
+ def sync[A](thunk: Callable[[], A]) -> Effect[A, Never, Never]:
932
+ """A side effect. Exceptions it raises are defects (Die), not typed errors."""
933
+ return Sync(thunk)
934
+
935
+
936
+ def suspend[A, E, R](thunk: Callable[[], Effect[A, E, R]]) -> Effect[A, E, R]:
937
+ return Suspend(thunk)
938
+
939
+
940
+ def suspend_exit[A, E, R](thunk: Callable[[], Effect[A, E, R]]) -> Effect[A, E, R]:
941
+ """Suspend lazily, delivering a returned Exit without another operation boundary.
942
+
943
+ A destructive read can remove a value and return Success(value) without an
944
+ intervening budget yield or pending-interrupt check losing that value before
945
+ its first consumer. Nonterminal effects are delegated normally. This does not
946
+ mask waiting or roll back work after a continuation receives the result.
947
+ """
948
+ return SuspendExit(thunk)
949
+
950
+
951
+ def async_[A, E = Never, R = Never](register: Register[A, E, R]) -> Effect[A, E, R]:
952
+ return Async(register)
953
+
954
+
955
+ def exit_[A, E, R](eff: Effect[A, E, R]) -> Effect[Exit[A, E], Never, R]:
956
+ """Run ``eff`` and succeed with how it ended. An Exit passed in is the value as it is.
957
+ Effect v4: exit, internal/effect.ts:3873-3874."""
958
+ if isinstance(eff, (Success, Failure)):
959
+ return Success(eff)
960
+ return ExitFrame(eff)
961
+
962
+
963
+ yield_now: Effect[None, Never, Never] = YieldNow()
964
+ never: Effect[Never, Never, Never] = Async(lambda _resume: None)
965
+
966
+
967
+ def attempt[A, X: BaseException](
968
+ thunk: Callable[[], A] | Callable[[], Awaitable[A]],
969
+ catch: type[X] | tuple[type[X], ...] = (),
970
+ ) -> Effect[A, X, Never]:
971
+ """Call sync or async code. Exceptions of type ``catch`` become typed failures; others, defects.
972
+
973
+ An awaitable result runs as an asyncio task; interrupting the fiber cancels the task and waits
974
+ for it to finish.
975
+ """
976
+
977
+ def start() -> AnyEffect:
978
+ try:
979
+ out = thunk()
980
+ except catch as e:
981
+ return Failure(Cause.fail(e))
982
+ if inspect.isawaitable(out):
983
+ return _await(cast(Awaitable[A], out), catch)
984
+ return Success(out)
985
+
986
+ return Suspend(start)
987
+
988
+
989
+ def from_async[A](thunk: Callable[[], Awaitable[A]]) -> Effect[A, Never, Never]:
990
+ return attempt(thunk) # no exception is expected: all of them are defects
991
+
992
+
993
+ def _await(
994
+ aw: Awaitable[Any], catch: type[BaseException] | tuple[type[BaseException], ...]
995
+ ) -> AnyEffect:
996
+ def register(resume: Resume[Any, Any, Any]) -> AnyEffect:
997
+ task = asyncio.ensure_future(aw)
998
+
999
+ def done(t: asyncio.Future[Any]) -> None:
1000
+ if t.cancelled():
1001
+ resume(Failure(Cause.interrupt()))
1002
+ elif (e := t.exception()) is not None:
1003
+ resume(Failure(Cause.fail(e) if isinstance(e, catch) else Cause.die(e)))
1004
+ else:
1005
+ resume(Success(t.result()))
1006
+
1007
+ task.add_done_callback(done)
1008
+
1009
+ def cancel_and_wait(resume_cancel: Resume[None, Never, Never]) -> None:
1010
+ task.cancel()
1011
+ task.add_done_callback(lambda _: resume_cancel(UNIT))
1012
+
1013
+ return Async(cancel_and_wait)
1014
+
1015
+ return Async(register)
1016
+
1017
+
1018
+ # ================================================================================================
1019
+ # Interruptibility
1020
+ # ================================================================================================
1021
+
1022
+
1023
+ def uninterruptible[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
1024
+ def go(fiber: AnyFiber) -> AnyEffect:
1025
+ if fiber.interruptible:
1026
+ fiber.interruptible = False
1027
+ fiber.stack.append(RESTORE_INTERRUPTIBLE)
1028
+ return eff
1029
+
1030
+ return WithFiber(go)
1031
+
1032
+
1033
+ def interruptible[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
1034
+ def go(fiber: AnyFiber) -> AnyEffect:
1035
+ if fiber.interruptible:
1036
+ return eff
1037
+ fiber.interruptible = True
1038
+ fiber.stack.append(RESTORE_UNINTERRUPTIBLE)
1039
+ if fiber.interrupted is not None:
1040
+ return Failure(fiber.take_interrupt())
1041
+ return eff
1042
+
1043
+ return WithFiber(go)
1044
+
1045
+
1046
+ @final
1047
+ class Restore:
1048
+ """Passed to uninterruptible_mask's body: puts back the interruptibility from outside."""
1049
+
1050
+ __slots__ = ("was",)
1051
+
1052
+ def __init__(self, was: bool) -> None:
1053
+ self.was = was
1054
+
1055
+ def __call__[A, E, R](self, eff: Effect[A, E, R]) -> Effect[A, E, R]:
1056
+ return interruptible(eff) if self.was else eff
1057
+
1058
+
1059
+ def uninterruptible_mask[A, E, R](body: Callable[[Restore], Effect[A, E, R]]) -> Effect[A, E, R]:
1060
+ """Run ``body`` uninterruptibly, except the parts it wraps in ``restore(...)``.
1061
+
1062
+ The acquire/use/release shape: acquire and release can't be interrupted halfway; use can.
1063
+ """
1064
+
1065
+ def go(fiber: AnyFiber) -> AnyEffect:
1066
+ was = fiber.interruptible
1067
+ if was:
1068
+ fiber.interruptible = False
1069
+ fiber.stack.append(RESTORE_INTERRUPTIBLE)
1070
+ return body(Restore(was))
1071
+
1072
+ return WithFiber(go)
1073
+
1074
+
1075
+ # ================================================================================================
1076
+ # Context
1077
+ # ================================================================================================
1078
+
1079
+
1080
+ def update_context[A, E, R](
1081
+ eff: Effect[A, E, R], f: Callable[[ContextMap], ContextMap]
1082
+ ) -> Effect[A, E, R]:
1083
+ """Run ``eff`` with the context ``f(current)``; the current one comes back on every exit.
1084
+
1085
+ The new context is a read-only copy of what f returns, so changing that mapping later can't
1086
+ reach the fiber. Swap and restore frame happen in one step, like ``uninterruptible``: no
1087
+ interrupt can land between them. If f raises, nothing changed and the raise is a defect.
1088
+ R is unchanged; context.provide is what removes services from R.
1089
+ Effect v4: internal/effect.ts:2269-2293 (updateContext).
1090
+ """
1091
+
1092
+ def go(fiber: AnyFiber) -> AnyEffect:
1093
+ old = fiber.swap_context(MappingProxyType(dict(f(fiber.context))))
1094
+ fiber.stack.append(RestoreContext(old))
1095
+ return eff
1096
+
1097
+ return WithFiber(go)
1098
+
1099
+
1100
+ # ================================================================================================
1101
+ # Error handling and finalization
1102
+ #
1103
+ # Two spellings. Methods (`eff.catch_all(h)`) give the handler the precise error type. Pipeables
1104
+ # (`eff.pipe(catch_all(h))`) build the handler before they see `eff`, and Python can't infer a
1105
+ # lambda's parameter from a later call, so their handler parameter is Any. catch_tag pipes cleanly
1106
+ # because the class names the type.
1107
+ # ================================================================================================
1108
+
1109
+
1110
+ def _first_recoverable(cause: Cause[Any]) -> tuple[bool, Any]:
1111
+ """A typed failure is recoverable unless a defect is also present (v4 effect.ts:184-200)."""
1112
+ if cause.defects:
1113
+ return False, None
1114
+ for e in cause.failures:
1115
+ return True, e
1116
+ return False, None
1117
+
1118
+
1119
+ def _catch_all(eff: AnyEffect, handler: Callable[[Any], AnyEffect]) -> AnyEffect:
1120
+ def on_err(cause: Cause[Any]) -> AnyEffect:
1121
+ ok, err = _first_recoverable(cause)
1122
+ return handler(err) if ok else Failure(cause)
1123
+
1124
+ return OnFailure(eff, on_err)
1125
+
1126
+
1127
+ @final
1128
+ class catch_all[B, E2, R2]:
1129
+ """eff.pipe(catch_all(lambda e: ...)): recover from any typed failure. Defects pass through."""
1130
+
1131
+ __slots__ = ("handler",)
1132
+
1133
+ def __init__(self, handler: Callable[[Any], Effect[B, E2, R2]]) -> None:
1134
+ self.handler = handler
1135
+
1136
+ def __call__[A, R](self, eff: Effect[A, Any, R]) -> Effect[A | B, E2, R | R2]:
1137
+ return _catch_all(eff, self.handler)
1138
+
1139
+
1140
+ @final
1141
+ class catch_cause[B, E2, R2]:
1142
+ """See the whole Cause (failures, defects). Interrupts can't be caught."""
1143
+
1144
+ __slots__ = ("handler",)
1145
+
1146
+ def __init__(self, handler: Callable[[Cause[Any]], Effect[B, E2, R2]]) -> None:
1147
+ self.handler = handler
1148
+
1149
+ def __call__[A, R](self, eff: Effect[A, Any, R]) -> Effect[A | B, E2, R | R2]:
1150
+ return OnFailure(eff, self.handler)
1151
+
1152
+
1153
+ @final
1154
+ class catch_tag[X, B, E2, R2]:
1155
+ """eff.pipe(catch_tag(NotFound, lambda e: succeed(None))) removes NotFound from E."""
1156
+
1157
+ __slots__ = ("cls", "handler")
1158
+
1159
+ def __init__(self, cls: type[X], handler: Callable[[X], Effect[B, E2, R2]]) -> None:
1160
+ self.cls = cls
1161
+ self.handler = handler
1162
+
1163
+ # exact match first: matching `X | E` against plain `X` would leave E unsolved
1164
+ @overload
1165
+ def __call__[A, R](self, eff: Effect[A, X, R]) -> Effect[A | B, E2, R | R2]: ...
1166
+ @overload
1167
+ def __call__[A, E, R](self, eff: Effect[A, X | E, R]) -> Effect[A | B, E | E2, R | R2]: ...
1168
+ def __call__(self, eff: AnyEffect) -> AnyEffect:
1169
+ def on_err(cause: Cause[Any]) -> AnyEffect:
1170
+ if not cause.defects:
1171
+ for e in cause.failures:
1172
+ if isinstance(e, self.cls):
1173
+ return self.handler(e)
1174
+ return Failure(cause)
1175
+
1176
+ return OnFailure(eff, on_err)
1177
+
1178
+
1179
+ @final
1180
+ class on_exit[R2 = Never, E2 = Never]:
1181
+ """Run ``f(exit)`` after the effect however it ends (success, failure, interrupt), masked."""
1182
+
1183
+ __slots__ = ("f",)
1184
+
1185
+ def __init__(self, f: Callable[[Exit[Any, Any]], Effect[Any, E2, R2]]) -> None:
1186
+ self.f = f
1187
+
1188
+ def __call__[A, E, R](self, eff: Effect[A, E, R]) -> Effect[A, E | E2, R | R2]:
1189
+ return OnExit.of(eff, self.f)
1190
+
1191
+
1192
+ def ensuring[R2](finalizer: Effect[Any, Never, R2]) -> on_exit[R2]:
1193
+ return on_exit(lambda _exit: finalizer)
1194
+
1195
+
1196
+ def on_error[R2](f: Callable[[Cause[Any]], Effect[Any, Never, R2]]) -> on_exit[R2]:
1197
+ """Run ``f(cause)`` if the effect fails (interruption included), masked. Effect v4:
1198
+ onError, internal/effect.ts:4411-4425."""
1199
+
1200
+ def finalizer(exit_: Exit[Any, Any]) -> Effect[Any, Never, R2]:
1201
+ return f(exit_.cause) if isinstance(exit_, Failure) else succeed(None)
1202
+
1203
+ return on_exit(finalizer)
1204
+
1205
+
1206
+ def on_interrupt[R2](f: Callable[[frozenset[int]], Effect[Any, Never, R2]]) -> on_exit[R2]:
1207
+ """Run ``f(interruptors)`` if the effect's cause holds an interruption, masked. The set holds
1208
+ the interrupting fiber ids that are known. Effect v4: onInterrupt, internal/effect.ts:4485-4499
1209
+ (causeFilterInterruptors, :224)."""
1210
+
1211
+ def on_cause(cause: Cause[Any]) -> Effect[Any, Never, R2]:
1212
+ if not cause.is_interrupted:
1213
+ return succeed(None)
1214
+ ids = frozenset(
1215
+ r.by for r in cause.reasons if isinstance(r, Interrupt) and r.by is not None
1216
+ )
1217
+ return f(ids)
1218
+
1219
+ return on_error(on_cause)
1220
+
1221
+
1222
+ # ================================================================================================
1223
+ # Composition
1224
+ # ================================================================================================
1225
+
1226
+
1227
+ def _tap(eff: AnyEffect, f: Callable[[Any], AnyEffect] | AnyEffect) -> AnyEffect:
1228
+ def cont(a: Any) -> AnyEffect:
1229
+ tapped = f(a) if callable(f) else f
1230
+ return OnSuccess(tapped, lambda _: Success(a))
1231
+
1232
+ return OnSuccess(eff, cont)
1233
+
1234
+
1235
+ @final
1236
+ class tap[B, E2, R2]:
1237
+ """eff.pipe(tap(lambda a: ...)) or eff.pipe(tap(effect)): run after success, keep the value.
1238
+ Like catch_all, the function's parameter is Any; use the method for a typed parameter."""
1239
+
1240
+ __slots__ = ("f",)
1241
+
1242
+ def __init__(self, f: Callable[[Any], Effect[B, E2, R2]] | Effect[B, E2, R2]) -> None:
1243
+ self.f = f
1244
+
1245
+ def __call__[A, E, R](self, eff: Effect[A, E, R]) -> Effect[A, E | E2, R | R2]:
1246
+ return _tap(eff, self.f)
1247
+
1248
+
1249
+ # ================================================================================================
1250
+ # Generators: Effect.gen
1251
+ # ================================================================================================
1252
+
1253
+ type Do[A, E, R] = Generator[Effect[Any, E, R], Any, A]
1254
+ """Declared @gen body type (mypy needs it): ``def get(uid: int) -> Do[User, NotFound, Db]``"""
1255
+
1256
+
1257
+ def gen[**P, A, E = Never, R = Never](
1258
+ f: Callable[P, Generator[Effect[Any, E, R], Any, A]],
1259
+ ) -> Callable[P, Effect[A, E, R]]:
1260
+ """Write effects as generator functions; pyright infers Effect[A, E, R] from the yields.
1261
+
1262
+ @gen
1263
+ def greet(uid: str):
1264
+ users = yield from Users()
1265
+ user = yield from users.find(uid)
1266
+ return user.name
1267
+ """
1268
+
1269
+ @wraps(f)
1270
+ def build(*args: P.args, **kwargs: P.kwargs) -> Effect[A, E, R]:
1271
+ return Suspend(lambda: GenFrame(f(*args, **kwargs)))
1272
+
1273
+ return build