• Once deployed, no need to reload hubot when editing or adding scripts!

Simply copy the contents of this repository to your bot's scripts folder and reload your bot.

Edit exec.py in order to change configuration values to desired specifications.

Default: inactive

Allows connection to an existing Redis instance for data persistence across command execution.

Default: general

Logging messages (using the built-in logger) will be sent to this room.

Default: 2 (errors and warnings)

Options:

1 - Errors only
2 - Warnings and the above
3 - Informational messages and all of the above
4 - Debug messages and all of the above

See the Triggers section below for details.

Default:
/usr/lib/python3.5
/usr/lib/python3.5/lib-dynload
/usr/lib/python3.5/plat-i386-linux-gnu
/usr/lib/python3/dist-packages
/usr/lib/python35.zip

Allows the python process to include custom locations where to search for modules.

To get a list of local paths in a particular machine, run the following commands in the Python interpreter:

>>> from sys import path
>>> for p in path:
...     print(p)
...

/usr/lib/python3.5
/usr/lib/python3.5/lib-dynload
/usr/lib/python3.5/plat-i386-linux-gnu
/usr/lib/python3/dist-packages
/usr/lib/python35.zip

Simply create new python script file under bot_commands where the file name is the command to be executed.

For example, to create a command that responds to marco with polo:

• Create the file bot_commands/marco.py
• Modify the contents of the file to be:

def execute(**kwargs):
    print('polo')

That's it!

Now every time someone says marco in a room where the bot is active, the bot will reply with polo.

Please note: commands will only execute if the message starts with the command itself.
E.g., Marco 123 will trigger the script; hello there, Marco will not.

room      = kwargs['room'     ] # The room where the message was posted
username  = kwargs['username' ] # The user who posted the message
command   = kwargs['command'  ] # The command used to execute the script
arguments = kwargs['arguments'] # The list of arguments (i.e., each word in the rest of the message)
bot_name  = kwargs['bot_name' ] # The bot who is handling the message
direct    = kwargs['direct'   ] # Whether the bot was mentioned in the message (e.g., @bot)
redis     = kwargs['redis'    ] # The connected redis object
logger    = kwargs['logger'   ] # The built-in logger object

Simply create new python script file under bot_commands and make the necessary changes in exec.py.

For example, to create a command that responds to marco with polo:

• Create the file bot_commands/say_polo.py
• Modify the contents of the file to be:

def execute(**kwargs):
    print('polo')

• Within exec.py, declare the trigger within the trigger_scripts variable:

# If a sentence does not begin with a command but is matched
# by any of the following regular expressions (with flags),
# execute the indicated script.
trigger_scripts = {
    # Example: anytime 'marco' is found in a sentence,
    # regardless of case, bot_commands/say_polo.py will be executed
    Trigger('marco', re.I): 'say_polo',
    }

Now every time someone says marco in a room where the bot is active, the bot will reply with polo.

Please note: triggers will execute if a particular word is found anywhere in the message.
E.g., hello there, Marco will trigger the script.

room     = kwargs['room'    ] # The room where the message was posted
username = kwargs['username'] # The user who posted the message
message  = kwargs['message' ] # The entire message sent by the user
trigger  = kwargs['trigger' ] # The regex match responsible for triggering the script
bot_name = kwargs['bot_name'] # The bot who is handling the message
direct   = kwargs['direct'  ] # Whether the bot was mentioned in the message (e.g., @bot)
redis    = kwargs['redis'   ] # The connected redis object
logger   = kwargs['logger'  ] # The built-in logger object

To print usage guidance when a user requests help (e.g., @bot help), simply add a help() function to your command or trigger script:

def help(**kwargs):
    print('marco: respond with "polo"')

bot_name = kwargs['bot_name'] # The bot who is handling the message
username = kwargs['username'] # The user who posted the message

To log messages to the log room (see the Log room section for information on configuring it), use the built-in logger object to send Python logging events:

logger = kwargs['logger']
logger.debug  ('Debug message'        )
logger.info   ('Informational message')
logger.warning('Warning message'      )
logger.error  ('Error message'        )

In addition to Python's logging functions, there is a status() function will be issued regardless of the logging level (verbosity): logger.status('This will post regardless of verbosity!')

If any of the scripts created under bot_commands/ encounter errors, these errors will never be printed to chat unless explicitly sent:

x = 1/0 # No message sent here
try:
    x = 1/0
except ZeroDivisionError as zde:
    logger.error('Whoops! {}'.format(zde)) # Message sent here

Given a pre-existing Redis instance and a proper connection, scripts under bot_commands/ can use the built-in redis object to retrieve and store information from Redis:

redis = kwargs['redis']

# Post all available keys in the active Redis instance
print(redis.keys())

# Set 'polo' as the value for the 'marco' key
redis.set('marco', 'polo')

# Post the value of the 'marco' key
print(redis.get('marco'))

To send messages to different rooms, specify the room name followed by <+[: print('{} <+[ Hello!'.format('other_room'))

If you know the room ID of a direct message room, you can use it to have the bot send a DM. This can be a good option to act as a log room.

To issue a log message as a multi-line code block, surround the message with 2 backticks:

logger.debug('''
``
test: one
test: two
``
''')

This is due to the fact that logging messages are already formatted to have a single backtick by default.