Skip to content

Result

funstruct.monad.result

Result — a monad for computations that can fail with an Exception.

Result[A] = Ok(value) | Err(exception). AsyncResult[A] = async computation producing Result[A].

Decorators

@Try : (args) -> Result[A] @TryAsync : (args) -> AsyncResult[A]

Examples:

>>> from funstruct.monad.result import Result, Ok, Err, Try
>>> Ok(10).map(lambda x: x + 1)
Ok(11)
>>> Err("bad").map(lambda x: x + 1)
Err('bad')
>>> Ok(10).bind(lambda x: Ok(x * 2))
Ok(20)

handle_error_with — recover from Err:

>>> Err("bad").handle_error_with(lambda e: Ok("default"))
Ok('default')

@Try decorator:

>>> @Try
... def safe_div(a, b):
...     return a / b
>>> safe_div(10, 2)
Ok(5.0)
>>> safe_div(10, 0)
Err(ZeroDivisionError(...))

Result

Bases: DataType, Generic[_A]

Result[A] = Ok(value) | Err(exception).

Source code in funstruct/monad/result/__init__.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
class Result(DataType, Generic[_A]):
    """Result[A] = Ok(value) | Err(exception)."""

    @classmethod
    def pure(cls, value: _A) -> Result[_A]:
        return Ok(value)

    @classmethod
    def raise_error(cls, error: Exception) -> Result:
        return Err(error)

    @classmethod
    def do(cls, gen_fn: Callable) -> Callable[..., Result]:
        """Do-notation. Short-circuits on Err. Returns a callable.

        # TODO: do-notation is ~2x slower than raw bind chains due to generator
        # protocol overhead. Consider optimizing the generator loop or providing
        # a bind-chain builder as an alternative for performance-sensitive code.
        """

        def _thunk(*args, **kwargs):
            gen = gen_fn(*args, **kwargs)
            try:
                monadic_val = next(gen)
                while True:
                    match monadic_val:
                        case Err():
                            return monadic_val
                        case Ok(value):
                            monadic_val = gen.send(value)
            except StopIteration as e:
                return Ok(e.value)

        return _thunk

    @property
    def is_ok(self) -> bool:
        return False

    @property
    def is_err(self) -> bool:
        return not self.is_ok

do(gen_fn) classmethod

Do-notation. Short-circuits on Err. Returns a callable.

TODO: do-notation is ~2x slower than raw bind chains due to generator
protocol overhead. Consider optimizing the generator loop or providing
a bind-chain builder as an alternative for performance-sensitive code.
Source code in funstruct/monad/result/__init__.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@classmethod
def do(cls, gen_fn: Callable) -> Callable[..., Result]:
    """Do-notation. Short-circuits on Err. Returns a callable.

    # TODO: do-notation is ~2x slower than raw bind chains due to generator
    # protocol overhead. Consider optimizing the generator loop or providing
    # a bind-chain builder as an alternative for performance-sensitive code.
    """

    def _thunk(*args, **kwargs):
        gen = gen_fn(*args, **kwargs)
        try:
            monadic_val = next(gen)
            while True:
                match monadic_val:
                    case Err():
                        return monadic_val
                    case Ok(value):
                        monadic_val = gen.send(value)
        except StopIteration as e:
            return Ok(e.value)

    return _thunk

Ok dataclass

Bases: Result[_A]

Success case of Result.

Source code in funstruct/monad/result/__init__.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
@dataclass(frozen=True, eq=False)
class Ok(Result[_A]):
    """Success case of Result."""

    value: _A

    @property
    def is_ok(self) -> bool:
        return True

    def bind(self, f: Callable[[_A], Result[_B]]) -> Result[_B]:
        return f(self.value)

    def fold(self, on_err: Callable[[Exception], _B], on_ok: Callable[[_A], _B]) -> _B:
        return on_ok(self.value)

    def left_map(self, f: Callable[[Exception], Exception]) -> Result[_A]:
        return self

    def handle_error_with(self, f: Callable[[Exception], Result[_A]]) -> Result[_A]:
        return self

    def bimap(self, on_err: Callable, on_ok: Callable) -> Result:
        return Ok(on_ok(self.value))

    def get_or_else(self, default: _A) -> _A:
        return self.value

    def swap(self) -> Result:
        return Err(self.value)

    def __eq__(self, other: object) -> bool:
        match other:
            case Ok(val):
                return self.value == val
            case _:
                return False

    def __repr__(self) -> str:
        return f"Ok({repr(self.value)})"

Err dataclass

Bases: CapturesCreationSiteMixin, Result[_A]

Error case of Result. Captures creation site automatically.

