Detailed Documentation pythonic-fp.containers

Single item box

Stateful container holds at most one item of a given type.

class pythonic_fp.containers.box.Box
class pythonic_fp.containers.box.Box(value: D)

Container holding at most one item of a given type

  • where Box(item) contains at most one item of type ~D

    • Box() creates an empty container

    • can store any item of any type, including None

Initialize Box with an “optional” initial value.

Parameters:

value (~D) – “optional” initial value

bind(f)

Flatmap Box with function f.

Return type:

Box[T]

Returns:

a new instance

exchange(new_item)

Exchange an item with what is in the Box.

Return type:

~D

Raises:

ValueError – if box is empty

get()
get(alt: pythonic_fp.containers.box.D) → pythonic_fp.containers.box.D
get(alt: pythonic_fp.fptools.singletons.Sentinel)
get(alt=Sentinel('Box'))

Return the contained value if it exists, otherwise an alternate value.

Return type:

~D

Raises:

ValueError – when an alternate value is not provided but needed

map(f)

Map function f over contents.

Return type:

Box[T]

Returns:

a new instance

pop()

Pop the value if Box is not empty.

Return type:

~D

Raises:

ValueError – if box is empty

push(item)

Push an item in an empty Box.

Raises:

ValueError – if box is not empty

Return type:

Optional[Never]

put(item)

Put an item in the Box. Discard any previous contents.

Return type:

None

Functional Tuple

Pythonic FP - Functional Tuple

class pythonic_fp.containers.functional_tuple.FunctionalTuple(iterable=(), /)

Functional Tuple suitable for inheritance

  • Supports both indexing and slicing

  • FunctionalTuple addition and int multiplication supported

    • addition concatenates results, resulting in a Union type

    • both left and right int multiplication supported

    • homogeneous in its data type

    • supports being further inherited from

    • unslotted

  • Since these tuples are homogeneous, their covariance may be quirky

accummulate(f, s=None, /)

Accumulate partial folds

Accumulate partial fold results in an FunctionalTuple with an optional starting value.

Return type:

FunctionalTuple[L]

bind(f, type=FM.CONCAT, /)

Bind function f to the FunctionalTuple.

  • FM Enum types

    • CONCAT: sequentially concatenate iterables one after the other

    • MERGE: round-robin merge iterables until one is exhausted

    • EXHAUST: round-robin merge iterables until all are exhausted

Parameters:

ds – values to instantiate FunctionalTuple

Return type:

Union[FunctionalTuple[U], Never]

Returns:

resulting FunctionalTuple

copy()

Return a shallow copy of FunctionalTuple in O(1) time & space complexity.

Return type:

FunctionalTuple[+D]

foldl(f, /, start=None, default=None)

Fold Left

  • fold left with an optional starting value

  • first argument of function f is for the accumulated value

Raises:

ValueError – when FunctionalTuple empty and a start value not given

Return type:

Optional[L]

foldr(f, /, start=None, default=None)

Fold Right

  • fold right with an optional starting value

  • second argument of function f is for the accumulated value

Raises:

ValueError – when FunctionalTuple empty and a start value not given

Return type:

Optional[R]

pythonic_fp.containers.functional_tuple.functional_tuple(*ds)

Construct a FunctionalTuple from arguments.

Parameters:

ds – values to instantiate FunctionalTuple

Returns:

resulting FunctionalTuple

Immutable List

Pythonic FP - Immutable guaranteed hashable lists

  • hashable if elements are hashable

  • declared covariant in its generic datatype - hashability should be enforced by LSP tooling - hashability will be enforced at runtime - ImmutableList addition supported via concatenation - ImmutableList integer multiplication supported

class pythonic_fp.containers.immutable_list.ImmutableList(*dss)

Immutable List like data structure.

  • its method type parameters are also covariant

  • hashability will be enforced by LSP tooling

  • supports both indexing and slicing

  • addition concatenates results, resulting type a Union type

  • both left and right int multiplication supported

accummulate(f, s=None, /)

Accumulate partial folds

Accumulate partial fold results in an ImmutableList with an optional starting value.

Return type:

ImmutableList[L]

bind(f, type=FM.CONCAT, /)

Bind function f to the ImmutableList.

  • FM Enum types

    • CONCAT: sequentially concatenate iterables one after the other

    • MERGE: round-robin merge iterables until one is exhausted

    • EXHAUST: round-robin merge iterables until all are exhausted

Return type:

Union[ImmutableList[U], Never]

foldl(f, /, start=None, default=None)

Fold Left

  • fold left with an optional starting value

  • first argument of function f is for the accumulated value

“raises ValueError: when empty and a start value not given

Return type:

Optional[L]

foldr(f, /, start=None, default=None)

Fold Right

  • fold right with an optional starting value

  • second argument of function f is for the accumulated value

“raises ValueError: when empty and a start value not given

Return type:

Optional[R]

pythonic_fp.containers.immutable_list.immutable_list(*ts)

Function to produce an ImmutableList from a variable number of arguments.

Parameters:

ds – initial values to push onto a new ImmutableList from right to left

Return type:

ImmutableList[TabError]

Maybe Monad

