added usage help to a lot of modules, added a verbose option to karma.py.

modules/bitly.py

@@ -11,7 +11,8 @@ class Module(object):
         self.bot = bot
         bot.events.on("get").on("shortlink").hook(self.shortlink)
         bot.events.on("received").on("command").on("shorten"
-            ).hook(self.shorten, min_args=1)
+            ).hook(self.shorten, min_args=1, help="Shorten a URL.",
+            usage="<url>")
 
     def shortlink(self, event):
         url = event["url"]

modules/books.py

@@ -11,10 +11,10 @@ class Module(object):
         self.bot = bot
         bot.events.on("received").on("command").on("isbn").hook(
             self.isbn, help="Get book information from a provided ISBN",
-            min_args=1)
+            min_args=1, usage="<isbn>")
         bot.events.on("received").on("command").on("book").hook(
             self.book, help="Get book information from a provided title",
-            min_args=1)
+            min_args=1, usage="<book title>")
 
     def get_book(self, query, event):
         page = Utils.get_url(URL_GOOGLEBOOKS, get_params={

modules/commands.py

@@ -47,9 +47,10 @@ class Module(object):
         bot.events.on("received").on("message").on("private").hook(
             self.private_message)
         bot.events.on("received").on("command").on("help").hook(self.help,
-            help="Show help for commands")
+            help="Show help for commands", usage="<command>")
         bot.events.on("received").on("command").on("usage").hook(self.usage,
-            help="Show usage help for commands", min_args=1)
+            help="Show usage help for commands", min_args=1,
+            usage="<command>")
         bot.events.on("received").on("command").on("more").hook(self.more,
             help="Get more output from the last command")
         bot.events.on("new").on("user", "channel").hook(self.new)

modules/define.py

@@ -8,7 +8,8 @@ class Module(object):
     def __init__(self, bot):
         self.bot = bot
         bot.events.on("received").on("command").on("define").hook(
-            self.define, help="Define a provided term")
+            self.define, help="Define a provided term",
+            usage="<phrase>")
 
     def define(self, event):
         if event["args"]:

modules/dns.py

@@ -5,7 +5,8 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("dns").hook(
             self.dns, min_args=1,
-            help="Get all addresses for a given hostname (IPv4/IPv6)")
+            help="Get all addresses for a given hostname (IPv4/IPv6)",
+            usage="<hostname>")
 
     def dns(self, event):
         hostname = event["args_split"][0]

modules/geoip.py

@@ -7,7 +7,8 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("geoip").hook(
             self.geoip, min_args=1,
-            help="Get geoip data on a given IPv4/IPv6 address")
+            help="Get geoip data on a given IPv4/IPv6 address",
+            usage="<IP>")
 
     def geoip(self, event):
         page = Utils.get_url(URL_GEOIP % event["args_split"][0],

modules/google.py

@@ -9,7 +9,8 @@ class Module(object):
     def __init__(self, bot):
         self.bot = bot
         bot.events.on("received").on("command").on("google",
-            "g").hook(self.google, help="Google feeling lucky")
+            "g").hook(self.google, help="Google feeling lucky",
+            usage="[search term]")
 
     def google(self, event):
         phrase = event["args"] or event["log"].get()

modules/haveibeenpwned.py

@@ -8,7 +8,7 @@ class Module(object):
         bot.events.on("received").on("command").on("beenpwned").hook(
             self.beenpwned, min_args=1,
             help="Find out if a username, email or similar has appeared "
-            "in any hacked databased")
+            "in any hacked databased", usage="<username/email>")
 
     def beenpwned(self, event):
         page = Utils.get_url(URL_HAVEIBEENPWNEDAPI % event["args"], json=True,

modules/imdb.py

@@ -9,7 +9,8 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("imdb").hook(
             self.imdb, min_args=1,
-            help="Search for a given title on IMDb")
+            help="Search for a given title on IMDb",
+            usage="<movie/tv title>")
 
     def imdb(self, event):
         page = Utils.get_url(URL_OMDB, get_params={"t": event["args"]},

modules/in.py

@@ -9,7 +9,7 @@ class Module(object):
         self.bot = bot
         bot.events.on("received").on("command").on("in").hook(
             self.in_command, min_args=2,
-            help="Set a reminder")
+            help="Set a reminder", usage="<time> <message>")
         bot.events.on("received").on("numeric").on("001").hook(
             self.on_connect)
 

