maybe monad

final class pythonic_fp.fptools.maybe.MayBe

Bases: Generic

Maybe Monad

Data structure wrapping a potentially missing item.

• immutable semantics

• can store any item of any type, including None

• hashable when contents are hashable

__init__() → None

__init__(data: D) → None

init

Initialize MayBe with 1 or 0 data items.

param data:

Optional data item for the MayBe instance.

Important

• a MayBe is immutable once initialized

• MayBe() is not a singleton

__hash__() → int

hash

returns:

The integer hash for the MayBe instance.

raises TypeError:

When contained object is not hashable.

Note

If contained item hashable, use its hash value in the hash calculation, otherwise the MayBe will be unhashable.

• should be safe, the MayBe holds a reference to the item

• only calculates its hash value when necessary

• if contained value unhashable, MayBe will be unhashable

Tip

Use MayBe instances as dict keys or set members only when the type of contained data is hashable.

__eq__(other: object) → bool

equality comparison

Compare MayBe instance to another object. Compare first by identity, then value.

returns:

True only if other object is a MayBe with a corresponding item, or both empty.

__getstate__() → dict[str, object]

getstate

Don’t carry the hash value across pickling and spawn-based multiprocessing (the default on Windows and Mac-OS).

__setstate__(state: dict[str, object]) → None

setstate

Don’t carry the hash value across pickling and spawn-based multiprocessing (the default on Windows and Mac-OS).

__bool__() → bool

bool

Truthy when not empty.

returns:

True if not empty, False if empty.

__len__() → int

len

Zero or one items.

__iter__() → Iterator

iterate

yields:

The contained item.

__repr__() → str

repr string

returns:

A string to reproduce the MayBe.

Note

Return the strings

• ‘MayBe()’ if empty

• ‘MayBe(repr_item)’ if not empty

Where repr_item = repr(item).

__str__() → str

user string

returns:

A string meaningful to an end user.

Note

Return the strings

• ‘MayBe(str_item)’ when not empty

• ‘MayBe()’ when empty

Where str_item = str(item).

get() → D

get(alt: D) → D

get

Return the item if it exists, otherwise an optional alternate item.

param alt:

Optional alternative item to return if MayBe empty.

returns:

The item if it exists.

raises ValueError:

When an alternate item is not provided but needed.

Warning

Unsafe method get will raise ValueError() if the MayBe is empty and an alternate return item not provided.

Tip

Best practice is to first check the MayBe in a boolean context. Threadsafe since a MayBe is immutable once created.

map(f: Callable[[D], U]) → MayBe

map

Map function f over the MayBe.

param f:

Mapping function.

returns:

A new MayBe instance if not empty, otherwise itself.

map_except(f: Callable[[D], U]) → MayBe

map_except

Map function f over the MayBe.

param f:

Mapping function.

returns:

New MayBe instance if not empty and exception is not thrown, an empty Maybe if exception is thrown, otherwise itself.

Note

Swallows exceptions of types

• LookupError

• ValueError

• ArithmeticError

• RuntimeError

Does not attempt to stop exceptions

• TypeError

• AttributeError

• KeyboardInterrupt

bind(f: Callable[[D], MayBe]) → MayBe

bind

Flatmap function f over the MayBe.

param f:

Function to bind.

returns:

A new MayBe instance if not empty, otherwise itself.

bind_except(f: Callable[[D], MayBe]) → MayBe

bind_except

Flatmap function f over the MayBe.

param f:

Function to bind over contained values.

returns:

A successfully bound MayBe[U], a propagated

empty MayBe[U], or an empty MayBe[U] if an exception is raised.

Note

Swallows exceptions of types

• LookupError

• ValueError

• ArithmeticError

• RuntimeError

Does not attempt to stop exceptions

• TypeError

• AttributeError

• KeyboardInterrupt

static sequence(iterable_mb_u: Iterable[MayBe]) → MayBe[Iterable]

MayBe.sequence

Iterable[MayBe[U]] -> MayBe[Iterable[U]]

param sequence_mb_u:

An Iterable of MayBe[U] values.

returns:

Empty MayBe if one of the MayBe is empty, otherwise a MayBe of an Iterable of the contained values.

Note

A sequenced empty Iterable[MayBe[U]] would produce a MayBe of an empty Iterable, not an empty MayBe.