Actions¶

monad.actions - useful monadic actions.

monad.actions.either(left_handler, right_handler=identity)[source]¶

Case analysis for Either.

Returns a function that when called with a value of type Either, applies either left_handler or right_handler to that value depending on the type of it. If an incompatible value is passed, a TypeError will be raised.

>>> def log(v):
...     print('Got Left({})'.format(v))
>>> logger = either(left_handler=log)
>>> logger(Left(1))
Got Left(1)
>>> logger(Right(1))
1
>>> def inc(v):
...     return v + 1
>>> act = either(log, inc)
>>> [act(v) for v in (Left(0), Right(1), Left(2), Right(3))]
Got Left(0)
Got Left(2)
[None, 2, None, 4]

monad.actions.first(sequence, default=Nothing, predicate=None)[source]¶

Iterate over a sequence, return the first Just.

If predicate is provided, first returns the first item that satisfy the predicate, the item will be wrapped in a Just if it is not already, so that the return value of this function will be an instance of Maybe in all circumstances. Returns default if no satisfied value in the sequence, default defaults to Nothing.

>>> from monad.types import Just, Nothing
>>> first([Nothing, Nothing, Just(42), Nothing])
Just(42)
>>> first([Just(42), Just(43)])
Just(42)
>>> first([Nothing, Nothing, Nothing])
Nothing
>>> first([])
Nothing
>>> first([Nothing, Nothing], default=Just(2))
Just(2)
>>> first([False, 0, True], predicate=bool)
Just(True)
>>> first([False, 0, Just(1)], predicate=bool)
Just(1)
>>> first([False, 0, ''], predicate=bool)
Nothing
>>> first(range(100), predicate=lambda x: x > 40 and x % 2 == 0)
Just(42)
>>> first(range(100), predicate=lambda x: x > 100)
Nothing

This is basically a customized version of msum for Maybe, a separate function like this is needed because there is no way to write a generic msum in python that cab be evaluated in a non-strict way. The obvious reduce(operator.add, sequence), albeit beautiful, is strict, unless we build up the sequence with generator expressions in-place.

Maybe (pun intended!) implemented as MonadOr instead of MonadPlus might be more semantically correct in this case.

monad.actions.tryout(*functions)[source]¶

Combine functions into one.

Returns a monadic function that when called, will try out functions in functions one by one in order, testing the result, stop and return with the first value that is true or the last result.

>>> zero = lambda n: 'zero' if n == 0 else False
>>> odd = lambda n: 'odd' if n % 2 else False
>>> even = lambda n: 'even' if n % 2 == 0 else False
>>> test = tryout(zero, odd, even)
>>> test(0)
'zero'
>>> test(1)
'odd'
>>> test(2)
'even'

Decorators¶

monad.decorators - helpful decorators.

monad.decorators.failsafe(callable_object=None, predicate=None, left_on_value=Null, left_on_exception=<type 'exceptions.Exception'>)[source]¶

Transform a callable into a function returns an Either.

>>> parse_int = failsafe(int)
>>> parse_int(42)
Right(42)
>>> parse_int(42.0)
Right(42)
>>> parse_int('42')
Right(42)
>>> parse_int('invalid')
Left(ValueError(...))

>>> parse_pos = failsafe(int, predicate=lambda i: i > 0)
>>> parse_pos('42')
Right(42)
>>> parse_pos('-42')
Left(-42)

>>> parse_nonzero = failsafe(int, left_on_value=0)
>>> parse_nonzero('42')
Right(42)
>>> parse_nonzero('0')
Left(0)

>>> @failsafe(left_on_exception=ZeroDivisionError)
... def safe_div(a, b):
...     return a / b
>>> safe_div(42.0, 2)
Right(21.0)
>>> safe_div(42, 0)
Left(ZeroDivisionError(...))

When invoked, this new function returns the return value of decorated function, wrapped in an Either monad.

predicate should be a false value, or be set to a callable. The default is None.

left_on_value can be set to any object supporting comparison against return value of the original function. The default is Null, which means no checking on the return value.

left_on_exception should be a false value, or a type of exception, or a tuple of exceptions. The default is Exception, which will suppress most exceptions and return Left(exception) instead.

The returned monad will be Left if

• predicate is set, and predicate(result_from_decorated_function) returns true value (not necessarily equal to True)
• left_on_value is set and the result from decorated function matches it, testing with ==
• left_on_exception is set and a compatible exception has been caught, the exception will be suppressed in this case, and the value of exception will be wrapped in a Left
• exception ExtractError has been caught, this could be the case, for example, trying to extract value from Nothing
• any combination of the above