modules/karma.py

@@ -5,11 +5,22 @@ KARMA_DELAY_SECONDS = 3
 
 class Module(object):
     def __init__(self, bot):
+        self.bot = bot
         bot.events.on("new").on("user").hook(self.new_user)
         bot.events.on("received").on("message").on("channel").hook(
             self.channel_message)
         bot.events.on("received").on("command").on("karma").hook(
-            self.karma, help="Get your or someone else's karma")
+            self.karma, help="Get your or someone else's karma",
+            usage="[target]")
+        bot.events.on("boot").on("done").hook(self.boot_done)
+
+    def validate_setchannel(self, s):
+        return s.lower() == "true"
+    def boot_done(self, event):
+        self.bot.events.on("postboot").on("configure").on(
+            "channelset").call(setting="karmaverbose",
+            help="Disable/Enable automatically responding to karma changes",
+            validate=self.validate_setchannel)
 
     def new_user(self, event):
         event["user"].last_karma = None
@@ -20,6 +31,7 @@ class Module(object):
             if not event["user"].last_karma or (time.time()-event["user"
                     ].last_karma) >= KARMA_DELAY_SECONDS:
                 target = match.group(1).lower().strip()
+                verbose = event["channel"].get_setting("karmaverbose", False)
                 if not target == event["user"].name:
                     positive = match.group(2)[0] == "+"
                     setting = "karma-%s" % target
@@ -32,7 +44,14 @@ class Module(object):
                         event["server"].set_setting(setting, karma)
                     else:
                         event["server"].del_setting(setting)
+                    if verbose:
+                        self.bot.events.on("send").on("stdout").call(
+                            module_name="Karma", target=event["channel"],
+                            message="%s now has %d karma" % (target, karma))
                     event["user"].last_karma = time.time()
+                elif verbose:
+                    self.bot.events.on("send").on("stderr").call(module_name="Karma",
+                        target=event["channel"], message="You cannot change your own karma")
 
     def karma(self, event):
         if event["args"]:

modules/lastfm.py

@@ -10,7 +10,8 @@ class Module(object):
         bot.events.on("boot").on("done").hook(self.boot_done)
         bot.events.on("received").on("command").on("np",
             "listening", "nowplaying").hook(self.np,
-            help="Get the last listen to track from a user")
+            help="Get the last listen to track from a user",
+            usage="[username]")
 
     def boot_done(self, event):
         self.bot.events.on("postboot").on("configure").on(

modules/permissions.py

@@ -7,11 +7,14 @@ class Module(object):
         bot.events.on("new").on("user").hook(self.new_user)
         bot.events.on("received").on("part").hook(self.on_part)
         bot.events.on("received").on("command").on("identify"
-            ).hook(self.identify, private_only=True, min_args=1)
+            ).hook(self.identify, private_only=True, min_args=1,
+            usage="<password>", help="Identify yourself")
         bot.events.on("received").on("command").on("register"
-            ).hook(self.register, private_only=True, min_args=1)
+            ).hook(self.register, private_only=True, min_args=1,
+            usage="<password>", help="Register your nickname")
         bot.events.on("received").on("command").on("logout"
-            ).hook(self.logout, private_only=True)
+            ).hook(self.logout, private_only=True,
+            help="Sign out from the bot")
 
     def new_user(self, event):
         self._logout(event["user"])

modules/random.py

@@ -3,7 +3,8 @@ import random
 class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("random",
-            "rand").hook(self.random, help="Get a random number")
+            "rand").hook(self.random, help="Get a random number",
+            usage="[start] [end]")
 
     def random(self, event):
         start, end = "1", "100"

modules/seen.py

@@ -7,7 +7,8 @@ class Module(object):
             ).hook(self.channel_message)
         bot.events.on("received").on("command").on("seen").hook(
             self.seen, min_args=1,
-            help="Find out when a user was last seen")
+            help="Find out when a user was last seen",
+            usage="<username>")
 
     def channel_message(self, event):
         seen_seconds = time.time()

modules/thesaurus.py

