Merge pull request #23 from wardellchandler/nightly

Readme updates for new docstring changes for commands.

Author: wardellbagby

Core/Bot.py

@@ -25,7 +25,7 @@
     [["bot", "robot", "Yo"], "/think {}"]
   ],
   "development_mode": false,
-  "commands_admin": ["hangouts", "reload", "quit", "restart", "config", "restart", "block"],
+  "commands_admin": ["hangouts", "reload", "quit", "config", "block"],
   "commands_conversation_admin": ["leave", "echo", "block"]
   "commands_enabled": true,
   "forwarding_enabled": false,

Core/Commands/ExtraCommands.py

@@ -82,106 +82,96 @@ def udefine(bot, event, *args):
 @DispatcherSingleton.register
 def remind(bot, event, *args):
     # TODO Implement a private chat feature. Have reminders save across reboots?
-    if ''.join(args) == '?':
-        segments = [hangups.ChatMessageSegment('Remind', is_bold=True),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
-                    hangups.ChatMessageSegment(
-                        'Usage: /remind <optional: date [defaults to today]> <optional: time [defaults to an hour from now]> Message'),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
-                    hangups.ChatMessageSegment(
-                        'Usage: /remind'),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
-                    hangups.ChatMessageSegment(
-                        'Usage: /remind delete <index to delete>'),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
+    """
+    *Remind:*
+    Usage: /remind <optional: date [defaults to today]> <optional: time [defaults to an hour from now]> <message> {/remind 1/1/15 2:00PM Call mom}
+    Usage: /remind
+    Usage /remind delete <index to delete> {/remind delete 1}
+    Purpose: Will post a message on the date and time specified to the current chat. With no arguments, it'll list all the reminders."""
+    if len(args) == 0:
+        segments = [hangups.ChatMessageSegment('Reminders:', is_bold=True),
+                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK)]
+        if len(reminders) > 0:
+            for x in range(0, len(reminders)):
+                reminder = reminders[x]
+                reminder_timer = reminder[0]
+                reminder_text = reminder[1]
+                date_to_post = datetime.now() + timedelta(seconds=reminder_timer.interval)
+                segments.append(
                     hangups.ChatMessageSegment(
-                        'Purpose: Will post a message the date and time specified to the current chat. With no arguments, it\'ll list all the reminders.')]
-        bot.send_message_segments(event.conv, segments)
-    else:
-        if len(args) == 0:
-            segments = [hangups.ChatMessageSegment('Reminders:', is_bold=True),
-                        hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK)]
-            if len(reminders) > 0:
-                for x in range(0, len(reminders)):
-                    reminder = reminders[x]
-                    reminder_timer = reminder[0]
-                    reminder_text = reminder[1]
-                    date_to_post = datetime.now() + timedelta(seconds=reminder_timer.interval)
-                    segments.append(
-                        hangups.ChatMessageSegment(
-                            str(x + 1) + ' - ' + date_to_post.strftime('%m/%d/%y %I:%M%p') + ' : ' + reminder_text))
-                    segments.append(hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK))
-                segments.pop()
-                bot.send_message_segments(event.conv, segments)
-            else:
-                bot.send_message(event.conv, "No reminders are currently set.")
-            return
-        if args[0] == 'delete':
-            try:
-                x = int(args[1])
-                x -= 1
-            except ValueError:
-                bot.send_message(event.conv, 'Invalid integer: ' + args[1])
-                return
-            if x in range(0, len(reminders)):
-                reminder_to_remove_text = reminders[x][1]
-                reminders[x][0].cancel()
-                reminders.remove(reminders[x])
-                bot.send_message(event.conv, 'Removed reminder: ' + reminder_to_remove_text)
-            else:
-                bot.send_message(event.conv, 'Invalid integer: ' + str(x + 1))
-            return
-
-        def send_reminder(bot, conv, reminder_time, reminder_text, loop):
-            asyncio.set_event_loop(loop)
-            bot.send_message(conv, reminder_text)
-            for reminder in reminders:
-                if reminder[0].interval == reminder_time and reminder[1] == reminder_text:
-                    reminders.remove(reminder)
-
-        args = list(args)
-        date = str(datetime.now().today().date())
-        time = str((datetime.now() + timedelta(hours=1)).time())
-        set_date = False
-        set_time = False
-        index = 0
-        while index < len(args):
-            item = args[index]
-            if item[0].isnumeric():
-                if '/' in item or '-' in item:
-                    date = item
-                    args.remove(date)
-                    set_date = True
-                    index -= 1
-                else:
-                    time = item
-                    args.remove(time)
-                    set_time = True
-                    index -= 1
-            if set_date and set_time:
-                break
-            index += 1
-
-        reminder_time = date + ' ' + time
-        if len(args) > 0:
-            reminder_text = ' '.join(args)
+                        str(x + 1) + ' - ' + date_to_post.strftime('%m/%d/%y %I:%M%p') + ' : ' + reminder_text))
+                segments.append(hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK))
+            segments.pop()
+            bot.send_message_segments(event.conv, segments)
         else:
-            bot.send_message(event.conv, 'No reminder text set.')
-            return
-        current_time = datetime.now()
+            bot.send_message(event.conv, "No reminders are currently set.")
+        return
+    if args[0] == 'delete':
         try:
-            reminder_time = parser.parse(reminder_time)
-        except (ValueError, TypeError):
-            bot.send_message(event.conv, "Couldn't parse " + reminder_time + " as a valid date.")
+            x = int(args[1])
+            x -= 1
+        except ValueError:
+            bot.send_message(event.conv, 'Invalid integer: ' + args[1])
             return
-        if reminder_time < current_time:
-            reminder_time = current_time + timedelta(hours=1)
-        reminder_interval = (reminder_time - current_time).seconds
-        reminder_timer = threading.Timer(reminder_interval, send_reminder,
-                                         [bot, event.conv, reminder_interval, reminder_text, asyncio.get_event_loop()])
-        reminders.append((reminder_timer, reminder_text))
-        reminder_timer.start()
-        bot.send_message(event.conv, "Reminder set for " + reminder_time.strftime('%B %d, %Y %I:%M%p'))
+        if x in range(0, len(reminders)):
+            reminder_to_remove_text = reminders[x][1]
+            reminders[x][0].cancel()
+            reminders.remove(reminders[x])
+            bot.send_message(event.conv, 'Removed reminder: ' + reminder_to_remove_text)
+        else:
+            bot.send_message(event.conv, 'Invalid integer: ' + str(x + 1))
+        return
+
+    def send_reminder(bot, conv, reminder_time, reminder_text, loop):
+        asyncio.set_event_loop(loop)
+        bot.send_message(conv, reminder_text)
+        for reminder in reminders:
+            if reminder[0].interval == reminder_time and reminder[1] == reminder_text:
+                reminders.remove(reminder)
+
+    args = list(args)
+    date = str(datetime.now().today().date())
+    time = str((datetime.now() + timedelta(hours=1)).time())
+    set_date = False
+    set_time = False
+    index = 0
+    while index < len(args):
+        item = args[index]
+        if item[0].isnumeric():
+            if '/' in item or '-' in item:
+                date = item
+                args.remove(date)
+                set_date = True
+                index -= 1
+            else:
+                time = item
+                args.remove(time)
+                set_time = True
+                index -= 1
+        if set_date and set_time:
+            break
+        index += 1
+
+    reminder_time = date + ' ' + time
+    if len(args) > 0:
+        reminder_text = ' '.join(args)
+    else:
+        bot.send_message(event.conv, 'No reminder text set.')
+        return
+    current_time = datetime.now()
+    try:
+        reminder_time = parser.parse(reminder_time)
+    except (ValueError, TypeError):
+        bot.send_message(event.conv, "Couldn't parse " + reminder_time + " as a valid date.")
+        return
+    if reminder_time < current_time:
+        reminder_time = current_time + timedelta(hours=1)
+    reminder_interval = (reminder_time - current_time).seconds
+    reminder_timer = threading.Timer(reminder_interval, send_reminder,
+                                     [bot, event.conv, reminder_interval, reminder_text, asyncio.get_event_loop()])
+    reminders.append((reminder_timer, reminder_text))
+    reminder_timer.start()
+    bot.send_message(event.conv, "Reminder set for " + reminder_time.strftime('%B %d, %Y %I:%M%p'))
 
 
 @DispatcherSingleton.register

readme.md

@@ -4,7 +4,7 @@ HangoutsBot
 Setup
 --------------
 
-In order to use this, you'll need to setup a GMail account for logging in, and a config.json file to give the bot its settings. The config file should look like:
+In order to use this, you'll need to setup a GMail account for logging in, and a config.json file (placed either at the folder root or in the Core folder) to give the bot its settings. The config file should look something like:
 
 ```JSON
 {
@@ -14,7 +14,7 @@ In order to use this, you'll need to setup a GMail account for logging in, and a
     [["bot", "robot", "Yo"], "/think {}"]
   ],
   "development_mode": false,
-  "commands_admin": ["hangouts", "reload", "quit", "restart", "config", "restart", "block"],
+  "commands_admin": ["hangouts", "reload", "quit", "config", "block"],
   "commands_conversation_admin": ["leave", "echo", "block"],
   "commands_enabled": true,
   "forwarding_enabled": false,
@@ -32,7 +32,9 @@ In order to use this, you'll need to setup a GMail account for logging in, and a
     }
   }
 }
-```
+```  
+
+If you neglect to create a config.json file, this exact one will be created for you in the Core folder.  
 
 Line by Line breakdown (excluding braces/brackets):  
 
@@ -54,6 +56,8 @@ Line by Line breakdown (excluding braces/brackets):
 16. Start of the "forward_to" array. All conversation IDs listed here will have this conversation forwarded to them.  
 17. "CONV-ID-HERE" should be replaced with an actual id, which looks something like "Ugxxxxxxxxxxx_xxxxxxxxxxxxx", and then commands will be forwarded to that conversation.  
 
+Note: Every top-level argument can be made a conversation level argument, which will overwrite the top level argument for that conversation. For instance, if you put a commands_admin array containing only "quit" and "block" in "CONV-ID-HERE", in the CONV-ID-HERE conversation, all users would be able to run /hangouts, /reload, /config, etc but would still be blocked from running /quit and /block. Conversely, if you put an empty commands_admin array in CONV-ID-HERE, all users in that conversation would be able to run all commands (except any commands in the "commands_conversation_admin" array unless they're a conversation admin.)  
+
 A cookies.txt file will also be created, holding the cookies that are valid for your login.  
 
 Usage
@@ -72,19 +76,20 @@ Any function created in the ExtraCommands.py file (or any .py file that imports
 
 ```python  
 @DispatcherSingleton.register
-def function_for_bot(bot, event, *args):
-     if ''.join(args) == '?':
-        segments = [hangups.ChatMessageSegment('New Function For Bot', is_bold=True),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
-                    hangups.ChatMessageSegment('Usage: /function_for_bot <required argument> <optional: optional argument>'),
-                    hangups.ChatMessageSegment('\n', hangups.SegmentType.LINE_BREAK),
-                    hangups.ChatMessageSegment('Purpose: Does a thing.')]
-        bot.send_message_segments(event.conv, segments)
-     else:
-        # Do actual functionality here.
+def command(bot, event, *args):
+    """Command
+    Usage: /command <required argument> <optional: optional argument> {for complicated commands, put an example call in curly braces}
+    Purpose: Does a thing."""
+    
+    # Do actual functionality here.
 ```  
 
-It should be frowned upon to force a user to put underscores in to use a command, but that's up to you to decide.  
+The docstring isn't necessary, but should be used as it will be printed out if a user uses "/help \<command name\>" or does "/\<command_name\> ?". Admin-only commands generally don't have help text by default, but that's left up to your discretion.
+   
+The bot variable is a reference to the HangoutsBot that is currently running. The event variable is a ConversationEvent that has information about the event (as in, text, the user who sent it, the conversation, and all users in the conversation.) The \*args variable is a tuple of all of the text sent along with the command call, split by whitespace so that you can easily check its values. Look at the DefaultCommands.py file for actual examples of how commands work.  
+  
+It should be frowned upon to force a user to put underscores in to use a command, but that's up to you to decide.
+  
 
 
 Have fun botting!