Cloak Option Type

Class implementations

class cloak.option.Option

Bases: cloak.monadic.Monadic, cloak.immutable.Immutable

Option is the abstract type that both Some and Nothing (which is a singleton with the instance bound to nil), inherit from. It should both respect the monad laws, as well as be immutable.

exists(predicate_callable)

If the current option is Some, this method results the result of predicate_callable called with the inner value as its only argument cast to bool.

If the current option is nil/Nothing, this method always returns False, and predicate_callable is never evaluated.

Parameters:predicate_callable (T -> bool) – A function that evaluates if an inner value exists that satisfies its embodied predicate Returns:True if an element exists that satisfies the predicate, False otherwise. Return type:bool

filter(filter_callable)

If the current option is Some, this method returns the current Option object if filter_callable returns a value that converts to True when evaluated with the inner value. If the result is False, the Nothing singleton nil is returned.

If the current option is nil/Nothing, the current option object (which is the same as nil), is always returned and filter_callable is not evaluated.

Parameters:filter_callable (T -> bool) – A function which is evaluated on the inner value, if present. Returns:The current object if it has an inner value (i.e. not nil), and the evaluation of filter_callable is truthy. Otherwise returns nil. Return type:cloak.option.Option

flatten()

Flatten is similar to join, with an additional check made that InnerValueNotContainerTypeException will be thrown if the inner value exists, but does not inherit from cloak.option.Option.

Returns:The extracted option, if applicable. Return type:Option[T]

get()

Extract and return the inner value if the option is Some, else throw NoSuchElementException if nil.

Returns:The inner value if present, else raise NoSuchElementException

get_or_else(else_value)

Extract and return the inner value if the option is Some, or return else_value if this is nil.

Parameters:else_value – The value to return if the option is nil/Nothing. Returns:The inner value if present, else else_value

is_defined

is_defined must be defined by the corresponding subtype, and is False if the container is nil, and True if the container is Some

Returns:False if nil, True if Some. Return type:bool

is_empty

is_empty must be defined by the corresponding subtype, and is True if the container is nil, and False if the container is Some

Returns:True if nil, False if Some. Return type:bool

join()

Extract the inner value from option if it has one, otherwise return nil.

Returns:The inner value or nil if the origin object is nil. Return type:T | Nothing

map(map_func)

Apply the map_func to the inner value, if it exists, and return a new Option with the result of the computation. If the Option is nil, map_func is not called, and nil is returned.

Parameters:map_func (T -> S) – An arity one function to apply to the inner value, if it exists. The computation will be returned in a new Option. Returns:A Some container with the computation result, if the original option was not nil/Nothing. Otherwise nil is returned. Return type:Option[S]

or_else(alternative_callable, *args, **kwargs)

Return the current option if the option is Some, else call alternative_callable and return its result if the option is nil/Nothing.

Parameters:

• alternative_callable (function | method) – A function to call and get a result from if the option is nil.
• args – Positional arguments to be passed to alternative_callable.
• kwargs – Keyword arguments to be passed to alternative_callable.

Returns:

The current option object itself, if it’s Some, else the result of calling alternative_callable with the specified arguments if the current option is nil/Nothing.

product_arity = 1

classmethod unit(value)

Create a new option unit container from a specified value.

Parameters:value (T) – The inner value for the resulting Option. Returns:The inner value in cloak.option.Option’s unit container, cloak.option.Some. Return type:Some[T]

classmethod zero()

Access the zero element for the cloak.option.Option type, cloak.option.nil

Returns:nil Return type:cloak.option.Nothing

class cloak.option.Some(value)

Bases: cloak.option.Option

Some[T] is the unit subtype for Option. It denotes the presence of an inner value.

exists(predicate_callable)

Check to see if the inner value satisfies the predicate_callable, by calling it with the inner value and returning the result of this computation converted to a boolean.

Parameters:predicate_callable (T -> bool) – This function take the inner value as its only argument and it’s return value is converted to bool and returned from this method. This is intended to allow the programmer to determine if the inner value exists, and satisfies an arbitrary criterion embedded in the predicate_callable. Returns:True if the result of predicate_callable can be converted to True, False otherwise. Return type:bool

filter(filter_callable)

Check to see if the inner value satisfies the filter_callable, by calling it with the inner value and returning the result of this computation converted to a boolean. If True, the current option is returned, if False the nil Option is returned.

Parameters:filter_callable (T -> bool) – This function take the inner value as its only argument and is used to determine if the current Some option is returned or nil. If filter_callable evaluates to False, nil is returned, if True the current Some Option is returned Returns:The current option object is filter_callable evaluates to True, otherwise nil Return type:Option

flatten()

Extract the inner value, if it’s an Option subclass. If the inner value is not an instance of Option, InnerValueNotContainerTypeException is raised.

Returns:The inner value, if it’s an Option subtype. Return type:T

for_each(apply_callable)

Run a side-effecting callable on the inner value. This is pretty much syntatic sugar over the bind method.

Parameters:apply_callable (T -> Any) – The callable to execute with the inner value as its only argument. Returns:None Return type:NoneType

get()

Extract and return the inner value.