Otherwise, the result will be wrapped in a Right.

monad.decorators.function(callable_object)[source]¶

Decorator that wraps a callabe into Function.

>>> to_int = function(int)
>>> to_int('42')
42
>>> @function
... def puts(msg, times=1):
...     while times > 0:
...         print(msg)
...         times -= 1
>>> puts('Hello, world', 2)
Hello, world
Hello, world

monad.decorators.maybe(callable_object=None, predicate=None, nothing_on_value=Null, nothing_on_exception=<type 'exceptions.Exception'>)[source]¶

Transform a callable into a function returns a Maybe.

>>> parse_int = maybe(int)
>>> parse_int(42)
Just(42)
>>> parse_int(42.0)
Just(42)
>>> parse_int('42')
Just(42)
>>> parse_int('invalid')
Nothing

>>> parse_pos = maybe(int, predicate=lambda i: i > 0)
>>> parse_pos('42')
Just(42)
>>> parse_pos('-42')
Nothing

>>> parse_nonzero = maybe(int, nothing_on_value=0)
>>> parse_nonzero('42')
Just(42)
>>> parse_nonzero('0')
Nothing

>>> @maybe(nothing_on_exception=ZeroDivisionError)
... def safe_div(a, b):
...     return a / b
>>> safe_div(42.0, 2)
Just(21.0)
>>> safe_div(42, 0)
Nothing

When invoked, this new function returns the return value of decorated function, wrapped in a Maybe monad.

predicate should be a false value, or be set to a callable. The default is None.

nothing_on_value can be set to any object supporting comparison against return value of the original function. The default is Null, which means no checking on the return value.

nothing_on_exception can be a false value, a type of exception, or a tuple of exceptions. The default is Exception, which will suppress most exceptions and return Nothing instead.

The returned monad will be Nothing if

• predicate is set, and predicate(result_from_decorated_function) returns true value (not necessarily equal to True)
• nothing_on_value is set and the result from decorated function matches it, testing with ==
• nothing_on_exception is set and a compatible exception has been caught, the exception will be suppressed in this case
• exception ExtractError has been caught, when trying to extract value from Nothing
• any combination of the above

Otherwise, the result will be wrapped in a Just.

monad.decorators.monadic(callable_object)[source]¶

Decorator that wraps a callabe into Monadic.

monad.decorators.producer(function_or_generator=None, empty_on_exception=None)[source]¶

Transform a callable into a producer that when called, returns List.

>>> @producer
... def double(a):
...     yield a
...     yield a
>>> List(42) >> double
List(42, 42)

>>> @producer
... def times(a):
...     for b in List(1, 2, 3):
...         yield '{}x{}={}'.format(a, b, a * b)
>>> List(1, 2) >> times
List('1x1=1', '1x2=2', '1x3=3', '2x1=2', '2x2=4', '2x3=6')

function_or_generator can be a function that returns an iterable, or a generator.

empty_on_exception can be a false value, a type of exception, or a tuple of exceptions. The default is None, which will not suppress all exceptions except ExtractError, in which case, an empty List will be returned.

Exceptions¶

monad.exceptions - custom exceptions.

exception monad.exceptions.ExtractError(monad)[source]¶

Bases: exceptions.Exception

Raised when failed to extract value from monad.

Common Mixin Classes¶

monad.mixins - implements common mixin classes.

class monad.mixins.ContextManager[source]¶

Bases: object

Mixin class that support with statement for monad.

class monad.mixins.Ord[source]¶

Bases: object

Mixin class that implements rich comparison ordering methods.

Types¶

Utility Functions¶

monad.utils - utility functions and values.

class monad.utils.SuppressContextManager(*exceptions)[source]¶

Bases: object

Context manager class that suppress specified exceptions.

monad.utils.compose(f, g)[source]¶

Function composition.

compose(f, g) -> f . g

>>> add_2 = lambda a: a + 2
>>> mul_5 = lambda a: a * 5
>>> mul_5_add_2 = compose(add_2, mul_5)
>>> mul_5_add_2(1)
7
>>> add_2_mul_5 = compose(mul_5, add_2)
>>> add_2_mul_5(1)
15

monad.utils.identity(a)[source]¶

Identity function.

monad.utils.ignore_exception_set(*exceptions)[source]¶

Helper function for suppress.

monad.utils.suppress(*exceptions)[source]¶

Context manager that suppress specified exceptions.

>>> with suppress(ZeroDivisionError):
...     42 / 0