phi 0.6.7
Phi is a library for fluent functional programming in Python which includes a DSL + facilities to create libraries that integrate with it.
License: MIT
Keywords: functional programming

# Phi
Phi library for functional programming in Python that intends to remove as much of the pain as possible from your functional programming experience in Python.

## Import
For demonstration purposes we will import right now everything we will need for the rest of the exercises like this
```python
from phi.api import *
```
but you can also import just what you need from the `phi` module.

## Math-like Lambdas

#### Operators

Using the `P` object you can create quick lambdas using any operator. You can write things like

```python
f = (P * 6) / (P + 2)  #lambda x: (x * 6) / (x + 2)

assert f(2) == 3  # (2 * 6) / (2 + 2) == 12 / 4 == 3
```

where the expression for `f` is equivalent to

```python
f = lambda x: (x * 6) / (x + 2)
```

#### getitem
You can also use the `P` object to create lambdas that access the items of a collection
```python
f = P[0] + P[-1]  #lambda x: x[0] + x[-1]

assert f([1,2,3,4]) == 5   #1 + 4 == 5
```

#### field access
If you want create lambdas that access the field of some entity you can use the `Rec` (for Record) object an call that field on it
```python
from collections import namedtuple
Point = namedtuple('Point', ['x', 'y'])

f = Rec.x + Rec.y  #lambda p: p.x + p.y

assert f(Point(3, 4)) == 7   #point.x + point.y == 3 + 4 == 7
```
#### method calling
If you want to create a lambda that calls the method of an object you use the `Obj` object and call that method on it with the parameters
```python
f = Obj.upper() + ", " + Obj.lower()  #lambda s: s.upper() + ", " + s.lower()

assert f("HEllo") == "HELLO, hello"   # "HEllo".upper() + ", " + "HEllo".lower() == "HELLO" + ", " + "hello" == "HELLO, hello"
```
Here no parameters were needed but in general
```python
f = Obj.some_method(arg1, arg2, ...) #lambda obj: obj.some_method(arg1, arg2, ...)
```
is equivalent to
```python
f = lambda obj: obj.some_method(arg1, arg2, ...)
```
## Composition
#### >> and <<
You can use the `>>` operator to *forward* compose expressions

```python
f = P + 7 >> math.sqrt  #executes left to right

assert f(2) == 3  # math.sqrt(2 + 7) == math.sqrt(9) == 3
```
This is preferred because it is more readable, but you can use the `<<` to compose them *backwards* just like the mathematical definition of function composition

```python
f =  math.sqrt << P + 7 #executes right to left

assert f(2) == 3  # math.sqrt(2 + 7) == math.sqrt(9) == 3
```

#### Seq and Pipe
If you need to do a long or complex composition you can use `Seq` (for 'Sequence') instead of many chained `>>`

```python
f = Seq(
  str,
  P + "00",
  int,
  math.sqrt
)

assert f(1) == 10  # sqrt(int("1" + "00")) == sqrt(100) == 10
```
If you want to create a composition and directly apply it to an initial value you can use `Pipe`

```python
assert 10 == Pipe(
  1,  #input
  str,  # "1"
  P + "00",  # "1" + "00" == "100"
  int,  # 100
  math.sqrt  #sqrt(100) == 10
)
```

## Combinators
#### List, Tuple, Set, Dict
There are a couple of combinators like `List`, `Tuple`, `Set`, `Dict` that help you create compound functions that return the container types `list`, `tuple`, `set` and `dict` respectively. For example, you can pass `List` a couple of expressions to get a function that returns a list with the values of these functions

```python
f = List( P + 1, P * 10 )  #lambda x: [ x +1, x * 10 ]

assert f(3) == [ 4, 30 ]  # [ 3 + 1, 3 * 10 ] == [ 4, 30 ]
```
The same logic applies for `Tuple` and `Set`. With `Dict` you have to use keyword arguments

```python
f = Dict( x = P + 1, y = P * 10 )  #lambda x: [ x +1, x * 10 ]

d = f(3)

assert d == { 'x': 4, 'y': 30 }  # { 'x': 3 + 1, 'y': 3 * 10 } == { 'x': 4, 'y': 30 }
assert d.x == 4   #access d['x'] via field access as d.x
assert d.y == 30  #access d['y'] via field access as d.y
```
As you see, `Dict` returns a custom `dict` that also allows *field access*, this is useful because you can use it in combination with `Rec`.

#### State: Read and Write
Internally all these expressions are implemented in such a way that they not only pass their computed values but also pass a **state** dictionary between them in a functional manner. By reading from and writing to this state dictionary the `Read` and `Write` combinators can help you "save" the state of intermediate computations to read them later