Pythonic FP - Maybe Monad

class pythonic_fp.containers.maybe.MayBe
class pythonic_fp.containers.maybe.MayBe(value: D)

Maybe monad, data structure wrapping a potentially missing value.

  • where MayBe(value) contains a possible value of type +D

  • MayBe() represent a non-existent or missing value of type +D

  • immutable semantics

    • immutable, therefore made covariant

    • can store any item of any type, including None

    • can store any value of any type with one exception

:: warning:

hashability invalidated if contained value is not hashable

:: note:

MayBe(): MayBe[+D] -> mb: Xor[+D] MayBe(value: +D) -> mb: Xor[+D]

bind(f)

Flatmap MayBe with function f.

Return type:

MayBe[U]

bind_except(f)

Flatmap MayBe with function f.

:: warning:

Swallows exceptions

Return type:

MayBe[U]

static failable_call(f, t)

Return MayBe wrapped result of a function call that can fail.

Return type:

MayBe[V]

static failable_index(vs, ii)

Return a MayBe of an indexed value that can fail.

Return type:

MayBe[V]

get()
get(alt: pythonic_fp.containers.maybe.D) → pythonic_fp.containers.maybe.D
get(alt=Sentinel('MayBe'))

Return the contained value if it exists, otherwise an alternate value.

:: warning:

Unsafe method get. Will raise ValueError if MayBe empty and an alt return value not given. Best practice is to first check the MayBe in a boolean context.

Return type:

+D

Raises:

ValueError – when an alternate value is not provided but needed

map(f)

Map function f over contents.

Return type:

MayBe[U]

map_except(f)

Map function f over contents.

If f should fail, return a MayBe().

:: warning:

Swallows exceptions

Return type:

MayBe[U]

static sequence(sequence_mb_u)

Sequence a mutable indexable of type MayBe[~U]

If the iterated MayBe values are not all empty,

  • return a MayBe of the Sequence subtype of the contained values

  • otherwise return an empty MayBe

Return type:

MayBe[Sequence[U]]

Either Monad

Pythonic FP - Either monad

  • class Xor: left biased either monad

class pythonic_fp.containers.xor.Xor(value: L, side: Truth)
class pythonic_fp.containers.xor.Xor(value: R, side: Lie)

Either monad, data structure semantically containing either a left or a right value, but not both.

Implements a left biased Either Monad.

  • Xor(value: +L, LEFT) produces a left Xor

  • Xor(value: +L, RIGHT) produces a right Xor

In a Boolean context

  • True if a left Xor

  • False if a right Xor

Two Xor objects compare as equal when

  • both are left values or both are right values whose values

    • are the same object

    • compare as equal

Immutable, an Xor does not change after being created.

  • immutable semantics, map & bind return new instances

    • warning: contained value need not be immutable

    • warning: not hashable if value is mutable

:: Note:

Xor(value: +L, side: Left): Xor[+L, +R] -> left: Xor[+L, +R] Xor(value: +R, side: Right): Xor[+L, +R] -> right: Xor[+L, +R]

bind(f)

Flatmap over the left value, propagate right values.

Return type:

Xor[U, +R]

bind_except(f, fallback_right)

Flatmap Xor with function f with fallback right

:: warning:

Swallows exceptions.

Parameters:

fallback_right (+R) – fallback value if exception thrown

Return type:

Xor[U, +R]

static failable_call(f, left)

Return Xor wrapped result of a function call that can fail

:: warning:

Swallows exceptions.

Return type:

Xor[V, Exception]

static failable_index(v, ii)

Return an Xor of an indexed value that can fail.

:: warning:

Swallows exceptions.

Return type:

Xor[V, Exception]

get()

Get value if a left.

:: warning:

Unsafe method get. Will raise ValueError if Xor is a right. Best practice is to first check the Xor in a boolean context.

Returns:

its value if a Left

Return type:

+L

Raises:

ValueError – if not a left

get_left()

Get value of Xor if a left. Safer version of get method.

  • if Xor contains a left value, return it wrapped in a MayBe

  • if Xor contains a right value, return MayBe()

Return type:

MayBe[+L]

get_right()

Get value of Xor if a right

  • if Xor contains a right value, return it wrapped in a MayBe

  • if Xor contains a left value, return MayBe()

Return type:

MayBe[+R]

map(f)

Map over if a left value. Return new instance.

Return type:

Xor[U, +R]

map_except(f, fallback_right)

Map over if a left value - with fallback upon exception.

  • if Xor is a left then map f over its value

    • if f successful return a left Xor[+U, +R]

    • if f unsuccessful return right Xor[+U, +R]

      • swallows many exceptions f may throw at run time

  • if Xor is a right

    • return new Xor(right=self._right): Xor[+U, +R]

Return type:

Xor[U, +R]

map_right(f)

Construct new Xor with a different right.

Return type:

Xor[+L, V]

static sequence(sequence_xor_uv)

Sequence an indexable of type Xor[~U, ~V]

If the iterated Xor values are all lefts, then return an Xor of an iterable of the left values. Otherwise return a right Xor containing the first right encountered.

Return type:

Xor[Sequence[U], V]