genmonads package

Submodules

genmonads.mlist module

class genmonads.mlist.List(*values)

Bases: genmonads.monadfilter.MonadFilter

A type that represents list of values of the same type.

Instances are either of type List[T] or Nil[T].

Monadic computing is supported with map(), flat_map(), flatten(), and filter() functions, and for-comprehensions can be formed by evaluating generators over monads with the mfor() function.

static empty()
Returns:Nil, the empty instance for this MonadFilter
Return type:List[T]
flatten()

Flattens nested instances of List.

If the inner values can be converted to an instance of List by having an implementation of to_mlist(), the inner values will be converted to List before flattening. This allows for flattening of List[Option[T]] into List[T], as is done in Scala.

Returns:the flattened monad
Return type:List[T]
head()

Returns the first item in the list.

Returns:the first item
Return type:T
Throws:
IndexError: if the list is empty
head_option()

Safely returns the first item in the list by wrapping the attempt in Option.

Returns:the first item wrapped in Some, or Nothing if the list is empty
Return type:Option[T]
last()

Returns the last item in the list.

Returns:the last item
Return type:T
Throws:
IndexError: if the list is empty
last_option()

Safely returns the last item in the list by wrapping the attempt in Option.

Returns:the first item wrapped in Some, or Nothing if the list is empty
Return type:Option[T]
map(f)

Applies a function to the inner value of an List.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting List
Return type:List[B]
mtail()

Returns the tail of the list as a monadic List.

Returns:the rest of the nel
Return type:List[T]
static pure(*values)

Injects a value into the List monad.

Parameters:*values (T) – the values
Returns:the resulting List
Return type:List[T]
tail()

Returns the tail of the list.

Returns:the tail of the list
Return type:typing.List[T]
to_list()

Converts the Option into a list.

Returns:the resulting python list
Return type:typing.List[A]
to_mlist()

Converts the Option into a List monad.

Returns:the resulting List monad
Return type:List[A]
class genmonads.mlist.Nil

Bases: genmonads.mlist.List

A type that represents the absence of an optional value.

Forms the List monad together with Some.

flatten()

Flattens nested instances of List.

If the inner values can be converted to an instance of List by having an implementation of to_mlist(), the inner values will be converted to List before flattening. This allows for flattening of List[Option[T]] into List[T], as is done in Scala.

Returns:the flattened monad
Return type:List[T]
map(f)

Applies a function to the inner value of an List.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting List
Return type:List[B]
genmonads.mlist.main()
genmonads.mlist.mlist(*values)

Constructs a List instance from a tuple of values.

Parameters:values (Tuple[T]) – the values
Returns:the resulting List
Return type:List[T]
genmonads.mlist.nil()

Constructs a Nil instance.

Returns:the resulting Nil
Return type:Nil[T]

genmonads.monad module

class genmonads.monad.Monad

Bases: object

A base class for representing monads.

Monadic computing is supported with map(), flat_map(), and flatten() functions, and for-comprehensions can be formed by evaluating generators over monads with the mfor() function.

flat_map(f)

Applies a function that produces an Monad from unwrapped values to an Monad’s inner value and flattens the nested result.

Equivalent to self.map(f).flatten().

Parameters:f (Callable[[A],Monad[B]]) – the function to apply
Returns:the resulting monad
Return type:Monad[B]
flatten()

Flattens nested instances of Monad.

Returns:the flattened monad
Return type:Monad[T]
map(f)

Applies a function to the inner value of a monad.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting monad
Return type:Monad[B]
static pure(value)

Injects a value into the monad.

Parameters:value (T) – the value
Returns:the monadic value
Return type:Monad[T]
class genmonads.monad.MonadIter(monad)

Bases: object

An iterator wrapper class over the content of the monad to support usage in generators

next()
genmonads.monad.do(gen, frame_depth=5)

A synonym for mfor.

Evaluates a generator over a monadic value, translating it into the equivalent for-comprehension.