Source code in funstruct/monad/result/__init__.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
@dataclass(frozen=True, eq=False)
class Err(CapturesCreationSiteMixin, Result[_A]):
    """Error case of Result. Captures creation site automatically."""

    error: Exception

    @property
    def is_ok(self) -> bool:
        return False

    def bind(self, f: Callable[[_A], Result[_B]]) -> Result[_B]:
        return self

    def fold(self, on_err: Callable[[Exception], _B], on_ok: Callable[[_A], _B]) -> _B:
        return on_err(self.error)

    def left_map(self, f: Callable[[Exception], Exception]) -> Result[_A]:
        return Err(f(self.error))

    def handle_error_with(self, f: Callable[[Exception], Result[_A]]) -> Result[_A]:
        return f(self.error)

    def bimap(self, on_err: Callable, on_ok: Callable) -> Result:
        return Err(on_err(self.error))

    def get_or_else(self, default: _A) -> _A:
        return default

    def swap(self) -> Result:
        return Ok(self.error)

    def __eq__(self, other: object) -> bool:
        match other:
            case Err(err):
                return self.error == err
            case _:
                return False

    def __repr__(self) -> str:
        return f"Err({repr(self.error)})"

AsyncResult

Bases: DataType, Generic[_A]

Async computation that produces Result[A] — essentially Future[Result[A]].

Create with

AsyncResult.pure(42) # Ok(42) wrapped in async AsyncResult.raise_error(ValueError()) # Err wrapped in async AsyncResult.from_result(Ok(42)) # lift sync Result @TryAsync decorator # catch exceptions

Compose (lazy — nothing executes until awaited): result.map(f) # transform success value result.bind(f) # chain async operations result.left_map(f) # transform error value result.handle_error_with(f) # recover from error

Execute (one await at the boundary): value = await result # Result[A]

Do-notation — all of these are equivalent::

# 1. Decorator style (recommended)
@AsyncResult.do
def pipeline():
    x = yield AsyncResult.pure(10)
    return x + 1

await pipeline()

# 2. Manual do — no args
await AsyncResult.do(gen_fn)()
#     do(gen_fn) → thunk
#     thunk()    → AsyncResult
#     await      → Result

# 3. Manual do — with args
await AsyncResult.do(gen_fn_with_args)("yo")
#     do(gen_fn) → thunk
#     thunk(arg) → AsyncResult  ← NOT thunk(arg)() !
#     await      → Result

# 4. WRONG — extra () causes TypeError
# await AsyncResult.do(gen_fn)("yo")()  # TypeError: AsyncResult not callable

Important: @do uses generators (yield), NOT async/await. You cannot decorate an async def with @do.

Source code in funstruct/monad/result/__init__.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
class AsyncResult(DataType, Generic[_A]):
    """Async computation that produces Result[A] — essentially Future[Result[A]].

    Create with:
        AsyncResult.pure(42)                     # Ok(42) wrapped in async
        AsyncResult.raise_error(ValueError())    # Err wrapped in async
        AsyncResult.from_result(Ok(42))          # lift sync Result
        @TryAsync decorator                      # catch exceptions

    Compose (lazy — nothing executes until awaited):
        result.map(f)                            # transform success value
        result.bind(f)                           # chain async operations
        result.left_map(f)                       # transform error value
        result.handle_error_with(f)              # recover from error

    Execute (one await at the boundary):
        value = await result                     # Result[A]

    Do-notation — all of these are equivalent::

        # 1. Decorator style (recommended)
        @AsyncResult.do
        def pipeline():
            x = yield AsyncResult.pure(10)
            return x + 1

        await pipeline()

        # 2. Manual do — no args
        await AsyncResult.do(gen_fn)()
        #     do(gen_fn) → thunk
        #     thunk()    → AsyncResult
        #     await      → Result

        # 3. Manual do — with args
        await AsyncResult.do(gen_fn_with_args)("yo")
        #     do(gen_fn) → thunk
        #     thunk(arg) → AsyncResult  ← NOT thunk(arg)() !
        #     await      → Result

        # 4. WRONG — extra () causes TypeError
        # await AsyncResult.do(gen_fn)("yo")()  # TypeError: AsyncResult not callable

    Important: @do uses generators (yield), NOT async/await.
    You cannot decorate an async def with @do.
    """

    def __init__(self, coro: Awaitable[Result[_A]]) -> None:
        self._coro = ReAwaitable(coro) if not isinstance(coro, ReAwaitable) else coro

    def __await__(self):
        return self._awaitable().__await__()

    async def _awaitable(self) -> Result[_A]:
        return await self._coro

    @staticmethod
    async def _resolve(value: Any) -> Result:
        if inspect.isawaitable(value):
            value = await value
        if isinstance(value, (Either, Result)):
            return value
        return Ok(value)

    def bind(self, f: Callable[[_A], Any]) -> AsyncResult:
        async def _inner():
            result = await self._coro
            match result:
                case Ok(value):
                    return await AsyncResult._resolve(f(value))
                case _:
                    return result

        return AsyncResult(_inner())

    def left_map(self, f: Callable[[Exception], Exception]) -> AsyncResult[_A]:
        async def _inner():
            result = await self._coro
            match result:
                case Err(error):
                    return Err(f(error))
                case _:
                    return result

        return AsyncResult(_inner())

    def bimap(
        self, on_err: Callable[[Exception], Exception], on_ok: Callable
    ) -> AsyncResult:
        async def _inner():
            result = await self._coro
            match result:
                case Ok(value):
                    return Ok(on_ok(value))
                case Err(error):
                    return Err(on_err(error))
                case _:
                    return result

        return AsyncResult(_inner())

    def handle_error_with(self, f: Callable[[Exception], Any]) -> AsyncResult:
        async def _inner():
            result = await self._coro
            match result:
                case Err(error):
                    return await AsyncResult._resolve(f(error))
                case _:
                    return result

        return AsyncResult(_inner())

    @classmethod
    def pure(cls, value: _A) -> AsyncResult[_A]:
        async def _inner():
            return Ok(value)

        return cls(_inner())

    @classmethod
    def raise_error(cls, error: Exception) -> AsyncResult:
        async def _inner():
            return Err(error)

        return cls(_inner())

    @classmethod
    def from_result(cls, result: Result) -> AsyncResult:
        async def _inner():
            return result

        return cls(_inner())

    @classmethod
    def from_either(cls, either: Either) -> AsyncResult:
        async def _inner():
            return either

        return cls(_inner())

    def fold(
        self, on_err: Callable[[Exception], _B], on_ok: Callable[[_A], _B]
    ) -> Future[_B]:
        async def _inner():
            result = await self._coro
            return result.fold(on_err=on_err, on_ok=on_ok)

        return Future(_inner())

    @classmethod
    def do(cls, gen_fn: Callable) -> Callable[..., AsyncResult]:
        """Do-notation for AsyncResult.

        # TODO: do-notation is ~2x slower than raw bind chains due to generator
        # protocol overhead. Consider optimizing the generator loop or providing
        # a bind-chain builder as an alternative for performance-sensitive code.
        """

        def _thunk(*args, **kwargs):
            async def _run():
                gen = gen_fn(*args, **kwargs)
                try:
                    monadic_val = next(gen)
                    while True:
                        result = await monadic_val
                        match result:
                            case Ok(value):
                                monadic_val = gen.send(value)
                            case _:
                                return result
                except StopIteration as e:
                    return Ok(e.value)

            return cls(_run())

        return _thunk

    def __repr__(self) -> str:
        return f"AsyncResult({self._coro})"

