add doc for memoize and memoize_when_activated

docs/misc.rst

@@ -1,7 +1,7 @@
 Miscellanea
 -----------
 
-.. py:function:: pydu.unix_timeout(seconds)
+.. py:function:: pydu.misc.unix_timeout(seconds)
 
   This func decorates any func which may be hang for a while. The param ``seconds``
   should be integer.
@@ -21,14 +21,14 @@ Miscellanea
   .. note:: ``unix_timeout`` can only be used on ``unix-like`` system.
 
 
-.. py:function:: pydu.trace(obj)
+.. py:function:: pydu.misc.trace(obj)
 
   Tracing every statement and line number for running program, like ``bash -x``.
   In `test.py`, you may write like below:
 
   .. code-block:: python
 
-    from pydu import trace
+    from pydu.misc import trace
     @trace
     def f():
         print(1)
@@ -47,3 +47,47 @@ Miscellanea
     test.py(6):     b = [a]
     test.py(7):     print(2)
     2
+
+
+.. py:function:: pydu.misc.memoize(obj)
+
+  A simple memoize decorator for functions supporting (hashable)
+  positional arguments.
+  It also provides a ``cache_clear()`` function for clearing the cache.
+
+  >>> @memoize
+  ... def foo()
+  ...     return 1
+      ...
+  >>> foo()
+  1
+  >>> foo.cache_clear()
+  >>>
+
+
+.. py:function:: pydu.misc.memoize_when_activated(obj)
+
+  A memoize decorator which is disabled by default. It can be
+  activated and deactivated on request.
+  For efficiency reasons it can be used only against class methods
+  accepting no arguments.
+
+  >>> class Foo:
+  ...     @memoize
+  ...     def foo()
+  ...         print(1)
+  ...
+  >>> f = Foo()
+  >>> # deactivated (default)
+  >>> foo()
+  1
+  >>> foo()
+  1
+  >>>
+  >>> # activated
+  >>> foo.cache_activate()
+  >>> foo()
+  1
+  >>> foo()
+  >>> foo()
+  >>>

pydu/compat.py

@@ -10,6 +10,7 @@ if PY2:
 else:
     from urllib.parse import urljoin
 
+# TODO doc
 # Dictionary iteration
 if PY2:
     iterkeys = lambda d: d.iterkeys()

pydu/string.py

@@ -24,6 +24,7 @@ def safeunicode(obj, encoding='utf-8'):
         return text_type(obj)
 
 
+# TODO doc
 def safestr(obj, encoding='utf-8'):
     r"""
     Converts any given object to utf-8 encoded string.