common: add docstrings

amodem/common.py

@@ -1,3 +1,6 @@
+''' Common package functionality.
+'''
+
 import itertools
 import numpy as np
 
@@ -8,21 +11,25 @@ scaling = 32000.0  # out of 2**15
 
 
 def load(fileobj):
+    ''' Load signal from file object. '''
     return loads(fileobj.read())
 
 
 def loads(data):
+    ''' Load signal from memory buffer. '''
     x = np.frombuffer(data, dtype='int16')
     x = x / scaling
     return x
 
 
 def dumps(sym):
+    ''' Dump signal to memory buffer. '''
     sym = sym.real * scaling
     return sym.astype('int16').tostring()
 
 
 def iterate(data, size, func=None, truncate=True, index=False):
+    ''' Iterate over a signal, taking each time *size* elements. '''
     offset = 0
     data = iter(data)
 
@@ -40,6 +47,9 @@ def iterate(data, size, func=None, truncate=True, index=False):
 
 
 def split(iterable, n):
+    ''' Split an iterable of n-tuples into n iterables of scalars.
+    The k-th iterable will be equivalent to (i[k] for i in iter).
+    '''
     def _gen(it, index):
         for item in it:
             yield item[index]
@@ -49,23 +59,26 @@ def split(iterable, n):
 
 
 def icapture(iterable, result):
+    ''' Appends each yielded item to result. '''
     for i in iter(iterable):
         result.append(i)
         yield i
 
 
 def take(iterable, n):
+    ''' Take n elements from iterable, and return them as a numpy array. '''
     return np.array(list(itertools.islice(iterable, n)))
 
 
-# "Python 3" zip re-implementation for Python 2
 def izip(iterables):
+    ''' "Python 3" zip re-implementation for Python 2. '''
     iterables = [iter(iterable) for iterable in iterables]
     while True:
         yield tuple([next(iterable) for iterable in iterables])
 
 
 class Dummy(object):
+    ''' Dummy placeholder object for testing and mocking. '''
 
     def __getattr__(self, name):
         return self