From acca8723b36ed729fed3e2e6a62402beb20c1aa3 Mon Sep 17 00:00:00 2001 From: "Brian S. Stephan" Date: Thu, 6 Jan 2011 23:25:46 -0600 Subject: [PATCH] convert to/standardize docstrings a bit. this got boring fast, so it's only half done --- modules/Alias.py | 12 +++--- modules/Countdown.py | 38 ++++++++++-------- modules/Dice.py | 80 +++++++++++++++++++++++--------------- modules/Echo.py | 7 ++-- modules/EightBall.py | 1 + modules/FactFile.py | 38 ++++++++++-------- modules/Facts.py | 13 ++++--- modules/GoogleTranslate.py | 46 +++++++++++++--------- modules/IrcAdmin.py | 51 ++++++++++++------------ 9 files changed, 160 insertions(+), 126 deletions(-) diff --git a/modules/Alias.py b/modules/Alias.py index 55d4a87..c5eaec1 100644 --- a/modules/Alias.py +++ b/modules/Alias.py @@ -24,13 +24,11 @@ from extlib import irclib from Module import Module class Alias(Module): - """ - Allows for commands to be aliased as !command, circumventing bot addressing stuff. - """ + + """Alias commands as !command, circumventing bot addressing stuff.""" def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): - """ - See if there is an alias ("!command") in the text, and if so, translate it into + """See if there is an alias ("!command") in the text, and if so, translate it into an internal bot command and run it. """ @@ -99,8 +97,8 @@ class Alias(Module): except NoSectionError: pass def try_recursion(self, connection, event, nick, userhost, replypath, what, admin_unlocked): - """ - Scan message for subcommands to execute and use as part of this command. + """Scan message for subcommands to execute and use as part of this command. + Upon seeing a line intended for this module, see if there are subcommands that we should do what is basically a text replacement on. The intent is to allow things like the following: diff --git a/modules/Countdown.py b/modules/Countdown.py index a5313fd..40019b4 100644 --- a/modules/Countdown.py +++ b/modules/Countdown.py @@ -1,18 +1,20 @@ -# Countdown - track and display time until events -# Copyright (C) 2010 Brian S. Stephan -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +""" +Countdown - track and display time until events +Copyright (C) 2010 Brian S. Stephan + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +""" from ConfigParser import NoOptionError, NoSectionError from datetime import datetime @@ -24,11 +26,13 @@ from extlib import irclib from Module import Module -# Class that adds a countdown item to the bot - class Countdown(Module): + """Class that adds a countdown item to the bot.""" + def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): + """Add/retrieve countdown items.""" + whats = what.split(' ') if whats[0] == 'countdown' and len(whats) >= 2: if whats[1] == 'add' and len(whats) >= 4: diff --git a/modules/Dice.py b/modules/Dice.py index eb26083..ef47e2a 100644 --- a/modules/Dice.py +++ b/modules/Dice.py @@ -1,18 +1,20 @@ -# Dice - roll dice when asked, intended for RPGs -# Copyright (C) 2010 Brian S. Stephan -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +""" +Dice - roll dice when asked, intended for RPGs +Copyright (C) 2010 Brian S. Stephan + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +""" import math import re @@ -25,10 +27,10 @@ from Module import Module import ply.lex as lex import ply.yacc as yacc -# Rolls dice, for RPGs mostly - class Dice(Module): + """Roll simple or complex dice strings.""" + tokens = ['NUMBER', 'TEXT'] literals = ['#', '/', '+', '-', 'd', ';'] @@ -56,9 +58,11 @@ class Dice(Module): output = "" - # Takes the parsed dice string for a single roll (eg 3/4d20) and performs - # the actual roll. Returns a string representing the result def roll_dice(self, keep, dice, size): + """Takes the parsed dice string for a single roll (eg 3/4d20) and performs + the actual roll. Returns a string representing the result. + """ + a = range(dice) for i in range(dice): a[i] = random.randint(1, size) @@ -82,10 +86,14 @@ class Dice(Module): return (total, outstr) - # Processes rolls coming from the parser. This generates the inputs - # for the roll_dice() command, and returns the full string representing - # the whole current dice string (the part up to a semicolon or end of line) def process_roll(self, trials, mods, comment): + """Processes rolls coming from the parser. + + This generates the inputs for the roll_dice() command, and returns + the full string representing the whole current dice string (the part + up to a semicolon or end of line). + """ + output = "" repeat = 1 if trials != None: @@ -129,18 +137,22 @@ class Dice(Module): output = "%s: %s" % (comment.strip(), output) return output - # General idea I had when creating this grammar: A roll string is a chain - # of modifiers, which may be repeated for a certain number of trials. It can - # have a comment that describes the roll - # Multiple roll strings can be chained with semicolon def p_roll_r(self, p): + """Chain rolls together.""" + + # General idea I had when creating this grammar: A roll string is a chain + # of modifiers, which may be repeated for a certain number of trials. It can + # have a comment that describes the roll + # Multiple roll strings can be chained with semicolon + 'roll : roll ";" roll' global output p[0] = p[1] + "; " + p[3] output = p[0] - # The basic roll string def p_roll(self, p): + """Parse a basic roll string.""" + 'roll : trial modifier comment' global output mods = [] @@ -151,8 +163,9 @@ class Dice(Module): p[0] = self.process_roll(p[1], mods, p[3]) output = p[0] - # Trial is optional so have a rule without it def p_roll_no_trials(self, p): + """Parse a roll string without trials.""" + 'roll : modifier comment' global output mods = [] @@ -164,6 +177,8 @@ class Dice(Module): output = p[0] def p_comment(self, p): + """Parse a comment.""" + '''comment : TEXT |''' if len(p) == 2: @@ -172,6 +187,8 @@ class Dice(Module): p[0] = None def p_modifier(self, p): + """Parse a modifier on a roll string.""" + '''modifier : modifier "+" modifier | modifier "-" modifier''' # Use append to prevent nested lists (makes dealing with this easier) @@ -186,8 +203,9 @@ class Dice(Module): else: p[0] = [p[1], p[2], p[3]] - # Return the left side before the "d", and the number of faces def p_die(self, p): + """Return the left side before the "d", and the number of faces.""" + 'modifier : left NUMBER' p[0] = (p[1], p[2]) @@ -195,8 +213,8 @@ class Dice(Module): 'modifier : NUMBER' p[0] = p[1] - # left is the number of dice we are rolling, and how many we are keeping def p_left(self, p): + """Parse the number of dice we are rolling, and how many we are keeping.""" 'left : keep dice' if p[1] == None: p[0] = [None, p[2]] @@ -233,8 +251,8 @@ class Dice(Module): 'dice : "d"' p[0] = 1 - # Provide the user with something (albeit not much) when the roll can't be parsed def p_error(self, p): + """Provide the user with something (albeit not much) when the roll can't be parsed.""" global output output = "Unable to parse roll" diff --git a/modules/Echo.py b/modules/Echo.py index 68cfa08..9e18bff 100644 --- a/modules/Echo.py +++ b/modules/Echo.py @@ -21,11 +21,12 @@ from extlib import irclib from Module import Module class Echo(Module): - """ - Repeat provided text, for random internal use, mostly. - """ + + """Repeat provided text.""" def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): + """Repeat provided text.""" + whats = what.split(' ') if whats[0] == 'echo' and len(whats) >= 2: return self.reply(connection, replypath, ' '.join(whats[1:])) diff --git a/modules/EightBall.py b/modules/EightBall.py index 832e508..151dc64 100644 --- a/modules/EightBall.py +++ b/modules/EightBall.py @@ -23,6 +23,7 @@ from extlib import irclib from Module import Module class EightBall(Module): + """Return a random answer when asked a question.""" def __init__(self, config, server, modlist): diff --git a/modules/FactFile.py b/modules/FactFile.py index 15147d6..1c9837e 100644 --- a/modules/FactFile.py +++ b/modules/FactFile.py @@ -1,18 +1,20 @@ -# FactFile - display facts from a flat file upon request -# Copyright (C) 2010 Brian S. Stephan -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +""" +FactFile - display facts from a flat file upon request +Copyright (C) 2010 Brian S. Stephan + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +""" from ConfigParser import NoOptionError import os @@ -23,11 +25,13 @@ from extlib import irclib from Module import Module -# Returns a random fact/quote/whatever from one or more files - class FactFile(Module): + """Return a random fact/quote/whatever from one or more files.""" + def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): + """Search for a fact, or return a random one.""" + whats = what.split(' ') try: filename = self.config.get(self.__class__.__name__, whats[0]) diff --git a/modules/Facts.py b/modules/Facts.py index efb0cb1..c114862 100644 --- a/modules/Facts.py +++ b/modules/Facts.py @@ -25,15 +25,14 @@ from extlib import irclib from Module import Module class Facts(Module): - """ - Select a fact from the database. Facts are categorized by a name, - which may allow for random selection and so on. + + """Select a fact from the database. + + Facts are categorized by a name, which may allow for random selection and so on. """ def db_init(self): - """ - Initialize database tables. - """ + """Initialize database tables.""" # init the database if module isn't registered version = self.db_module_registered(self.__class__.__name__) @@ -58,6 +57,8 @@ class Facts(Module): raise def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): + """Add or retrieve a fact from the database.""" + whats = what.split(' ') if whats[0] == 'facts' and len(whats) >= 2: diff --git a/modules/GoogleTranslate.py b/modules/GoogleTranslate.py index 3989c30..75cf48b 100644 --- a/modules/GoogleTranslate.py +++ b/modules/GoogleTranslate.py @@ -1,18 +1,20 @@ -# GoogleTranslate - go out to google and translate sentences -# Copyright (C) 2010 Brian S. Stephan -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +""" +GoogleTranslate - go out to google and translate sentences +Copyright (C) 2010 Brian S. Stephan + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +""" from urllib2 import urlopen from urllib import urlencode @@ -21,13 +23,19 @@ from extlib import irclib from Module import Module -# Class that translates text via Google Translate. -# -# http://code.google.com/apis/ajaxlanguage/documentation/ - class GoogleTranslate(Module): + """Class that translates text via Google Translate. + + http://code.google.com/apis/ajaxlanguage/documentation/ + """ + def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked): + """Query Google for weather info. + + Leaves the input alone to let google make the best guess. + """ + whats = what.split(' ') if whats[0] == 'translate' and len(whats) >= 4: fromlang = whats[1] diff --git a/modules/IrcAdmin.py b/modules/IrcAdmin.py index 5c0b09d..e1d8ecf 100644 --- a/modules/IrcAdmin.py +++ b/modules/IrcAdmin.py @@ -1,18 +1,20 @@ -# IrcAdmin - handle normal IRC functions one would expect -# Copyright (C) 2010 Brian S. Stephan -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +""" +IrcAdmin - handle normal IRC functions one would expect +Copyright (C) 2010 Brian S. Stephan + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +""" from ConfigParser import NoOptionError import signal @@ -22,10 +24,10 @@ from extlib import irclib from Module import Module -# All kinds of miscellaneous irc stuff - class IrcAdmin(Module): + """Support miscellaneous IRC stuff --- joining channels, changing the nick, etc.""" + def register_handlers(self, server): server.add_global_handler('welcome', self.on_connect) server.add_global_handler('pubmsg', self.on_pubmsg) @@ -40,8 +42,7 @@ class IrcAdmin(Module): self.server.remove_global_handler('privmsg', self.on_privmsg) def on_connect(self, connection, event): - """handler for when the bot has connected to IRC - """ + """Set up handlers when the bot has connected to IRC.""" # user modes try: @@ -160,8 +161,8 @@ class IrcAdmin(Module): return self.reply(connection, replypath, replystr) def sub_load_module(self, connection, event, nick, userhost, replypath, what, admin_unlocked): - """ - Load a module (in both the python and dr.botzo sense) if not already loaded. + """Load a module (in both the python and dr.botzo sense) if not + already loaded. """ whats = what.split(' ') @@ -189,9 +190,7 @@ class IrcAdmin(Module): return self.reply(connection, replypath, 'Module ' + modname + ' not found.') def sub_unload_module(self, connection, event, nick, userhost, replypath, what, admin_unlocked): - """ - Attempt to unload and del a module if it's loaded. - """ + """Attempt to unload and del a module if it's loaded.""" whats = what.split(' ') modname = whats[1] @@ -216,8 +215,8 @@ class IrcAdmin(Module): return self.reply(connection, replypath, 'Module ' + modname + ' is not loaded.') def sub_reload_module(self, connection, event, nick, userhost, replypath, what, admin_unlocked): - """ - Attempt to reload a module, by removing it from memory and then re-initializing it. + """Attempt to reload a module, by removing it from memory and then + re-initializing it. """ whats = what.split(' ')