do(gen_fn) classmethod

Do-notation for AsyncResult.

TODO: do-notation is ~2x slower than raw bind chains due to generator
protocol overhead. Consider optimizing the generator loop or providing
a bind-chain builder as an alternative for performance-sensitive code.
Source code in funstruct/monad/result/__init__.py 
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
@classmethod
def do(cls, gen_fn: Callable) -> Callable[..., AsyncResult]:
    """Do-notation for AsyncResult.

    # TODO: do-notation is ~2x slower than raw bind chains due to generator
    # protocol overhead. Consider optimizing the generator loop or providing
    # a bind-chain builder as an alternative for performance-sensitive code.
    """

    def _thunk(*args, **kwargs):
        async def _run():
            gen = gen_fn(*args, **kwargs)
            try:
                monadic_val = next(gen)
                while True:
                    result = await monadic_val
                    match result:
                        case Ok(value):
                            monadic_val = gen.send(value)
                        case _:
                            return result
            except StopIteration as e:
                return Ok(e.value)

        return cls(_run())

    return _thunk

Try(f)

Decorator: wraps a sync function so exceptions become Err.

Source code in funstruct/monad/result/__init__.py 
365
366
367
368
369
370
371
372
373
374
375
376
377
def Try(
    f: Callable[_P, _A],
) -> Callable[_P, Result[_A]]:
    """Decorator: wraps a sync function so exceptions become Err."""

    @wraps(f)
    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> Result[_A]:
        try:
            return Ok(f(*args, **kwargs))
        except Exception as e:
            return Err(e)

    return wrapper

TryAsync(f) 

TryAsync(
    f: Callable[_P, Coroutine[Any, Any, _A]],
) -> Callable[_P, AsyncResult[_A]]

TryAsync(
    f: Callable[_P, _A],
) -> Callable[_P, AsyncResult[_A]]

Decorator: wraps a function so exceptions become Err.

Source code in funstruct/monad/result/__init__.py 
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
def TryAsync(
    f: Callable[_P, _A],
) -> Callable[_P, AsyncResult[_A]]:
    """Decorator: wraps a function so exceptions become Err."""

    @wraps(f)
    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> AsyncResult[_A]:
        async def _inner():
            try:
                result = f(*args, **kwargs)
                if inspect.isawaitable(result):
                    result = await result
                return Ok(result)
            except Exception as e:
                return Err(e)

        return AsyncResult(_inner())

    return wrapper