Commits

Devin Jeanpierre  committed 31d266d

made builder docs better

  • Participants
  • Parent commits f196dad

Comments (0)

Files changed (1)

File tetrisinventory/__init__.py

 from tetrisinventory.compat import izip_longest
 
 def builder(constructor):
-    """Create a container using a generator"""
+    """Create a container using a generator.
+    
+    The constructor is called with the return value of the decorated function.
+        
+        >>> from itertools import izip_longest
+        >>> @builder(tuple)
+        ... def ndim_sub(v1, v2):
+        ...     for a, b in izip_longest(v1, v2, fillvalue=0):
+        ...         yield a - b
+        ...
+        >>> ndim_sub((0, 1), (1, 2, 3)) == (-1, -1, -3)
+        True
+        
+    Non-generator return values can be used as well, of course::
+        
+        >>> from itertools import chain
+        >>> s = builder(set)(chain)(["ab"], "cd")
+        >>> s == set(['ab', 'c', 'd'])
+        True
+    
+    """
     # should really get added to the builtins
     def decorator(f):
         def g(*args, **kwargs):