Option and Result

Option[T] represents a present or absent value. Result[T] contains either a successful value or an exception.

Option

fpstreams.Option dataclass

Bases: Generic[T]

Store either one non-None value or an empty state.

Instances are immutable and cannot distinguish a present None from absence. Use of(), of_nullable(), or empty() to make that choice explicit.

of classmethod

of(value: T) -> Option[T]

Create a present option from a non-None value.

Parameters:

Name	Type	Description	Default
value	T	Value to store.	required

Returns:

Type	Description
Option[T]	A present option containing value.

Raises:

Type	Description
ValueError	If value is None.

of_nullable classmethod

of_nullable(value: T | None) -> Option[T]

Create a present option from value, or an empty option from None.

Parameters:

Name	Type	Description	Default
value	T | None	Nullable value to convert.	required

Returns:

Type	Description
Option[T]	Option.empty() for None; otherwise an option containing value.

empty classmethod

empty() -> Option[T]

Create an option whose stored state is absent.

Returns:

Type	Description
Option[T]	An empty option.

is_present

is_present() -> bool

Report whether this option stores a non-None value.

Returns:

Type	Description
bool	True for a present value and False for an empty option.

is_empty

is_empty() -> bool

Report whether this option stores None as its empty marker.

Returns:

Type	Description
bool	True for an empty option and False for a present value.

if_present

if_present(action: Callable[[T], None]) -> None

Invoke action once with the stored value, if one is present.

Parameters:

Name	Type	Description	Default
action	Callable[[T], None]	Side-effecting callable skipped for an empty option.	required

filter

filter(predicate: Callable[[T], bool]) -> Option[T]

Keep a present value only when predicate accepts it.

Empty options and accepted values return the current immutable instance. A rejected value produces a new empty option. Exceptions from predicate propagate.

Parameters:

Name	Type	Description	Default
predicate	Callable[[T], bool]	Callable evaluated only for a present value.	required

Returns:

Type	Description
Option[T]	This option when empty or accepted; otherwise an empty option.

map

map(mapper: Callable[[T], R | None]) -> Option[R]

Map a present value and convert a mapped None to absence.

The mapper is skipped for an empty option. Unlike Result, this method does not capture mapper exceptions.

Parameters:

Name	Type	Description	Default
mapper	Callable[[T], R | None]	Callable applied to the stored value.	required

Returns:

Type	Description
Option[R]	An option containing the mapped value, or an empty option if this option is empty or the mapper returns None.

flat_map

flat_map(mapper: Callable[[T], Option[R]]) -> Option[R]

Return the option produced by mapping a present value.

The mapper is skipped for an empty option. Its return value and any exception are passed through without additional wrapping or validation.

Parameters:

Name	Type	Description	Default
mapper	Callable[[T], Option[R]]	Option-returning callable applied to the stored value.	required

Returns:

Type	Description
Option[R]	The mapper's result, or an empty option when this option is empty.

unwrap

unwrap() -> T

Extract the stored value, rejecting an empty option.

Returns:

Type	Description
T	The contained value.

Raises:

Type	Description
ValueError	If this option is empty.

or_else

or_else(other: T) -> T

Return the stored value, or the eagerly supplied fallback when empty.

Parameters:

Name	Type	Description	Default
other	T	Value to return only when this option is empty.	required

Returns:

Type	Description
T	The contained value, or other when this option is empty.

or_else_get

or_else_get(supplier: Callable[[], T]) -> T

Return the stored value, or lazily call supplier when empty.

Parameters:

Name	Type	Description	Default
supplier	Callable[[], T]	Zero-argument fallback callable, skipped for a present value.	required

Returns:

Type	Description
T	The contained value, or the value supplied when this option is empty.

or_else_throw

or_else_throw(exception: Callable[[], Exception]) -> T

Return the stored value, or construct and raise an exception when empty.

Parameters:

Name	Type	Description	Default
exception	Callable[[], Exception]	A zero-argument callable that creates the exception to raise.	required

Returns:

Type	Description
T	The contained value.

Raises:

Type	Description
Exception	The exception produced by exception when this option is empty.

Result

fpstreams.Result

Bases: Generic[T]

Common interface for a successful Ok or failed Err value.

error property

error: Exception | None

Expose the stored failure exception, or None for success.

Returns:

Type	Description
Exception | None	The exception stored by Err, or None for Ok.

success classmethod

success(value: T) -> Result[T]

Create an Ok containing value.

Parameters:

Name	Type	Description	Default
value	T	Successful value to store.	required

Returns:

