pymonad

#+options: author:nil

PyMonad implements data structures typically available in pure
functional or functional first programming languages like Haskell and
F#. Included are Monad and Monoid data types with several common
monads included - such as Maybe and State - as well as some useful
tools such as the @curry decorator for defining curried
functions. PyMonad 2.0.x represents and almost complete re-write of
the library with a simpler, more consistent interface as well as type
annotations to help ensure correct usage.

** Getting Started

These instructions will get you a copy of the project up and running
on your local machine for development and testing purposes.

*** Prerequisites
PyMonad requires Python 3.7+. If installing via =pip= then you
will also need [[https://pypi.org/project/pip/][Pip]] and [[https://pypi.org/project/wheel/][Wheel]] installed. See those projects for
more information on installing them if necessary.

Potential contributors should additionally install [[https://pypi.org/project/pylint/][pylint]] and
[[https://pypi.org/project/pytype/][pytype]] to ensure their code adheres to common style conventions.

*** Installing
**** From the Python Package Index (PyPI) with pip
From a command line run:
#+begin_src bash
pip install PyMonad
#+end_src

**** Manual Build from PyPI
Download the project files from
https://pypi.org/project/PyMonad/#files and from the project
directory run:

 #+begin_src bash
   python setup.py install
 #+end_src
 
 If that doesn't work you may need to run the following instead.

 #+begin_src bash
   python3 setup.py install
 #+end_src

**** From github
Clone the project repository:

 #+begin_src bash
   git clone https://github.com/jasondelaat/pymonad.git
 #+end_src
 
 Then from the project directory run =setup.py= as for the manual
 build instructions above.

**** Example Usage
The following example imports the =tools= module and uses the
=curry= function to define a curried addition function.

 #+begin_src python
   import pymonad.tools

   @pymonad.tools.curry(2) # Pass the expected number of arguments to the curry function.
   def add(x, y):
   return x + y

   # We can call add with all of it's arguments...
   print(add(2, 3)) # Prints '5'

   # ...or only some of them.
   add2 = add(2)  # Creates a new function expecting a single arguments
   print(add2(3)) # Also prints '5'
 #+end_src

**** Next Steps

 The PyMonad documentation is a work in progress. For tutorials,
 how-to, and more head over to the [[https://jasondelaat.github.io/pymonad_docs/][PyMonad Documentation Project]].
 If you'd like to contribute visit the documentation repository
 [[https://github.com/jasondelaat/pymonad_docs][here]].

*** Upgrading from PyMonad 1.3
If you’ve used the 1.x versions of PyMonad you’ll notice that
there are a few differences:

**** Curried functions
Currying functions in PyMonad version 1.x wrapped a function in
an instance of the Reader monad. This is no longer the case and
currying simply produces a new function as one might expect.

 The signature of ~curry~ has changed slightly. The new ~curry~
 takes two arguments: the number of arguments which need to be
 curried and the function.
 
 #+begin_src python
   from pymonad.tools import curry

   def add(x, y):
       return x + y

   curried_add = curry(2, add)
   # add = curry(2, add) # If you don't need access to the uncurried version.
 #+end_src
 
 ~curry~ is itself a curried function so it can be used more
 concisely as a decorator.

 #+begin_src python
   from pymonad.tools import curry

   @curry(2)
   def add(x, y):
       return x + y
 #+end_src

**** Operators
Version 2 of PyMonad discourages the use of operators (>>, *, and
&) used in version 1 so old code which uses them will
break. Operators have been removed from the default monad
implementation but are still available for users that still wish
to use them in the _operators package. To use operators:

 #+begin_src python
   # Instead of this:
   # import pymonad.maybe

   # Do this:
   import pymonad.operators.maybe
 #+end_src
 
 While it's unlikely operators will be removed entirely, it is
 strongly suggested that users write code that doesn't require
 them.

**** Renamed Methods
The _fmap method has been renamed to simply _map and _unit is now called _insert.

 #+begin_src python
   from pymonad.maybe import Maybe

   def add2(x):
       return x + 2

   m = (Maybe.insert(1)
        .map(add2)
   )

   print(m) # Just 3
 #+end_src

**** Applicative Syntax
Previously applicative syntax used the _& operator or the _amap
method. _amap still exists but there’s now another way to use
applicatives: _{apply().to_arguments()}

 #+begin_src python
   from pymonad.tools import curry
   from pymonad.maybe import Maybe, Just

   @curry(2)
   def add(x, y):
       return x + y

   a = Just(1)
   b = Just(2)

   c  = Maybe.apply(add).to_arguments(a, b)
   print(c) # Just 3
 #+end_src
 
 If the function passed to ~apply~ accepts multiple arguments then
 it /must/ be a curried function.

**** New _then method
The _then method combines the functionality of both _map and
_bind. It first tries to _bind the function passed to it and,
if that doesn’t work, tries _map instead. It will be slightly
less efficient than using _map and _bind directly but frees
users from having to worry about specifically which functions are
being used where.

 #+begin_src python
   from pymonad.tools import curry
   from pymonad.maybe import Maybe, Just, Nothing

   @curry(2)
   def add(x, y):
       return x + y

   @curry(2)
   def div(y, x):
       if y == 0:
           return Nothing
       else:
           return Just(x / y)

   m = (Maybe.insert(2)
        .then(add(2)) # Uses map
        .then(div(4)) # Uses bind
   )

   print(m) # Just 1.0
 #+end_src

**** Getting values out of _Maybe and _Either
Previously, if you need to get a value out of a _Maybe or an
_Either after a series of calculations you would have to access
the _.value property directly. By the very nature of these two
monads, _.value may not contain valid data and checking whether
the data is valid or not is the problem these monads are supposed
to solve. As of PyMonad 2.3.0 there are methods – _maybe and
_either – for properly extracting values from these
monads.

 Given a ~Maybe~ value ~m~, the ~maybe~ method takes a default
 value, which will be returned if ~m~ is ~Nothing~, and a function
 which will be applied to the value inside of a ~Just~.
 
 #+begin_src python
   from pymonad.maybe import Just, Nothing

   a = Just(2)
   b = Nothing

   print(a.maybe(0, lambda x: x)) # 2
   print(b.maybe(0, lambda x: x)) # 0
 #+end_src
 
 The ~either~ method works essentially the same way but takes two
 functions as arguments. The first is applied if the value is a
 ~Left~ value and the second if it's a ~Right~.

 #+begin_src python
   from pymonad.either import Left, Right

   a = Right(2)
   b = Left('Invalid')

   print(a.either(lambda x: f'Sorry, {x}', lambda x: x)) # 2
   print(b.either(lambda x: f'Sorry, {x}', lambda x: x)) # Sorry, Invalid
 #+end_src

*** Note on efficiency in versions <2.3.5
In pymonad versions 2.3.4 and earlier, an error in the
implementation of _then, detailed [[https://github.com/jasondelaat/pymonad/issues/14][here]], meant that some monad
types executed _then with exponential complexity. As of version
2.3.5 this has been corrected. All monad types now execute _then
in linear time. A similar problem occured with the _map and
_bind methods for the State monad which have also been fixed in
2.3.5

If you're using an earlier version of pymonad upgrading to 2.3.5
is highly recommended.

** Running the tests
*** Unit Tests
These tests primarily ensure that the defined monads and monoids
obey the required mathematical laws.

On most *nix systems you should be able to run the automated tests
by typing the following at the command line.

#+begin_src bash
 ./run_tests.sh
#+end_src

However, =run_tests.sh= is just a convenience. If the above doesn't
work the following should:

#+begin_src bash
 python3 -m unittest discover test/
#+end_src

*** Style Tests
Contributors only need to run =pylint= and =pytype= over their
code and ensure that there are no glaring style or type
errors. PyMonad (mostly) attempts to adhere to the [[https://google.github.io/styleguide/pyguide.html][Google Python Style Guide]]
and includes type hinting according to [[https://www.python.org/dev/peps/pep-0484/][PEP 484]].

In general, don't disable =pylint= or =pytype= errors for the
whole project, instead disable them via comments in the code. See
the existing code for examples of errors which can be disabled.

** Authors
Jason DeLaat - /Primary Author/Maintainer/ - https://github.com/jasondelaat/pymonad
** License
This project is licensed under the 3-Clause BSD License. See
[[./LICENSE.rst][LICENSE.rst]] for details.