```python
assert [70, 30] == Pipe(
  3,
  Write(s = P * 10),  #s = 3 * 10 == 30
  P + 5,  #30 + 5 == 35
  List(
    P * 2  # 35 * 2 == 70
  ,
    Read('s')  #s == 30
  )
)
```
If you need to perform many reads inside a list -usually for output- you can use `ReadList` instead
```python
assert [2, 4, 22] == Pipe(
    1,
    Write(a = P + 1),  #a = 1 + 1 == 2
    Write(b = P * 2),  #b = 2 * 2 == 4
    P * 5,   # 4 * 5 == 20
    ReadList('a', 'b', P + 2)  # [a, b, 20 + 2] == [2, 4, 22]
)
```
`ReadList` interprets string elements as `Read`s, so the previous is translated to
```python
List(Read('a'), Read('b'), P + 2)
```

#### Then, Then2, ..., Then5, ThenAt
To create a partial expression from a function e.g.
```python
def repeat_word(word, times, upper=False):
  if upper:
    word = word.upper()

  return [ word ] * times
```
use the `Then` combinator which accepts a function plus all but the *1st* of its `*args` + `**kwargs`
```python
f = P[::-1] >> Then(repeat_word, 3)
g = P[::-1] >> Then(repeat_word, 3, upper=True)

assert f("ward") == ["draw", "draw", "draw"]
assert g("ward") == ["DRAW", "DRAW", "DRAW"]
```
and assumes that the *1st* argument of the function will be applied last, e.g. `word` in the case of `repeat_word`. If you need the *2nd* argument to be applied last use `Then2`, and so on. In general you can use `ThenAt(n, f, *args, **kwargs)` where `n` is the position of the argument that will be applied last. Example
```python
# since map and filter receive the iterable on their second argument, you have to use `Then2`
f = Then2(filter, P % 2 == 0) >> Then2(map, P**2) >> list  #lambda x: map(lambda z: z**2, filter(lambda z: z % 2 == 0, x))

assert f([1,2,3,4,5]) == [4, 16]  #[2**2, 4**2] == [4, 16]
```
Be aware that `P` already has the `map` and `filter` methods so you can write the previous more easily as
```python
f = P.filter(P % 2 == 0) >> P.map(P**2) >> list  #lambda x: map(lambda z: z**2, filter(lambda z: z % 2 == 0, x))

assert f([1,2,3,4,5]) == [4, 16]  #[2**2, 4**2] == [4, 16]
```

#### Val
If you need to create a constant function with a given value use `Val`
```python
f = Val(42)  #lambda x: 42

assert f("whatever") == 42
```

#### Others
Check out the `With`, `If` and more, combinators on the documentation. The `P` object also offers some useful combinators as methods such as `Not`, `First`, `Last` plus **almost all** python built in functions as methods:

```python
f = Obj.split(' ') >> P.map(len) >> sum >> If( (P < 15).Not(), "Great! Got {0} letters!".format).Else("Too short, need at-least 15 letters")

assert f("short frase") == "Too short, need at-least 15 letters"
assert f("some longer frase") == "Great! Got 15 letters!"
```

## The DSL
Phi has a small omnipresent DSL that has these simple rules:

1. Any element of the class `Expression` is an element of the DSL. `P` and all the combinators are of the `Expression` class.
2. Any callable of arity 1 is an element of the DSL.
3. The container types `list`, `tuple`, `set`, and `dict` are elements of the DSL. They are translated to their counterparts `List`, `Tuple`, `Set` and `Dict`, their internal elements are forwarded.
4. Any value `x` that does not comply with any of the previous rules is also an element of the DSL and is translated to `Val(x)`.

Using the DSL, the expression

```python
f = P**2 >> List( P, Val(3), Val(4) )  #lambda x: [ x**2]

assert f(10) == [ 100, 3, 4 ]  # [ 10**2, 3, 4 ]  == [ 100, 3, 4 ]
```
can be rewritten as
```python
f = P**2 >> [ P, 3, 4 ]

assert f(10) == [ 100, 3, 4 ]  # [ 10 ** 2, 3, 4 ]  == [ 100, 3, 4 ]
```
Here the values `3` and `4` are translated to `Val(3)` and `Val(4)` thanks to the *4th* rule, and `[...]` is translated to `List(...)` thanks to the *3rd* rule. Since the DSL is omnipresent you can use it inside any core function, so the previous can be rewritten using `Pipe` as
```python
assert [ 100, 3, 4 ] == Pipe(
  10,
  P**2,  # 10**2 == 100
  [ P, 3, 4 ]  #[ 100, 3, 4 ]
)
```

