either monad

The Either monad

Data structure semantically containing either a “left” value or a “right” value, but not both.

  • Module implements a left biased either monad

    • left value is intended for the “expected” result

    • right value gives information on something “exceptional”

  • left and right values can be the same or different types

  • in a boolean context

    • left values are truthy

    • right values are falsy

Tip

Happy path without exceptions.

Instead of catching an exception whenever the “happy path” fails, process the left values and either deal with or propagate right values.

Tip

Right Either instances can be used as sentinel values.

final class pythonic_fp.fptools.either.Either

Bases: Generic

Either monad

Left biased Either monad.

  • immutable semantics

  • contains either a “left” or a “right” item, but not both

  • hashable

Important

An Either is immutable once initialized.

__init__(value: L) → None
__init__(value: L, side: EitherFlag) → None
__init__(value: R, side: EitherFlag) → None

initializer

Initialize Either instance as a “left” or a “right”.

param value:

The value contained in the Either.

param side:

Determines whether to produce a left or right Either.

__hash__() → int

hashability

If contained value hashable, use its hash value in the hash calculation, otherwise use item’s identity.

  • should be safe, the Either holds a reference to the value

  • lazily calculates hash value, then caches it

  • hash also depends if Either is a left or right

__bool__() → bool

bool

  • left Either is truthy

  • right Either is falsy

__len__() → int

len

Either always contains just one value.

__eq__(other: object) → bool

equality comparison

Compare Either to another object. Compare first by identity, then value.

__iter__() → Iterator

iterate

Iterate value if a left Either.

__repr__() → str

representation string

Return the strings

  • ‘Either(repr_value, LEFT)’ if a left

  • ‘Either(repr_value, RIGHT)’ if if a right

Where repr_value = repr(value).

__str__() → str

user string

Return the strings

  • ‘Either(str_value)’ when a left

  • ‘Either(str_value, RIGHT)’ when a right

Where str_value = str(value).

get() → L

get

Get value if a left.

returns:

The value if a left.

raises ValueError:

If not a left.

Warning

Unsafe method get. Will raise ValueError if Either is a right.

Tip

Best practice is to first check the Either in a boolean context.

get_left() → MayBe

get left

Get the value if a left.

returns:

MayBe[L]

get_right() → MayBe

get right

Get the value if a right.

returns:

MayBe[R]

map_right(f: Callable[[R], V]) → Either[L, V]

map right

Map function f over the contents of a right Either.

param f:

function to map a right value

returns:

A new Either if a right, otherwise self.

map(f: Callable[[L], U]) → Either[U, R]

map

Map function f over left Either.

param f:

Function used to map left values.

returns:

A new Either if a left, otherwise self.

map_except(f: Callable[[L], U], fallback_right: R) → Either[U, R]

map except

Map f over left Either with a right fallback upon exception.

param f:

Function used to map left values.

param fallback_right:

Fallback value if exception thrown.

returns:

A successfully mapped left, a propagated right, or a right with a fallback value.

Warning

Swallows exceptions.

bind(f: Callable[[L], Either[U, R]]) → Either[U, R]

bind

Flatmap function f over a left value. Propagate right values.

param f:

Function to bind.

returns:

A new Either if a left, otherwise itself.

bind_except(f: Callable[[L], Either[U, R]], fallback_right: R) → Either[U, R]

bind except

Flatmap function f over Either, with fallback upon exception. Propagate right values.

param f:

Function to bind over values.

param fallback_right:

Fallback value if exception thrown.

returns:

A successfully bound left, a propagated right, or a right with a fallback value.

Warning

Swallows exceptions.

static sequence(sequence_either_uv: Sequence[Either]) → Either[Sequence, V]

sequence

Sequence[Either[U, V]] -> Either[Sequence[U], V]

If all Either are lefts, then return an Either of the Sequence of contained left values. Otherwise return a right Either containing the first right encountered.

final class pythonic_fp.fptools.either.EitherFlag

Bases: SBool

Type for LEFT and RIGHT singleton flags

Boolean-like type for signaling the Either initializer to make a left or right Either instance.

__repr__() → str

string representation

Two values ‘LEFT’ or ‘RIGHT’ for the truthy and falsy singletons respectfully. Also the default user strings.

pythonic_fp.fptools.either.LEFT: Final[EitherFlag] = TRUTH

truthy Either flag

Used by Either initializer to make a right Either.

pythonic_fp.fptools.either.RIGHT: Final[EitherFlag] = LIE

falsy Either flag

Used by Either initializer to make a right Either.