Option#
Closed optional values and pipe-friendly operations.
Option[T] is the union of Some[T] and the singleton case Nothing.
Match the case classes to access their payloads. Iteration and awaiting retain
the computation-expression protocol, including short-circuiting on Nothing.
- NOTHING: Final = Nothing()#
The canonical empty option, available without a constructor call.
- final class Nothing#
The empty option case, constructed and matched as
Nothing().Construction, copying, pickling, and Option decoding preserve one canonical instance. Use
NOTHINGto reuse it without calling the constructor.- async abind(mapper: Callable[[Never], Awaitable]) Nothing#
Return Nothing without invoking the continuation.
- async amap(mapper: Callable[[Never], Awaitable[object]]) Nothing#
Return Nothing without invoking the callback.
- apply(function: ~typing.Annotated[~expression.core.option.Some[~collections.abc.Callable[[~typing.Never], object]] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) Nothing#
Keep the empty option without invoking the optional function.
- bind(mapper: Callable[[Never], TOption]) Nothing#
Keep the empty option without evaluating the continuation.
- default_value(value: TResult) TResult#
Return the fallback value.
- default_with(getter: Callable[[], TResult]) TResult#
Evaluate the fallback factory.
- dict() dict[str, object]#
Encode the empty case with an explicit tag.
- filter(predicate: Callable[[Never], bool]) Nothing#
Keep the empty option without evaluating the predicate.
- is_none() bool#
Return True; use isinstance or the free guard for narrowing.
- is_some() bool#
Return False.
- map(mapper: Callable[[Never], object]) Nothing#
Keep the empty option without evaluating the mapper.
- map2(mapper: ~collections.abc.Callable[[~typing.Never, T2], object], other: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) Nothing#
Keep the empty option without evaluating the mapper.
- or_else(if_none: TOption) TOption#
Return the fallback option.
- or_else_with(if_none: Callable[[], TOption]) TOption#
Evaluate the fallback option factory.
- starmap(mapper: Callable[[...], object]) Nothing#
Keep the empty option without evaluating the mapper.
- tag: Literal['none'] = 'none'#
- to_list() list[_TEmpty]#
Return an empty list.
- to_optional() None#
Return None.
- to_result_with(error: Callable[[], TError]) Error[TError]#
Evaluate the error factory and return a failed result.
- property value: Never#
Raise ValueError because this option has no payload.
- final class Some(some: _TSourceOut)#
An optional value that is present, including when its payload is None.
- async abind(mapper: Callable[[_TSourceOut], Awaitable]) TOption#
Await an option-returning callback without wrapping its result.
- async amap(mapper: Callable[[_TSourceOut], Awaitable]) Some#
Await a mapper and wrap its value, propagating exceptions and cancellation.
- apply(function: ~typing.Annotated[~expression.core.option.Some[~collections.abc.Callable[[~expression.core.option._TSourceOut], TResult]] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) UnionSchema object at 0x711f63799d10>]#
Apply an optional function to the present value.
- bind(mapper: Callable[[_TSourceOut], TOption]) TOption#
Apply a function returning another option.
- default_value(value: object) _TSourceOut#
Return the present value.
- default_with(getter: Callable[[], object]) _TSourceOut#
Return the present value without evaluating the fallback.
- dict() dict[str, object]#
Encode a tagged value, preserving None and nested option cases.
- filter(predicate: Callable[[_TSourceOut], bool]) UnionSchema object at 0x711f63799d10>]#
Keep the value when the predicate holds.
- is_none() bool#
Return False.
- is_some() bool#
Return True; use isinstance or the free guard for narrowing.
- map2(mapper: ~collections.abc.Callable[[~expression.core.option._TSourceOut, T2], TResult], other: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) UnionSchema object at 0x711f63799d10>]#
Transform two present values, or return Nothing.
- or_else(if_none: ~typing.Annotated[~expression.core.option.Some[object] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) Some[_TSourceOut]#
Keep the present value.
- or_else_with(if_none: ~collections.abc.Callable[[], ~typing.Annotated[~expression.core.option.Some[object] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]]) Some[_TSourceOut]#
Keep the present value without evaluating the fallback.
- some: _TSourceOut#
- starmap(mapper: Callable[[Unpack[P]], TResult]) Some#
Apply a function to the unpacked tuple payload.
- tag: Literal['some'] = 'some'#
- to_list() list[_TSourceOut]#
Return a one-element list.
- to_optional() _TSourceOut#
Return the present value, erasing the option wrapper.
- to_result_with(error: Callable[[], object]) Ok[_TSourceOut]#
Return a successful result without evaluating the error factory.
- property value: _TSourceOut#
Return the payload; use matching when the case is not known.
- abind(mapper: Callable[[TSource], Awaitable]) _AsyncBind#
Create an async binding stage, preserving Nothing without invoking the callback.
Await the stage’s coroutine to obtain the callback’s option directly. Exceptions and cancellation propagate.
- amap(mapper: Callable[[TSource], Awaitable]) _AsyncMap#
Create an async mapping stage for pipe or apipe.
Await the returned stage’s coroutine to map Some, preserving Nothing without invoking the callback. Exceptions and cancellation propagate.
- apply(function: Nothing) Nothing]#
- apply(function: Option[Callable[[TSource], TResult]]) Callable[[Option[TSource]], Option[TResult]]
Apply an optional function to an optional value.
- bind(mapper: Callable[[TSource], TOption]) Nothing]#
Apply an option-returning function to a present value.
- default_arg(value: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], default_value: T1) TSource | T1#
Return the payload or an uncurried fallback value.
- default_value(value: T1) _DefaultValue#
Return an operation selecting the payload or a fallback value.
- default_with(getter: Callable[[], T1]) _DefaultWith#
Return an operation selecting the payload or evaluating a fallback.
- is_none(option: ~typing.Annotated[~expression.core.option.Some[object] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) TypeGuard[Nothing]#
Narrow an option to its empty case.
- is_some(option: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) TypeGuard[Some]#
Narrow an option to its present case.
- map(option: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], mapper: ~collections.abc.Callable[[TSource], TResult]) UnionSchema object at 0x711f63799d10>]#
- map2(opt1: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], opt2: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], mapper: ~collections.abc.Callable[[T1, T2], TResult]) UnionSchema object at 0x711f63799d10>]#
- model_dump(value: ~typing.Annotated[~expression.core.option.Some[object] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) dict[str, object]#
Encode an option using its tagged wire representation.
- of_obj(value: None) Nothing#
- of_obj(value: TSource | None) Option[TSource]
Wrap a value, treating None as absence.
- of_optional(value: None) Nothing#
- of_optional(value: TSource | None) Option[TSource]
Wrap a value, treating None as absence.
- of_result(result: Ok[TSource]) Some[TSource]#
- of_result(result: Error[object]) Nothing
Keep the successful result payload, or return Nothing.
- or_else(option: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], if_none: ~typing.Annotated[~expression.core.option.Some | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) UnionSchema object at 0x711f63799d10>]#
Return the first present option, allowing a different fallback type.
- starmap(option: ~typing.Annotated[~expression.core.option.Some[tuple[~typing.Unpack[~typing.P]]] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>], mapper: ~collections.abc.Callable[[~typing.Unpack[~typing.P]], TResult]) UnionSchema object at 0x711f63799d10>]#
- to_list(option: ~typing.Annotated[~expression.core.option.Some[~expression.core.option._TEmpty] | ~expression.core.option.Nothing, <expression.core._union_schema.UnionSchema object at 0x711f63799d10>]) list[_TEmpty]#
- to_optional(value: Some[TSource]) TSource#
- to_optional(value: Nothing) None
Erase the option wrapper, mapping Nothing to None.
- to_result(value: Some[TSource], error: object) Ok[TSource]#
- to_result(value: Nothing, error: TError) Error[TError]
- to_result_with(value: Some[TSource], error: Callable[[], object]) Ok[TSource]#
- to_result_with(value: Nothing, error: Callable[[], TError]) Error[TError]
Async mapping and binding#
Use amap when a callback returns an awaitable value. Use abind when it returns
an awaitable containing another Option. Both have fluent methods and
pipe-friendly module functions.
from expression import NOTHING, Option, Some, apipe, option
async def describe(value: int) -> str:
return f"item-{value}"
async def lookup(value: int) -> Option[int]:
return Some(value * 2) if value > 0 else NOTHING
async def example() -> None:
assert await Some(2).amap(describe) == Some("item-2")
assert await Some(2).abind(lookup) == Some(4)
assert await apipe(Some(2), option.abind(lookup), option.amap(describe)) == Some("item-4")
Awaiting either operation returns an ordinary Option. The callback is invoked
only when the operation is awaited, and only for Some. Nothing is preserved
without invoking the callback. amap wraps the callback’s resolved value even
when it is None or another container; abind returns the callback’s container
directly. Neither operation recursively awaits the returned payload or container.
Callbacks can return any Awaitable, including futures and tasks. Exceptions and
cancellation propagate; they are not converted into Nothing. No background tasks
are started by these operations.
For a single functional step, await pipe(value, option.amap(callback)) works.
Use apipe for multiple async stages so each stage’s coroutine is awaited before
its result reaches the next stage. An amap/abind stage skips its callback on
Nothing; apipe itself still calls later stages with that container.