#### F
You can *compile* any element to an `Expression` using `F`
```python
f = F((P + "!!!", 42, Obj.upper()))  #Tuple(P + "!!!", Val(42), Obj.upper())

assert f("some tuple") == ("some tuple!!!", 42, "SOME TUPLE")
```
Other example
```python
f = F([ P + n for n in range(5) ])  >> [ len, sum ]  # lambda x: [ len([ x, x+1, x+2, x+3, x+4]), sum([ x, x+1, x+2, x+3, x+4]) ]

assert f(10) == [ 5, 60 ]  # [ len([10, 11, 12, 13, 14]), sum([10, 11, 12, 13, 14])] == [ 5, (50 + 0 + 1 + 2 + 3 + 4) ] == [ 5, 60 ]
```

## Fluent Programming
All the functions you've seen are ultimately methods of the `PythonBuilder` class which inherits from the `Expression`, therefore you can also [fluently](https://en.wikipedia.org/wiki/Fluent_interface) chain methods instead of using the `>>` operator. For example

```python
f = Dict(
  x = 2 * P,
  y = P + 1
).Tuple(
  Rec.x + Rec.y,
  Rec.y / Rec.x
)

assert f(1) == (4, 1)  # ( x + y, y / x) == ( 2 + 2, 2 / 2) == ( 4, 1 )
```
This more complicated previous example
```python
f = Obj.split(' ') >> P.map(len) >> sum >> If( (P < 15).Not(), "Great! Got {0} letters!".format).Else("Too short, need at-least 15 letters")

assert f("short frase") == "Too short, need at-least 15 letters"
assert f("some longer frase") == "Great! Got 15 letters!"
```
can be be rewritten as
```python
f = (
  Obj.split(' ')
  .map(len)
  .sum()
  .If( (P < 15).Not(),
    "Great! Got {0} letters!".format
  ).Else(
    "Too short, need at-least 15 letters"
  )
)

assert f("short frase") == "Too short, need at-least 15 letters"
assert f("some longer frase") == "Great! Got 15 letters!"
```

## Integrability
#### Register, Register2, ..., Register5, RegistarAt
If you want to have custom expressions to deal with certain data types, you can create a custom class that inherits from `Builder` or `PythonBuilder`
```python
from phi import PythonBuilder

class MyBuilder(PythonBuilder):
  pass

M = MyBuilder()
```
and register your function in it using the `Register` class method

```python
def remove_longer_than(some_list, n):
  return [ elem from elem in some_list if len(elem) <= n ]

MyBuilder.Register(remove_longer_than, "my.lib.")
```
Or better even use `Register` as a decorator
```python
@MyBuilder.Register("my.lib.")
def remove_longer_than(some_list, n):
  return [ elem for elem in some_list if len(elem) <= n ]
```

Now the method `MyBuilder.remove_longer_than` exists on this class. You can then use it like this
```python
f = Obj.lower() >> Obj.split(' ') >> M.remove_longer_than(6)

assert f("SoMe aRe LONGGGGGGGGG") == ["some", "are"]
```
As you see the argument `n = 6` was partially applied to `remove_longer_than`, an expression which waits for the `some_list` argument to be returned. Internally the `Registar*` method family uses the `Then*` method family.

#### PatchAt
If you want to register a batch of functions from a module or class automatically you can use the `PatchAt` class method. It's an easy way to integrate an entire module to Phi's DSL. See `PatchAt`.

#### Libraries
Phi currently powers the following libraries that integrate with its DSL:

