updated README

Author: Qian Wenjie

README.md

@@ -1,2 +1,101 @@
 lazy-python
 ===========
+
+A Python Lazy Programming library.
+
+Overview
+-----------
+
+*Lazy Evaluation* is among useful features in Functional Programming. 
+This tool help make lazy evaluation in Python easy to use.  The expression
+is saved in directed graph and evaluate when necessary. The evaluation 
+leverage multicore (``multiprocessing`` library in Python) and graph cut
+algorithm to compute the results in parallel.
+
+Examples
+-----------
+
+This example illustrate how to calculate *Fibnoacci* by Lazy Evalution and
+the cache mechanism of pure function call with the same parameters.
+
+    >>> from lazy import Lazy
+    >>> def fib(n):
+    ...     return Lazy(int, debug=True)(n) if n <= 1 else fib(n-1) + fib(n-2)
+    ... 
+    >>> a = fib(10)
+    >>> a
+    (((((((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))+(((1+int(0))+1)+(1+int(0))))+((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1)))+(((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))+(((1+int(0))+1)+(1+int(0)))))+((((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))+(((1+int(0))+1)+(1+int(0))))+((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))))+(((((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))+(((1+int(0))+1)+(1+int(0))))+((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1)))+(((((1+int(0))+1)+(1+int(0)))+((1+int(0))+1))+(((1+int(0))+1)+(1+int(0))))))
+    >>> a.eval()
+    int(0) == 0
+    (1+0) == 1
+    (1+1) == 2
+    (2+1) == 3
+    (3+2) == 5
+    (5+3) == 8
+    (8+5) == 13
+    (13+8) == 21
+    (21+13) == 34
+    (34+21) == 55
+    55
+    >>> a
+    55
+    >>> b = fib(11)
+    >>> b
+    (55+34)
+    >>> b.eval()
+    (55+34) == 89
+    89
+
+Lazy Evaluation uses implicit parallel by *multiprocessing*. The following
+example shows how the implicit parallel works by using decorator *lazy*.
+
+    from lazy import lazy
+    import time
+    
+    def f(name):
+        print('Enter', name)
+        time.sleep(5)
+        print('Leave', name)
+    
+    @lazy
+    def f1():
+        f('f1')
+        return 1
+    
+    @lazy
+    def f2():
+        f('f2')
+        return 2
+    
+    @lazy
+    def f3():
+        f('f3')
+        return 3
+    
+    @lazy
+    def f4():
+        f('f4')
+        return 4
+    
+    if __name__ == '__main__':
+        s = f1()*f2()+f3()*f4()
+        print(s)
+        s.eval()
+        print(s)
+    
+    $ time python3 1.py
+    ((f1()*f2())+(f3()*f4()))
+    Enter f1
+    Enter f2
+    Enter f3
+    Enter f4
+    Leave f1
+    Leave f3
+    Leave f4
+    Leave f2
+    14
+    
+    real    0m5.173s
+    user    0m0.111s
+    sys 0m0.049s
+

lazy/__init__.py

@@ -1,2 +1,2 @@
-from lazy import Lazy, INT
+from .lazy import lazy, Lazy, INT
 

lazy/lazy.py

@@ -3,6 +3,14 @@
 from operator import add, sub, mul, truediv, getitem
 import time, weakref
 
+def lazy(func):
+    new_name = '_lazy_'+func.__name__
+    globals()[new_name] = func
+    func.__name__ = new_name
+    func.__module__ = __name__
+    lazyfunc = Lazy(func)
+    return lazyfunc
+
 class Lazy(object):
 
     POOL = None
@@ -14,14 +22,15 @@ class Lazy(object):
     @classmethod
     def set_cores(cls, num):
         cls.CORES = num
-    def __init__(self, operator, remote=True, format='{0}({1})'):
+    def __init__(self, operator, remote=True, format='{0}({1})', debug=False):
         self.operator = operator
         self.remote = remote
         self.format = format
         self.func = True
         self.depth = -1
         self.args = None
         self.waitlock = None
+        self.debug = debug
     def call(self, *args):
         cache_key = (self.operator, args)
         if cache_key in Lazy.CACHES:
@@ -41,6 +50,8 @@ def call(self, *args):
                 if i.value is None:
                     self.argscount += 1
                     i.waitings.append(self)
+                if i.debug:
+                    self.debug = True
         if self.argscount == 0:
             if self.remote:
                 Lazy.JOBS.add(self)
@@ -56,7 +67,7 @@ def setdepth(self, l=0):
                 i.setdepth(l+(1 if i.remote else 0))
         self.depth = max(self.depth, l)
     def __call__(self, *args):
-        s = Lazy(self.operator, self.remote, self.format)
+        s = Lazy(self.operator, self.remote, self.format, self.debug)
         return s.call(*args)
     def __add__(self, a):
         return ADD(self, a)
@@ -84,11 +95,16 @@ def __eq__(self, other):
         return self.operator == other.operator and self.args == other.args
     def __hash__(self):
         return hash((self.operator, self.args))
+    def opname(self):
+        if self.operator.__name__.startswith('_lazy_'):
+            return self.operator.__name__[6:]
+        else:
+            return self.operator.__name__
     def __str__(self):
         if self.func:
-            return 'Lazy(%s)' % (self.operator.__name__,)
+            return 'Lazy(%s)' % (self.opname(),)
         elif self.value is None:
-            return self.format.format(self.operator.__name__, ', '.join(map(str, self.args)), *self.args)
+            return self.format.format(self.opname(), ', '.join(map(str, self.args)), *self.args)
         else:
             return str(self.value)
     def __repr__(self):
@@ -99,7 +115,8 @@ def argsfinish(self):
             Lazy.JOBS.add(self)
     def finish(self, value):
         self.runtime = time.time() - self.startrun
-        #print(self, '==', value)
+        if self.debug:
+            print(self, '==', value)
         self.value = value
         for i in self.waitings[:]:
             i.argsfinish()