@@ -9,7 +9,8 @@ class Module(object):
         self.bot = bot
         bot.events.on("received").on("command").on("synonym",
             "antonym").hook(self.thesaurus, min_args=1,
-            help="Get synonyms/antonyms for a provided phrase")
+            help="Get synonyms/antonyms for a provided phrase",
+            usage="<word> [type]")
 
     def thesaurus(self, event):
         phrase = event["args_split"][0]

modules/title.py

@@ -7,7 +7,7 @@ class Module(object):
 	def __init__(self, bot):
 		bot.events.on("received").on("command").on("title", "t").hook(
 			self.title, help="Get the title of the provided or most "
-            "recent URL.")
+            "recent URL.", usage="[URL]")
 
 	def title(self, event):
 		url = None

modules/to.py

@@ -7,7 +7,7 @@ class Module(object):
         bot.events.on("received").on("command").on("to").hook(
             self.to, min_args=2, help=("Relay a message to a "
             "user the next time they talk in a channel"),
-            channel_only=True)
+            channel_only=True, usage="<username> <message>")
 
     def channel_message(self, event):
         setting = "to-%s" % event["user"].nickname

modules/trakt.py

@@ -12,7 +12,7 @@ class Module(object):
         bot.events.on("received").on("command").on("nowwatching",
             "nw").hook(self.now_watching,
             help="Get what you or another user is now watching "
-            "on trakt.tv")
+            "on trakt.tv", usage="[username]")
 
     def boot_done(self, event):
         self.bot.events.on("postboot").on("configure").on("set"

modules/translate.py

@@ -8,7 +8,7 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("translate", "tr").hook(
             self.translate, help="Translate the provided phrase or the "
-            "last line seen.")
+            "last line seen.", usage="[phrase]")
 
     def translate(self, event):
         phrase = event["args"]

modules/twitter.py

@@ -14,7 +14,8 @@ class Module(object):
     def __init__(self, bot):
         self.bot = bot
         bot.events.on("received").on("command").on("twitter", "tw"
-            ).hook(self.twitter, help="Find a tweet")
+            ).hook(self.twitter, help="Find a tweet",
+            usage="[@username/URL/ID]")
 
     def make_timestamp(self, s):
         seconds_since = time.time()-datetime.datetime.strptime(s,

modules/urbandictionary.py

@@ -8,7 +8,8 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("urbandictionary", "ud"
             ).hook(self.ud, min_args=1,
-            help="Get the definition of a provided term")
+            help="Get the definition of a provided term",
+            usage="<term>")
 
     def ud(self, event):
         term = event["args"]

modules/weather.py

@@ -6,10 +6,11 @@ URL_WEATHER = "http://api.openweathermap.org/data/2.5/weather"
 
 class Module(object):
     def __init__(self, bot):
+        self.bot = bot
         bot.events.on("received").on("command").on("weather").hook(
             self.weather, min_args=1,
-            help="Get current weather data for a provided location")
+            help="Get current weather data for a provided location",
-        self.bot = bot
+            usage="<location>")
 
     def weather(self, event):
         api_key = self.bot.config["openweathermap-api-key"]

modules/wolframalpha.py

@@ -11,7 +11,8 @@ class Module(object):
     def __init__(self, bot):
         bot.events.on("received").on("command").on("wolframalpha", "wa"
             ).hook(self.wa, min_args=1, help=
-            "Evauate a given string on Wolfram|Alpha")
+            "Evauate a given string on Wolfram|Alpha",
+            usage="<query>")
         self.bot = bot
 
     def wa(self, event):

modules/words.py

@@ -7,7 +7,8 @@ class Module(object):
         bot.events.on("received").on("message").on("channel"
             ).hook(self.channel_message)
         bot.events.on("received").on("command").on("words"
-            ).hook(self.words, channel_only=True)
+            ).hook(self.words, channel_only=True,
+            usage="<nickname>")
 
     def new_server(self, event):
         event["server"].tracked_words = set([])

modules/youtube.py

@@ -21,7 +21,7 @@ class Module(object):
         self.bot = bot
         bot.events.on("received").on("command").on("yt", "youtube"
             ).hook(self.yt,
-            help="Find a video on youtube")
+            help="Find a video on youtube", usage="[query]")
         bot.events.on("received").on("message").on("channel").hook(
             self.channel_message)
         bot.events.on("boot").on("done").hook(self.boot_done)