-

cool-RR · cool-RR · commit 654956f3a63e · 2013-09-06T04:52:19.000+03:00
diff --git a/python_toolbox/monkeypatch_envelopes.py b/python_toolbox/monkeypatch_envelopes.py
@@ -1,6 +1,7 @@
 # Copyright 2009-2013 Ram Rachum.
 # This program is distributed under the MIT license.
 
+'''Module for monkeypatching our own copy of `envelopes`.'''
 
 ### Monkeypatching envelopes: #################################################
 #                                                                             #
diff --git a/python_toolbox/monkeypatching_tools.py b/python_toolbox/monkeypatching_tools.py
@@ -14,8 +14,7 @@
 @decorator_tools.helpful_decorator_builder
 def monkeypatch_method(monkeypatchee, name=None):
     '''
-    blocktododoc
-    Monkeypatch a method into a class.
+    Monkeypatch a method into a class (or an object).
     
     Example:
     
@@ -33,7 +32,8 @@ def my_method(a):
     You may use the `name` argument to specify a method name different from the
     function's name.
     
-    You can also use this to monkeypatch a `CachedProperty` into a class.
+    You can also use this to monkeypatch a `CachedProperty`, a `classmethod`
+    and a `staticmethod` into a class.
     '''
     
     monkeypatchee_is_a_class = misc_tools.is_type(monkeypatchee)
@@ -49,8 +49,6 @@ def decorator(function):
             new_method = types.MethodType(function, None, monkeypatchee) if \
                 monkeypatchee_is_a_class else types.MethodType(function,
                                          monkeypatchee, class_of_monkeypatchee)
-            # todo: Last line was: `new_method = types.MethodType(function,
-            # class_)`, is subtly wrong, make tests to prove
             setattr(monkeypatchee, name_, new_method)
             return function
         else:
diff --git a/python_toolbox/pickle_tools.py b/python_toolbox/pickle_tools.py
@@ -188,7 +188,9 @@ def persistent_load(self, id_string):
  
  
 def compickle(thing):
+    '''Pickle `thing` and compress it using `zlib`.'''
     return zlib.compress(pickle_module.dumps(thing, protocol=2))
 
 def decompickle(thing):
+    '''Unpickle `thing` after decompressing it using `zlib`.'''
     return pickle_module.loads(zlib.decompress(thing))
diff --git a/python_toolbox/sequence_tools.py b/python_toolbox/sequence_tools.py
@@ -16,9 +16,9 @@
 
 def are_equal_regardless_of_order(seq1, seq2):
     '''
-    blocktododoc
-    Return whether the two sequences are equal in the elements they contain,
-    regardless of the order of the elements.
+    Do `seq1` and `seq2` contain the same elements, same number of times?
+    
+    Disregards order of elements.
 
     Currently will fail for items that have problems with comparing.
     '''
@@ -264,9 +264,9 @@ def to_tuple(single_or_sequence, item_type=None, item_test=None):
 
 def pop_until(sequence, condition=bool):
     '''
-    blocktododoc
+    Look for item in `sequence` that passes `condition`, popping away others.
     
-    Propagates whatever error is raised on popping the sequence.
+    When sequence is empty, propagates the `IndexError`.
     '''
     while True:
         item = sequence.pop()
@@ -275,6 +275,11 @@ def pop_until(sequence, condition=bool):
 
 
 def get_recurrences(sequence):
+    '''
+    Get a `dict` of all items that repeat at least twice.
+    
+    The values of the dict are the numbers of repititions of each item.    
+    '''
     # Use when ditching Python 2.6:
     #return {item: n_recurrences for item, n_recurrences in
             #Counter(sequence).most_common() if n_recurrences >= 2}
diff --git a/python_toolbox/zip_tools.py b/python_toolbox/zip_tools.py
@@ -58,6 +58,11 @@ def zip_folder(folder, zip_path, ignored_patterns=()):
                 
                 
 def zip_in_memory(files):
+    '''
+    Zip files in memory and return zip archive as a string.
+    
+    Files should be given as tuples of `(file_path, file_contents)`.
+    '''
     zip_stream = string_io_module.StringIO()
     with contextlib.closing(zip_module.ZipFile(zip_stream, mode='w',
                             compression=zip_module.ZIP_DEFLATED)) as zip_file:
@@ -68,6 +73,11 @@ def zip_in_memory(files):
     return zip_stream.getvalue()
     
 def unzip_in_memory(zip_archive):
+    '''
+    Unzip a zip archive given as string, returning files
+    
+    Files are returned as tuples of `(file_path, file_contents)`.
+    '''    
     zip_stream = string_io_module.StringIO(zip_archive)
     with contextlib.closing(zip_module.ZipFile(zip_stream, mode='r',
                             compression=zip_module.ZIP_DEFLATED)) as zip_file:
