update reqs, add some doc strings

.checkignore

@@ -1,2 +1 @@
-tests/
-docs/
+docs/conf.py

api/serializers.py

@@ -6,6 +6,9 @@
 
 
 class RecipientSerializer(serializers.ModelSerializer):
+    """
+    Serializes apostello.models.Recipient for use in table.
+    """
     url = serializers.CharField(source='get_absolute_url')
 
     class Meta:
@@ -19,6 +22,9 @@ class Meta:
 
 
 class RecipientGroupSerializer(serializers.ModelSerializer):
+    """
+    Serializes apostello.models.RecipientGroup for use in table.
+    """
     cost = serializers.CharField(source='calculate_cost')
     url = serializers.CharField(source='get_absolute_url')
     members = serializers.ListField(source='all_recipients_names')
@@ -34,6 +40,9 @@ class Meta:
 
 
 class KeywordSerializer(serializers.ModelSerializer):
+    """
+    Serializes apostello.models.Keyword for use in table.
+    """
     url = serializers.CharField(source='get_absolute_url')
     responses_url = serializers.CharField(source='get_responses_url')
     num_replies = serializers.CharField(source='num_matches')
@@ -52,6 +61,9 @@ class Meta:
 
 
 class SmsInboundSerializer(serializers.ModelSerializer):
+    """
+    Serializes apostello.models.SmsInbound for use in log and wall.
+    """
     time_received = serializers.DateTimeField(format='%d %b %H:%M')
 
     class Meta:
@@ -67,6 +79,9 @@ class Meta:
 
 
 class SmsOutboundSerializer(serializers.ModelSerializer):
+    """
+    Serializes apostello.models.SmsOutbound for use in log.
+    """
     time_sent = serializers.DateTimeField(format='%d %b %H:%M')
     recipient = serializers.StringRelatedField()
 

apostello/context_processors.py

@@ -3,6 +3,6 @@
 
 
 def global_settings(request):
-    # return any necessary values
+    """Expose TWILIO_FROM_NUM and DEBUG in templates"""
     return {'TWILIO_FROM_NUM': settings.TWILIO_FROM_NUM,
             'DEBUG': settings.DEBUG}

apostello/decorators.py

@@ -10,6 +10,8 @@
 
 
 def keyword_access_check(method):
+    """Checks a user can access a specific keyword."""
+
     @wraps(method)
     def wrapper(request, *args, **kwargs):
         if request.user.is_staff:
@@ -29,6 +31,7 @@ def wrapper(request, *args, **kwargs):
 
 
 def check_user_perms(view=None, require=None):
+    """Checks a user has the specified permissions."""
     if view is None:
         return partial(check_user_perms, require=require)
 

apostello/elvanto.py

@@ -8,10 +8,17 @@
 
 
 def elvanto():
+    """Shortcut to create Elvanto API instance"""
     return ElvantoAPI.Connection(APIKey=settings.ELVANTO_KEY)
 
 
 def grab_elvanto_groups():
+    """
+    Returns a list of elvanto groups.
+    Each group is a tuple: ('group id', 'group name').
+
+    TODO: replace with a list of named tuples
+    """
     e_api = elvanto()
     data = e_api._Post("groups/getAll")
     if data['status'] == 'ok':
@@ -21,7 +28,11 @@ def grab_elvanto_groups():
 
 
 def fix_elvanto_numbers(num_string):
-    '''Checks if number starts with +447 or 077 and normalises'''
+    """
+    Checks if number starts with +447 or 077 and normalises
+
+    TODO: modify for other locales
+    """
     number = re.sub("[^0-9]", "", num_string)
     if number.startswith(settings.COUNTRY_CODE + '7'):
         number = "+" + number
@@ -34,12 +45,26 @@ def fix_elvanto_numbers(num_string):
 
 
 def try_both_num_fields(mobile, phone):
+    """
+    Returns a person's phone number by checking both the
+    'mobile' and 'phone' fields.
+    """
     mobile_ = fix_elvanto_numbers(mobile)
     final_num = mobile_ if mobile_ is not None else fix_elvanto_numbers(phone)
     return final_num
 
 
 def grab_elvanto_people(group_id):
+    """
+    Returns the group name and a list of dictionaries.
+    Each dictionary has a "number", "first_name" and "last_name"
+    for each person.
+
+    An empty list is returned if the group is empty.
+
+    TODO: return a list of namedtuples
+    TODO: do not return empty list, raise exception
+    """
     e_api = elvanto()
     data = e_api._Post("groups/getInfo", id=group_id, fields=['people'])
     group_name = data['group'][0]['name']
@@ -53,7 +78,7 @@ def grab_elvanto_people(group_id):
 
 def import_elvanto_groups(group_ids, user_email):
     """
-    Import all people from groups provided
+    Imports all people from groups provided.
     """
     from apostello.models import Recipient, RecipientGroup
     for group_id in group_ids:

apostello/exceptions.py

@@ -6,5 +6,7 @@ class ApostelloException(Exception):
 
 
 class NoKeywordMatchException(ApostelloException):
-    """"""
+    """
+    SMS matches no keywords.
+    """
     pass

apostello/forms.py

@@ -8,6 +8,9 @@
 
 
 class SendAdhocRecipientsForm(forms.Form):
+    """
+    Sends an sms to ad-hoc groups.
+    """
     content = forms.CharField(
         validators=[gsm_validator, less_than_sms_char_limit],
         required=True,
@@ -26,6 +29,9 @@ class SendAdhocRecipientsForm(forms.Form):
 
 
 class SendRecipientGroupForm(forms.Form):
+    """
+    Sends an sms to pre-defined group.
+    """
     content = forms.CharField(
         validators=[gsm_validator, less_than_sms_char_limit],
         required=True,
@@ -46,6 +52,11 @@ class SendRecipientGroupForm(forms.Form):
 
 
 class ManageRecipientGroupForm(forms.ModelForm):
+    """
+    Manages RecipientGroup updates and creation.
+
+    __init__ and save are overridden to pull in group members.
+    """
 
     class Meta:
         model = RecipientGroup
@@ -77,6 +88,9 @@ def save(self, *args, **kwargs):
 
 
 class RecipientForm(forms.ModelForm):
+    """
+    Updates Recipients.
+    """
 
     class Meta:
         model = Recipient
@@ -87,6 +101,9 @@ class Meta:
 
 
 class KeywordForm(forms.ModelForm):
+    """
+    Updates Keywords.
+    """
 
     class Meta:
         model = Keyword
@@ -102,16 +119,27 @@ class Meta:
 
 
 class ArchiveKeywordResponses(forms.Form):
+    """
+    Used on keyword log page to allow user to archive all matching messages.
+
+    Single tick-box field for confirmation.
+    """
     tick_to_archive_all_responses = forms.BooleanField()
 
 
 class CsvImport(forms.Form):
+    """
+    Handles CSV imports.
+    """
     csv_data = forms.CharField(
         help_text='John, Calvin, +447095237960',
         widget=forms.Textarea
     )
 
 
 class ElvantoImport(forms.Form):
+    """
+    Handles Elvanto imports.
+    """
     group_choices = grab_elvanto_groups()
     elvanto_groups = forms.MultipleChoiceField(choices=group_choices)

apostello/logs.py

@@ -8,6 +8,9 @@
 
 
 def import_incoming_sms():
+    """
+    Loops over all incoming messages in Twilio's logs and adds them to our db.
+    """
     try:
         sms_page = twilio_client.messages.iter(to_=settings.TWILIO_FROM_NUM)
         for x in sms_page:
@@ -41,6 +44,9 @@ def import_incoming_sms():
 
 
 def import_outgoing_sms():
+    """
+    Loops over all outgoing messages in Twilio's logs and adds them to our db.
+    """
     try:
         sms_page = twilio_client.messages.iter(from_=settings.TWILIO_FROM_NUM)
         for x in sms_page:

apostello/management/commands/import_incoming_sms.py

@@ -5,6 +5,10 @@
 
 
 class Command(BaseCommand):
+    """
+    Checks Twilio's incoming logs for our number and updates the
+    database to match.
+    """
     args = ''
     help = 'Import incoming messages from twilio'
 

apostello/management/commands/import_outgoing_sms.py

@@ -5,6 +5,10 @@
 
 
 class Command(BaseCommand):
+    """
+    Checks Twilio's outgoing logs for our number and updates the
+    database to match.
+    """
     args = ''
     help = 'Import outgoing messages from twilio'
 

apostello/management/commands/update_sms_name_fields.py

@@ -6,6 +6,9 @@
 
 
 class Command(BaseCommand):
+    """
+    Updates names on messages for all existing contacts.
+    """
     args = ''
     help = 'Update from_name fields'
 

apostello/mixins.py

@@ -5,13 +5,23 @@
 
 
 class LoginRequiredMixin(object):
+    """
+    Checks if a user is logged in.
+    Redirects to login page otherwise.
+
+    TODO: Remove when Django 1.9 is released.
+    """
     @classmethod
     def as_view(cls, **initkwargs):
         view = super(LoginRequiredMixin, cls).as_view(**initkwargs)
         return login_required(view)
 
 
 class ProfilePermsMixin(object):
+    """
+    Checks if a user is staff or has permission.
+    Redirects to '/' otherwise.
+    """
     @classmethod
     def as_view(cls, **initkwargs):
         view = super(ProfilePermsMixin, cls).as_view(**initkwargs)