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 values is intended for “expected” results.

    • Right value gives information on the “unexpected” perhaps “exceptional” result.

  • 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, as well as LEFT and RIGHT EitherFlag, can be used as hidden 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

  • immutable

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

init

Initialize Either instance as a left or a right Either.

param value:

The value contained in the Either.

param side:

Determines whether to produce a “left” or a “right” Either.

type side:

EitherFlag

__hash__() → int

hash

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

  • Should be safe, the Either holds a reference to the value.

  • Lazily calculates hash value, then caches it.

  • The hash also depends if the Either is a left or right.

__bool__() → bool

bool

  • left Eithers are truthy

  • right Eithers are falsy

returns:

True if Either is a left, False if a right.

__len__() → int

len

An Either always contains just one value.

returns:

1

__eq__(other: object) → bool

equality comparison

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

param other:

The object to be compared.

returns:

True only if other is a Either of the same side containing objects which compare as equal.

__iter__() → Iterator

iter

Yield the contained value if Either is a left.

yields:

The contained value if a left.

__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).

returns:

A string to reproduce the Either.

__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).

returns:

A string meaningful to an end user.

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 the 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 wrapping a left value.

rtype:

MayBe[L]

get_right() → MayBe

get right

Get the value if a right.

returns:

MayBe wrapping a right value.

rtype:

MayBe[R]

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

map right

Map the function f over the contents of a right Either.

param f:

A function to map a right value.

returns:

A new Either instance if a right, otherwise itself.

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

map

Map the function f over a left Either.

param f:

A function used to map a left value.

returns:

A new Either if a left, otherwise itself.

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

map except

Map function 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 the 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

LEFT and RIGHT singleton flags

Boolean-like type which can

  • signal the Either initializer to create either a left or right Either instance

  • be combined like Booleans with Python bitwise operators

__repr__() → str

repr string

Construct one of two strings:

  • ‘EitherFlag{True)’ for the LEFT EitherFlag

  • ‘EitherFlag{False)’ for the RIGHT EitherFlag

returns:

A string to construct the appropriate EitherFlag singleton.

__str__() → str

user string

Construct one of two strings:

  • ‘LEFT’ for a LEFT EitherFlag

  • ‘RIGHT’ for a RIGHT EitherFlag

returns:

A string meaningful to an end user.

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

The truthy EitherFlag

Used by the Either initializer to make a left Either.

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

The falsy EitherFlag

Used by the Either initializer to make a right Either.