Type	Description
Result[T]	A new successful result.

failure classmethod

failure(error: Exception) -> Result[T]

Create an Err containing error.

Parameters:

Name	Type	Description	Default
error	Exception	The exception stored in a failed result.	required

Returns:

Type	Description
Result[T]	A new failed result typed for the caller's expected success value.

of classmethod

of(function: Callable[[], T]) -> Result[T]

Call a zero-argument function and capture ordinary exceptions as failure.

A normal return becomes Ok; an Exception becomes Err. Exceptions outside the Exception hierarchy, such as KeyboardInterrupt, propagate.

Parameters:

Name	Type	Description	Default
function	Callable[[], T]	Zero-argument computation to evaluate immediately.	required

Returns:

Type	Description
Result[T]	Ok(function()), or Err(error) when the call raises error.

is_success

is_success() -> bool

Report whether this instance is an Ok.

Returns:

Type	Description
bool	True for Ok and False for Err.

is_failure

is_failure() -> bool

Report whether this instance is an Err.

Returns:

Type	Description
bool	True for Err and False for Ok.

map

map(mapper: Callable[[T], R]) -> Result[R]

Map an Ok value while preserving an existing Err.

The mapper runs only for success. Its return value becomes a new Ok, and any ordinary exception it raises becomes Err. A failed result returns itself unchanged.

Parameters:

Name	Type	Description	Default
mapper	Callable[[T], R]	Callable applied to a successful value.	required

Returns:

Type	Description
Result[R]	The mapped success, captured mapper failure, or original failed result.

and_then

and_then(mapper: Callable[[T], Result[R]]) -> Result[R]

Chain an Ok through a result-returning callable and bypass an Err.

Exceptions raised while mapping a success are captured as Err. The mapper's return value is passed through without runtime type validation.

Parameters:

Name	Type	Description	Default
mapper	Callable[[T], Result[R]]	Result-returning callable applied only to a successful value.	required

Returns:

Type	Description
Result[R]	The mapper's result, a captured mapper exception, or the original failure.

flat_map

flat_map(mapper: Callable[[T], Result[R]]) -> Result[R]

Alias and_then() for chaining result computations.

The callable runs only for success; existing failures pass through unchanged.

Parameters:

Name	Type	Description	Default
mapper	Callable[[T], Result[R]]	Result-returning callable applied only to a successful value.	required

Returns:

Type	Description
Result[R]	Exactly self.and_then(mapper).

map_err

map_err(
    mapper: Callable[[Exception], Exception],
) -> Result[T]

Map an Err exception while preserving an existing Ok.

Mapper exceptions are not captured; they propagate to the caller.

Parameters:

Name	Type	Description	Default
mapper	Callable[[Exception], Exception]	Callable that converts the stored exception.	required

Returns:

Type	Description
Result[T]	A new Err for a failure, or the original successful result.

map_error

map_error(
    mapper: Callable[[Exception], Exception],
) -> Result[T]

Alias map_err() for transforming a stored exception.

Parameters:

Name	Type	Description	Default
mapper	Callable[[Exception], Exception]	Callable that converts the stored exception.	required

Returns:

Type	Description
Result[T]	Exactly self.map_err(mapper).

on_success

on_success(action: Callable[[T], None]) -> Result[T]

Run a side effect for Ok and return this same result instance.

The action is skipped for Err; exceptions raised by the action propagate.

Parameters:

Name	Type	Description	Default
action	Callable[[T], None]	Callable invoked with the successful value.	required

Returns:

Type	Description
Result[T]	self, unchanged.

on_failure

on_failure(
    action: Callable[[Exception], None],
) -> Result[T]

Run a side effect for Err and return this same result instance.

The action is skipped for Ok; exceptions raised by the action propagate.

Parameters:

Name	Type	Description	Default
action	Callable[[Exception], None]	Callable invoked with the stored exception.	required

Returns:

Type	Description
Result[T]	self, unchanged.

unwrap

unwrap() -> T

Extract an Ok value or raise the exception stored by Err.

Returns:

Type	Description
T	The successful value.

Raises:

Type	Description
Exception	The stored failure exception when this result is unsuccessful.

get_or_throw

get_or_throw() -> T

Alias unwrap() for extracting success or raising failure.

Returns:

Type	Description
T	The successful value.

get_or_else

get_or_else(default: T) -> T

Return the Ok value or an eagerly supplied default for Err.

Parameters:

Name	Type	Description	Default
default	T	Value returned only for a failed result.	required

Returns:

Type	Description
T	The successful value, or default for a failure.