docs: Add basic documentation to handlers and utils

* Trata de #4

bpb/handlers.py

@@ -33,15 +33,19 @@
 
 
 def start(update, context):
-
+    """
+    Handle sending the start message
+    """
     context.bot.send_message(
         chat_id=update.effective_chat.id,
         text=START,
     )
 
 
 def get_meeting(update, context):
-
+    """
+    Get current meetings set on context
+    """
     try:
         datetime_obj = getattr(context.bot, "next_meeting")
 
@@ -66,6 +70,9 @@ def get_meeting(update, context):
 
 
 def set_meeting(update, context):
+    """
+    Set meetings and alarms
+    """
 
     try:
         chat_id = update.message.chat_id
@@ -99,6 +106,9 @@ def set_meeting(update, context):
 
 
 def clear_meetings(update, context):
+    """
+    Clear meetings and alarms
+    """
 
     try:
 
@@ -117,13 +127,19 @@ def clear_meetings(update, context):
 
 
 def links(update, context):
+    """
+    Get important links
+    """
 
     context.bot.send_message(
         chat_id=update.effective_chat.id, text=LINKS_IMPORTANTES, parse_mode="Markdown"
     )
 
 
 def welcome(update, context):
+    """
+    Welcome a new group member
+    """
 
     new_member = update.message.new_chat_members[0]
 
@@ -135,6 +151,9 @@ def welcome(update, context):
 
 
 def get_handlers():
+    """
+    Aggregate and return handlers
+    """
 
     handlers = [
         MessageHandler(Filters.status_update.new_chat_members, welcome),

bpb/utils.py

@@ -6,11 +6,30 @@
 
 
 def prettify_date(dt_object):
+    """
+    Pretty-format a datetime object
+
+    Args:
+        dt_object(datetime.datetime): A datetime object.
+
+    Returns:
+        str: A pretty-formatted date.
+    """
 
     return dt_object.strftime("%A %Hh%M, %d %b %Y")
 
 
 def parse_date(date_args):
+    """
+    Parse argument into a datetime object
+
+    Args:
+        date_args: A list or datetime object to be parsed.
+
+    Returns:
+        tuple: A tuple of a string-date and a datetime object.
+    """
+
     if isinstance(date_args, (list, tuple)):
         date_args = " ".join(date_args)
     elif isinstance(date_args, datetime):
@@ -21,6 +40,16 @@ def parse_date(date_args):
 
 
 def get_meeting_range(date_args):
+    """
+    Parse argument into datetimes and datetime range.
+
+    Args:
+        date_args: A list or datetime object to be parsed.
+
+    Returns:
+        tuple: A tuple of a string-date, a datetime object and
+        a list of tuple representing the next meetings.
+    """
 
     # Get message meeting and following ones
     parsed_date, datetime_obj = parse_date(date_args)
@@ -35,18 +64,40 @@ def get_meeting_range(date_args):
 
 
 def add_timedeltas(dt_object):
+    """
+    Localize and buffer meeting datetime object
+
+    Adds a timedelta of +3 to localize to GMT-3 and
+    a timedelta of -30min for the reminder.
+
+    Args:
+        dt_object(datetime.datetime): A datetime object.
+
+    Returns:
+        datetime.datetime: A datetime object localized and buffered.
+    """
 
     return dt_object + timedelta(hours=3) - timedelta(minutes=30)
 
 
 def generate_reminders(next_meetings):
+    """
+    Generate list of datetimes for the alarms
+
+    Args:
+        next_meetings(list): The list made by get_meeting_range.
 
+    Returns:
+        list: A list of datetime objects corresponding to alarm times.
+    """
     alarm_times = [add_timedeltas(meeting[1]) for meeting in next_meetings]
 
     return alarm_times
 
 
 def alarm(context):
-
+    """
+    Handle sending the alarm message
+    """
     job = context.job
     context.bot.send_message(job.context, text=LEMBRETE)