Merge pull request #27 from babetoduarte/master

Added basic comment descriptions to the scripts and to some of the so…

amodem/alsa.py

@@ -1,3 +1,8 @@
+"""Code which adds Linux ALSA support for interfaces,
+recording and playing.
+
+"""
+
 import subprocess
 import logging
 

amodem/async.py

@@ -1,3 +1,5 @@
+"""Asynchronous Reading capabilities for amodem."""
+
 import threading
 import six  # since `Queue` module was renamed to `queue` (in Python 3)
 import logging

amodem/audio.py

@@ -1,3 +1,5 @@
+"""Audio capabilities for amodem."""
+
 import ctypes
 import logging
 import time

amodem/calib.py

@@ -1,3 +1,5 @@
+"""Calibration capabilities for amodem."""
+
 from . import common
 from . import dsp
 from . import sampling

amodem/common.py

@@ -1,5 +1,7 @@
-''' Common package functionality.
-'''
+""" Common package functionality.
+Commom utilities and procedures for amodem.
+
+"""
 
 import itertools
 import numpy as np
@@ -11,25 +13,25 @@ scaling = 32000.0  # out of 2**15
 
 
 def load(fileobj):
-    ''' Load signal from file object. '''
+    """ Load signal from file object. """
     return loads(fileobj.read())
 
 
 def loads(data):
-    ''' Load signal from memory buffer. '''
+    """ Load signal from memory buffer. """
     x = np.frombuffer(data, dtype='int16')
     x = x / scaling
     return x
 
 
 def dumps(sym):
-    ''' Dump signal to memory buffer. '''
+    """ 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. '''
+    """ Iterate over a signal, taking each time *size* elements. """
     offset = 0
     data = iter(data)
 
@@ -47,9 +49,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.
+    """ 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]
@@ -59,26 +61,26 @@ def split(iterable, n):
 
 
 def icapture(iterable, result):
-    ''' Appends each yielded item to 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. '''
+    """ Take n elements from iterable, and return them as a numpy array. """
     return np.array(list(itertools.islice(iterable, n)))
 
 
 def izip(iterables):
-    ''' "Python 3" zip re-implementation for Python 2. '''
+    """ "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. '''
+    """ Dummy placeholder object for testing and mocking. """
 
     def __getattr__(self, name):
         return self

amodem/config.py

@@ -1,3 +1,5 @@
+"""Configuration class."""
+
 import numpy as np
 
 

amodem/detect.py

@@ -1,3 +1,5 @@
+"""Signal detection capabilities for amodem."""
+
 from . import dsp
 from . import equalizer
 from . import common

amodem/dsp.py

@@ -1,3 +1,5 @@
+"""Digital Signal Processing capabilities for amodem."""
+
 import numpy as np
 
 from . import common
@@ -60,7 +62,7 @@ def coherence(x, omega):
 
 
 def linear_regression(x, y):
-    ''' Find (a,b) such that y = a*x + b. '''
+    """ Find (a,b) such that y = a*x + b. """
     x = np.array(x)
     y = np.array(y)
     mean_x = np.mean(x)
@@ -98,7 +100,7 @@ class MODEM(object):
             yield self.encode_map[bits_tuple]
 
     def decode(self, symbols, error_handler=None):
-        ''' Maximum-likelihood decoding, using naive nearest-neighbour. '''
+        """ Maximum-likelihood decoding, using naive nearest-neighbour. """
         symbols_vec = self.symbols
         _dec = self.decode_list
         for received in symbols:
@@ -111,7 +113,7 @@ class MODEM(object):
 
 
 def prbs(reg, poly, bits):
-    ''' Simple pseudo-random number generator. '''
+    """ Simple pseudo-random number generator. """
     mask = (1 << bits) - 1
 
     size = 0  # effective register size (in bits)

amodem/equalizer.py

@@ -1,3 +1,5 @@
+"""Audio equalizing capabilities for amodem."""
+
 from . import dsp
 from . import sampling
 from . import levinson

amodem/levinson.py

@@ -2,9 +2,9 @@ import numpy as np
 
 
 def solver(t, y):
-    ''' Solve Mx = y for x, where M[i,j] = t[|i-j|], in O(N^2) steps.
+    """ Solve Mx = y for x, where M[i,j] = t[|i-j|], in O(N^2) steps.
         See http://en.wikipedia.org/wiki/Levinson_recursion for details.
-    '''
+    """
     N = len(t)
     assert len(y) == N
 

scripts/plot.py

@@ -1,4 +1,11 @@
 #!/usr/bin/env python
+
+"""Script that exposes pylab's spectogram plotting
+capabilities to the command line. It implements this
+for amodem.config Configurations.
+
+"""
+
 import pylab
 import numpy as np
 from amodem import common
@@ -27,5 +34,6 @@ def main():
 
     pylab.show()
 
+
 if __name__ == '__main__':
     main()

scripts/record.py

@@ -1,4 +1,9 @@
 #!/usr/bin/env python
+
+"""Script that records audio through an interface
+and stores it into an amodem.config Configuration.
+
+"""
 import argparse
 from amodem import audio
 from amodem.config import Configuration

scripts/resample.py

@@ -1,4 +1,10 @@
 #!/usr/bin/env python
+
+"""Script that exposes the amodem.resample() function
+to the command line, taking parameters via standard
+inputs and returning results via standard outputs.
+"""
+
 from amodem.sampling import resample
 import argparse
 import sys
@@ -11,5 +17,6 @@ def main():
 
     resample(src=sys.stdin, dst=sys.stdout, df=args.df)
 
+
 if __name__ == '__main__':
     main()