Returns:The inner value. Return type:T

get_or_else(_)

Extract and return the inner value.

Parameters:_ (S) – The value that would have been returned if this Option were nil. Returns:The inner value. Return type:T

is_defined

is_defined is always True for the Some Option subtype. This signifies that the inner value is defined.

Returns:True Return type:bool

is_empty

is_empty is always False for the Some Option subtype. This signifies the inner value is not empty.

Returns:False Return type:bool

join()

Extract and return the inner value.

Returns:The inner value. Return type:T

map(map_func)

Apply a computation to the inner value, and return the result in a new Option.

Parameters:map_func (T -> S) – The arity one computation function to apply to the inner value. Returns:A new option contained the result of the applied computation. Return type:Option[S]

or_else(alternative_callable, *args, **kwargs)

Return the current Some object.

Parameters:

• alternative_callable (S -> U) – The callable function that would have been called if this Option were nil.
• args – Positional arguments to the alternative_callable.
• kwargs – Keyword arguments to the alternative_callable.

Returns:

The current object (self)

Return type:

Some[T]

class cloak.option.Nothing(_)

Bases: cloak.option.Option

Nothing[T] is the zero subtype for Option. It denotes the absence of a contained inner value.

Nothing exists as a singleton, called nil.

exists(_)

Return False, because there was no inner value to check if the callable returns true for.

Parameters:_ (T -> bool) – The callable that would have been evaluated on the inner value to return some truthiness, if an inner value was present. This never gets called when the Option is nil. Returns:False Return type:bool

filter(_)

Return nil, because there was no inner value to check if the callable returns true for.

Parameters:_ (T -> bool) – The callable that would have been evaluated on the inner value to return some truthiness to filter the option if an inner value was present. This never gets called when the Option is nil. Returns:nil Return type:Nothing

flatten()

Return nil, because there was no inner value to flatten.

Returns:nil Return type:Nothing

for_each(_)

Because the Option is nil, this method is a noop.

Parameters:_ (T -> S) – The side-effecting callable that would have been evaluated on the inner value, if it were present. Returns:None Return type:NoneType

get()

Raise NoSuchElementException, because there was no inner value to extract.

Returns:Does not return. Raises NoSuchElementException.

get_or_else(else_value)

Return the alternative value, because there was no inner value to return.

Parameters:else_value (T) – The alternative value to return. Returns:else_value Return type:T

is_defined

is_defined is always False for the Nothing/nil Option subtype. This signifies the inner value is empty.

Returns:False Return type:bool

is_empty

is_empty is always True for the Nothing/nil Option subtype. This signifies the inner value is empty.

Returns:True Return type:bool

join()

Return nil, because there was no inner value to join on.

Returns:nil Return type:Nothing

map(_)

Return nil, because there was no inner value for the function to operate on.

Parameters:_ (T -> S) – The map callable that would have operated on the inner value. Returns:nil Return type:Nothing

or_else(alternative_callable, *args, **kwargs)

Call and return an alternative callable, because the Option is empty (hence or_else).

Parameters:

• alternative_callable – The function or method to call, whose result will be returned.
• args – Positional arguments to the alternative callable.
• kwargs – Keyword arguments to the alternative callable.

Tyep alternative_callable:  

S -> U

Returns:

The result of calling alternative_callable.

Return type:

U

cloak.option.nil = nil

Nothing[T] is the zero subtype for Option. It denotes the absence of a contained inner value.

Nothing exists as a singleton, called nil.

Lifting functors

cloak.option.lift_option_functor(function)

Lift a function to seamlessly operate on and return Options. After a function has been decorated by this functor, if any of the arguments passed to the function on later invocations are nil, the function call is skipped, and nil is returned. All instances of Some passed to the function as arguments are joined, and the inner value extracted to be passed as the argument in place of its parent Option; any arguments that do not inherit from Option as passed unchanged. If none of the arguments are nil, the result will be returned wrapped in a Some container.

Parameters:function (T -> S) – The function to decorate. Returns:The lifted function, with correct Option handling installed. Return type:T -> Option[S]

cloak.option.lift_exception_to_option_functor(function, target_exceptions)

Lift a function to return nil if one of a set of target exceptions is raised, or otherwise return the result inside a new Option (Some) container.

This is especially useful for converting code that originally relied on exceptions for flow control into using options, and leaving exceptions for abnormalities only. An especially poignant example of this is the get() method on Queue-like objects in Python. Under normal circumstances, the only way to check and fetch results without introducing race conditions is to use a try/except Empty/else clause over the method, each providing a different code path depending on if the queue had a message or not. By decorating the get method with this functor, and setting the target_exceptions to the set containing the Empty exception, the get() function will the message fetched from the queue wrapped in a Some container if an object was present, and nil if nothing was waiting the queue; further operation on the retrieved object can simply be mapped onto the resultant Option.

Parameters:

• function (T -> S) – The function to decorate.
• target_exceptions (set[BaseException] | list[BaseException] | tuple[BaseException]) – The set of exceptions to convert into nil instead of re-raising.

Returns:

The decorated function.

Return type:

T -> Option[S]