* [PythonBuilder](https://cgarciae.github.io/phi/python_builder.m.html) : helps you integrate Python's built-in functions and keywords into the phi DSL and it also includes a bunch of useful helpers for common stuff. `phi`'s global `P` object is an instance of this class. [Shipped with Phi]
* [TensorBuilder](https://github.com/cgarciae/tensorbuilder): a TensorFlow library enables you to easily create complex deep neural networks by leveraging the phi DSL to help define their structure.
* NumpyBuilder: Comming soon!

## Documentation
Check out the [complete documentation](https://cgarciae.github.io/phi/).

## More Examples
The global `phi.P` object exposes most of the API and preferably should be imported directly. The most simple thing the DSL does is function composition:

```python
from phi.api import *

def add1(x): return x + 1
def mul3(x): return x * 3

x = Pipe(
    1.0,     #input 1
    add1,  #1 + 1 == 2
    mul3   #2 * 3 == 6
)

assert x == 6
```

Use phi [lambdas](https://cgarciae.github.io/phi/lambdas.m.html) to create the functions

```python
from phi.api import *

x = Pipe(
    1.0,      #input 1
    P + 1,  #1 + 1 == 2
    P * 3   #2 * 3 == 6
)

assert x == 6
```

Create a branched computation instead

```python
from phi.api import *

[x, y] = Pipe(
    1.0,  #input 1
    [
        P + 1  #1 + 1 == 2
    ,
        P * 3  #1 * 3 == 3
    ]
)

assert x == 2
assert y == 3
```

Compose it with a function equivalent to `f(x) = (x + 3) / (x + 1)`

```python
from phi.api import *

[x, y] = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1),  #(1 + 3) / (1 + 1) == 4 / 2 == 2
    [
        P + 1  #2 + 1 == 3
    ,
        P * 3  #2 * 3 == 6
    ]
)

assert x == 3
assert y == 6
```

Give names to the branches

```python
from phi.api import *

result = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1),  #(1 + 3) / (1 + 1) == 4 / 2 == 2
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    )
)

assert result.x == 3
assert result.y == 6
```

Divide `x` by `y`.

```python
from phi.api import *

result = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1),  #(1 + 3) / (1 + 1) == 4 / 2 == 2
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    Rec.x / Rec.y  #3 / 6 == 0.5
)

assert result == 0.5
```

Save the value from the `(P + 3) / (P + 1)` computation as `s` and load it at the end in a branch

```python
from phi.api import *

[result, s] = Pipe(
    1.0,  #input 1
    Write(s = (P + 3) / (P + 1)), #s = 4 / 2 == 2
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read('s')  #s == 2
    ]
)

assert result == 0.5
assert s == 2
```

Add 3 to the loaded `s` for fun and profit

```python
from phi.api import *

[result, s] = Pipe(
    1.0,  #input 1
    Write(s = (P + 3) / (P + 1)), #s = 4 / 2 == 2
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read('s') + 3  # 2 + 3 == 5
    ]
)

assert result == 0.5
assert s == 5
```

Use the `Read` and `Write` field access lambda style just because

```python
from phi.api import *

[result, s] = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1), #4 / 2 == 2
    Write.s,  #s = 2
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read.s + 3  # 2 + 3 == 5
    ]
)

assert result == 0.5
assert s == 5
```

Add an input `Val` of 9 on a branch and add to it 1 just for the sake of it

```python
from phi.api import *

[result, s, val] = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1), Write.s,  #4 / 2 == 2, saved as 's'
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read.s + 3  # 2 + 3 == 5
    ,
        Val(9) + 1  #input 9 and add 1, gives 10
    ]
)

assert result == 0.5
assert s == 5
assert val == 10
```

Do the previous only if `y > 7` else return `"Sorry, come back latter."`

```python
from phi.api import *

[result, s, val] = Pipe(
    1.0,  #input 1
    (P + 3) / (P + 1), Write.s,  #4 / 2 == 2, saved as 's'
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read.s + 3  # 2 + 3 == 5
    ,
        If( Rec.y > 7,
            Val(9) + 1  #input 9 and add 1, gives 10    
        ).Else(
            "Sorry, come back latter."
        )
    ]
)

assert result == 0.5
assert s == 5
assert val == "Sorry, come back latter."
```

Now, what you have to understand that everything you've done with these expression is to create and apply a single function. Using `Seq` we can get the standalone function and then use it to get the same values as before

```python
from phi.api import *

f = Seq(
    (P + 3) / (P + 1), Write.s,  #4 / 2 == 2, saved as 's'
    dict(
        x = P + 1  #2 + 1 == 3
    ,
        y = P * 3  #2 * 3 == 6
    ),
    [
        Rec.x / Rec.y  #3 / 6 == 0.5
    ,
        Read.s + 3  # 2 + 3 == 5
    ,
        If( Rec.y > 7,
            Val(9) + 1  #input 9 and add 1, gives 10    
        ).Else(
            "Sorry, come back latter."
        )
    ]
)

[result, s, val] = f(1.0)

assert result == 0.5
assert s == 5
assert val == "Sorry, come back latter."
```
### Even More Examples

```python
from phi.api import *

avg_word_length = Pipe(
    "1 22 333",
    Obj.split(" "), # ['1', '22', '333']
    P.map(len), # [1, 2, 3]
    P.sum() / P.len() # sum([1,2,3]) / len([1,2,3]) == 6 / 3 == 2
)

assert 2 == avg_word_length
```

```python
from phi.api import *

assert False == Pipe(
    [1,2,3,4], P
    .filter(P % 2 != 0)   #[1, 3], keeps odds
    .Contains(4)   #4 in [1, 3] == False
)
```

```python
from phi.api import *

assert {'a': 97, 'b': 98, 'c': 99} == Pipe(
    "a b c", Obj
    .split(' ').Write.keys  # keys = ['a', 'b', 'c']
    .map(ord),  # [ord('a'), ord('b'), ord('c')] == [97, 98, 99]
    lambda it: zip(Ref.keys, it),  # [('a', 97), ('b', 98), ('c', 99)]
    dict   # {'a': 97, 'b': 98, 'c': 99}
)
```

## Installation

    pip install phi


#### Bleeding Edge

    pip install git+https://github.com/cgarciae/phi.git@develop

## Status
* Version: **0.6.4**.
* Documentation coverage: 100%. Please create an issue if documentation is unclear, it is a high priority of this library.
* Milestone: reach 1.0.0 after feedback from the community.