Parameters:
  • gen (Generator[T, None, None]) – a generator over a monadic value
  • frame_depth (int) – the frame depth of which to search for the outermost monad
Returns:

the for-comprehension that corresponds to the generator
Return type:

Monad[T]
genmonads.monad.mfor(gen, frame_depth=5)

The monadic for-comprehension Evaluates a generator over a monadic value, translating it into the equivalent for-comprehension.

Parameters:
  • gen (Generator[T, None, None]) – a generator over a monadic value
  • frame_depth (int) – the frame depth of which to search for the outermost monad
Returns:

the for-comprehension that corresponds to the generator
Return type:

Monad[T]

genmonads.monadfilter module

class genmonads.monadfilter.MonadFilter

Bases: genmonads.monad.Monad

A base class for monads that can implement a filter() function.

The monad must define an empty instance of the monad that is returned when filter() fails and represents a False value for the monad.

static empty()
Returns:the empty instance for this monad
Return type:MonadFilter[T]
exists(f)

Checks if the predicate is True for any of this monad’s inner values .

Parameters:f (Callable[[T],bool]) – the predicate
Returns:True if the predicate is True for any of this monad’s inner values
Return type:bool
filter(f)

Filters this monad by applying the predicate f to the monad’s inner value. Returns this monad if the predicate is True, this monad’s empty instance otherwise.

Parameters:f (Callable[[T],bool]) – the predicate
Returns:this instance if the predicate is True when applied to its inner value, otherwise the monad’s empty instance
Return type:MonadFilter[T]

genmonads.monadtrans module

class genmonads.monadtrans.MonadTranslator(translator, tree)

Bases: pony.orm.asttranslation.PythonTranslator

The translator class that converts the AST of a generator over monads into a series of nested calls to flat_map(), map(), and filter().

For example, consider the following generator:

>>> from genmonads.Option import *
>>> print(mfor(x + y
          for x in option(2)
          if x < 10
          for y in option(5)
          if y % 2 != 0))
Some(7)

The above generator is automatically translated into the following at run-time:

>>> print(option(2)
              .filter(lambda x: x < 10)
              .flat_map(lambda x: option(5)
                  .filter(lambda y: y % 2 != 0)
                  .map(lambda y: x + y)))
Some(7)
postGenExpr(node)

Converts the AST node for the full generator expression into its code representation.

Responsible for discarding the parentheses around the generator expression.

Parameters:node (GenExpr) – the AST node
Returns:the source code representation
Return type:str
postGenExprFor(node)

Converts the AST node for the body of a generator’s for statements into its code representation.

Responsible for converting if statements into calls to filter and for x in y in to calls to flat_map.

Parameters:node (GenExprFor) – the AST node
Returns:the source code representation
Return type:str
postGenExprInner(node)

Converts the AST node for the generator’s inner expression into its code representation.

Responsible for converting the final flat_map call into a call to map and adding closing parentheses.

Parameters:node (GenExprInner) – the AST node
Returns:the source code representation
Return type:str
postLambda(node)

Converts the AST node for a lambda expression into its code representation

Parameters:node (Lambda) – the AST node
Returns:the source code representation
Return type:str
genmonads.monadtrans.ast2src(tree)

Converts an AST into python source, replacing generator expressions into a series of nested calls to flat_map, map, and filter by applying the MonadTranslator to an AST.

Parameters:tree (GenExpr) – the AST node of a generator expression
Returns:the source code representation
Return type:str

genmonads.mtry module

class genmonads.mtry.Failure(ex)

Bases: genmonads.mtry.Try

flatten()

Flattens nested instances of Try.

Returns:the flattened monad
Return type:Try[T]
get()

Returns the Try‘s inner value.

Returns:the inner value
Return type:Union[T,Exception]
get_or_else(default)

Returns the Try‘s inner value if an instance of Success or default if instance of Failure.

Parameters:default – the value to return for Failure[T] instances
Returns:the Try‘s inner value if an instance of Success or default if instance of Failure
Return type:T
map(f)

Applies a function to the inner value of a Try.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Try
Return type:Try[B]
or_else(default)

Returns the Try if an instance of Success or default if an instance of Failure .

Parameters:default (Try[B]) – the monad to return for Failure[T] instances
Returns:the resulting Try
Return type:Try[B]
raise_ex()

Raises this Failure instance’s exception.

Raises:Exception – the exception
recover(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a map on the Failure instance.

Parameters:f (Callable[[Exception],B) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
recover_with(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a flat_map on the Failure instance.

Parameters:f (Callable[[Exception],Try[B]) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
to_option()

Converts an instance of Try[T] to Option[T].

Success[T] is mapped to Some[T], and Failure[T] is mapped to Nothing[T].

Returns:the corresponding Option
Return type:Option[T]
class genmonads.mtry.Success(result)

Bases: genmonads.mtry.Try

flatten()

Flattens nested instances of Try.

Returns:Try[T]
get()

Returns the Try‘s inner value.

Returns:the inner value
Return type:Union[T,Exception]
get_or_else(default)

Returns the Try‘s inner value if an instance of Success or default if instance of Failure[T].

Parameters:default – the value to return for Failure instances
Returns:the Try‘s inner value if an instance of Success or default if instance of Failure[T]
Return type:T
map(f)

Applies a function to the inner value of a Try.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Try
Return type:Try[B]
or_else(default)

Returns the Try if an instance of Success or default if an instance of Failure .

Parameters:default (Try[B]) – the monad to return for Failure[T] instances
Returns:the resulting Try
Return type:Try[B]
static pure(result)

Injects a result into the Success monad.

Parameters:result (T) – the result
Returns:the resulting Try
Return type:Try[T]
recover(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a map on the Failure instance.

Parameters:f (Callable[[Exception],B) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
recover_with(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a flat_map on the Failure instance.

Parameters:f (Callable[[Exception],Try[B]) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
to_option()

Converts an instance of Try[T] to Option[T].

Success[T] is mapped to Some[T], and Failure[T] is mapped to Nothing[T].

Returns:the corresponding Option
Return type:Option[T]
class genmonads.mtry.Try(*args, **kwargs)

Bases: genmonads.monadfilter.MonadFilter

A type that represents a failable computation.

Instances of type Try[T] are either instances of Success[T] or Failure[T]. This monad uses eager evaluation. For lazy computations, see the Task monad (under construction).

Instances of Try[T] are constructed by passing a computation wrapped in a thunk (i.e. a lambda expression with no arguments) to either the mtry() or Try.pure() or functions. The thunk is evaluated immediately, and successful computations return the result wrapped in Success, while computations that raise an exception return that exception wrapped in Failure[T].

Monadic computing is supported with map, flat_map(), flatten(), and filter() functions, and for-comprehensions can be formed by evaluating generators over monads with the mfor() function.

static empty()
Returns:Failure[T] with a ValueError, the empty instance for this MonadFilter
Return type:Try[T]
flatten()

Flattens nested instances of Try.

Returns:the flattened monad
Return type:Try[T]
get()

Returns the Try’s inner value.

Returns:the inner value
Return type:Union[T,Exception]
get_or_else(default)

Returns the Try‘s inner value if an instance of Success or default if instance of Failure.

Parameters:default – the value to return for Failure[T] instances
Returns:the Try‘s inner value if an instance of Success or default if instance of Failure
Return type:T
map(f)

Applies a function to the inner value of a Try.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Try
Return type:Try[B]
or_else(default)

Returns the Try if an instance of Success or default if an instance of Failure .

Parameters:default (Try[B]) – the monad to return for Failure[T] instances
Returns:the resulting Try
Return type:Try[B]
static pure(thunk)

Evaluates a failable computation in the Try monad.

This function should be used instead of calling Try.__init__() directly.

Parameters:thunk (Callable[[None],T]) – the computation
Returns:the resulting Try
Return type:Try[T]
recover(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a map on the Failure instance.

Parameters:f (Callable[[Exception],B) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
recover_with(f)

Recovers from a failed computation by applying f to the exception.

Essentially, a flat_map on the Failure instance.

Parameters:f (Callable[[Exception],Try[B]) – the function to call on the Failure[T]‘s exception
Returns:the resulting Try
Return type:Try[B]
to_option()

Converts an instance of Try[T] to Option[T].

Success[T] is mapped to Some[T], and Failure[T] is mapped to Nothing[T].

Returns:the corresponding Option
Return type:Option[T]
genmonads.mtry.failure(ex)

Injects an exception into the Failure monad.

Parameters:ex (Exception) – the exception
Returns:the resulting Failure
Return type:Failure[T]
genmonads.mtry.main()
genmonads.mtry.mtry(thunk)

Evaluates a delayed computation in the Try monad.

Parameters:thunk (Callable[[None],T]) – the delayed computation
Returns:the resulting Try
Return type:Try[T]
genmonads.mtry.success(result)

Injects a value into the Success monad.

Parameters:result (T) – the result
Returns:the resulting monad
Return type:Try[T]

genmonads.nel module

class genmonads.nel.NonEmptyList(*values)

Bases: genmonads.monad.Monad

A type that represents a non-empty list of a single type.

Monadic computing is supported with map(), flat_map(), flatten(), and filter() functions, and for-comprehensions can be formed by evaluating generators over monads with the mfor() function.

filter(f)

Filters this monad by applying the predicate f to the monad’s inner value. Returns this monad if the predicate is True, this monad’s empty instance otherwise.

Parameters:f (Callable[[T],bool]) – the predicate
Returns:a list containing all inner values where the predicate is True
Return type:List[T]
flatten()

Flattens nested instances of NonEmptyList.

If the inner values can be converted to an instance of NonEmptyList by having an implementation of to_nel(), the inner values will be converted to NonEmptyList before flattening.

Returns:the flattened monad
Return type:NonEmptyList[T]
head()

Returns the first item in the nel.

Returns:the first item
Return type:T
last()

Returns the last item in the nel.

Returns:the last item
Return type:T
map(f)

Applies a function to the inner value of a nel.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting NonEmptyList
Return type:NonEmptyList[B]
mtail()

Returns the tail of the nel as a monadic List.

Returns:the rest of the nel
Return type:List[T]
static pure(*values)

Injects a value into the NonEmptyList monad.

Parameters:*values (T) – the values
Returns:the resulting NonEmptyList
Return type:NonEmptyList[T]
tail()

Returns the tail of the nel.

Returns:the tail of the nel
Return type:typing.List[T]
to_list()

Converts the NonEmptyList into a list.

Returns:the resulting python list
Return type:typing.List[T]
to_mlist()

Converts the NonEmptyList into a List monad.

Returns:the resulting List monad
Return type:List[T]
to_nel()

Converts the NonEmptyList into a NonEmptyList.

Returns:the resulting nel
Return type:NonEmptyList[T]
genmonads.nel.main()
genmonads.nel.nel(*values)

Constructs a NonEmptyList instance from a tuple of values.

Parameters:values (Tuple[T]) – the values
Returns:the resulting NonEmptyList
Return type:NonEmptyList[T]

genmonads.option module

class genmonads.option.Nothing

Bases: genmonads.option.Option

A type that represents the absence of an optional value.

Forms the Option monad together with Some.

flatten()

Flattens nested instances of Option.

Returns:the flattened monad
Return type:Option[T]
get()

Returns the Option‘s inner value. Raises a ValueError for instances of Nothing.

Returns:the inner value
Return type:T
get_or_else(default)

Returns the Option‘s inner value if an instance of Some or default if instance of Nothing.

Parameters:default – the value to return for Nothing[T] instances
Returns:the Option‘s inner value if an instance of Some or default if instance of Nothing
Return type:T
get_or_none()

Returns the Option‘s inner value if an instance of Some or None if instance of Nothing.

Provided as interface to code that expects None values.

Returns:the Option‘s inner value if an instance of Some or None if instance of Nothing
Return type:Union[T,None]
map(f)

Applies a function to the inner value of an Option.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Option
Return type:Option[B]
to_list()

Converts the Option into a list.

Returns:the resulting python list
Return type:typing.List[A]
to_mlist()

Converts the Option into a List monad.

Returns:the resulting List monad
Return type:List[A]
class genmonads.option.Option(*args, **kwargs)

Bases: genmonads.monadfilter.MonadFilter

A type that represents an optional value.

Instances of type Option[T] are either an instance of Some[T] or Nothing[T].

Monadic computing is supported with map(), flat_map(), flatten(), and filter() functions, and for-comprehensions can be formed by evaluating generators over monads with the mfor() function.

static empty()
Returns:Nothing, the empty instance for this MonadFilter
Return type:Option[T]
flatten()

Flattens nested instances of Option.

Returns:the flattened monad
Return type:Option[T]
get()

Returns the Option‘s inner value. Raises a ValueError for instances of Nothing[T].

Returns:the inner value
Return type:T
get_or_else(default)

Returns the Option‘s inner value if an instance of Some or default if instance of Nothing.

Parameters:default (T) – the value to return for Nothing[T] instances
Returns:the Option‘s inner value if an instance of Some or default if instance of Nothing
Return type:T
get_or_none()

Returns the Option‘s inner value if an instance of Some or None if instance of Nothing.

Provided as interface to code that expects None values.

Returns:the Option‘s inner value if an instance of Some or None if instance of Nothing
Return type:Union[T,None]
map(f)

Applies a function to the inner value of an Option.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Option
Return type:Option[B]
static pure(value)

Injects a value into the Option monad.

This function should be used instead of calling Option.__init__() directly.

Parameters:value (T) – the value
Returns:the resulting Option
Return type:Option[T]
to_list()

Converts the Option into a list.

Returns:the resulting python list
Return type:typing.List[A]
to_mlist()

Converts the Option into a List monad.

Returns:the resulting List monad
Return type:List[A]
class genmonads.option.Some(value)

Bases: genmonads.option.Option

A type that represents the presence of an optional value.

Forms the Option monad together with Nothing[T].

flatten()

Flattens nested instances of Option.

Returns:the flattened monad
Return type:Option[T]
get()

Returns the Option‘s inner value. Raises a ValueError for instances of Nothing[T].

Returns:the inner value
Return type:T
get_or_else(default)

Returns the Option‘s inner value if an instance of Some or default if instance of Nothing.

Parameters:default – the value to return for Nothing[T] instances
Returns:the Option‘s inner value if an instance of Some or default if instance of Nothing
Return type:T
get_or_none()

Returns the Option‘s inner value if an instance of Some or None if instance of Nothing.

Provided as interface to code that expects None values.

Returns:the Option‘s inner value if an instance of Some or None if instance of Nothing
Return type:Union[T,None]
map(f)

Applies a function to the inner value of an Option.

Parameters:f (Callable[[A],B]) – the function to apply
Returns:the resulting Option
Return type:Option[B]
to_list()

Converts the Option into a list.

Returns:the resulting python list
Return type:typing.List[A]
to_mlist()

Converts the Option into a List monad.

Returns:the resulting List monad
Return type:List[A]
genmonads.option.main()
genmonads.option.nothing()

Constructs a Nothing instance.

Returns:the resulting Nothing
Return type:Nothing[T]
genmonads.option.option(value)

Constructs an Option instance from a value.

This function converts None into an instance of Nothing[T]. If this behavior is undesired, use Option.pure() instead.

Parameters:value (T) – the value
Returns:the resulting Option
Return type:Option[T]
genmonads.option.some(value)

Constructs a Some instance from value.

Parameters:value (T) – the value
Returns:the resulting Some
Return type:Some[T]

Module contents