Slouch api

class slouch.Bot(slack_token, config)

A Bot connects to Slack using the RTM API and responds to public messages that are directed to it with username- or at-mentions.

Manage the Bot’s channels in Slack itself with the /join command. A Bot can be in multiple Slack channels (though state is not isolated by channel).

config

the same config dictionary passed to init.

id

the bot’s Slack id. Not available until prepare_connection().

log

a Logger (logging.getLogger(__name__)).

name

the bot’s Slack name. Not available until prepare_connection().

my_mention

the bot’s Slack mention, equal to <@%s> % self.id . Not available until prepare_connection().

slack

a Slacker instance created with slack_token.

ws

a WebSocketApp instance. Not available until prepare_connection().

__init__(slack_token, config)

Do not override this to perform implementation-specific setup; use prepare_bot() instead.

No IO will be done until run_forever() is called (unless prepare_bot() is overridden to perform some).

Parameters:

• slack_token – a Slack api token.
• config – an arbitrary dictionary for implementation-specific configuration. The same object is stored as the config attribute and passed to prepare methods.

prepare_bot(config)

Override to perform implementation-specific setup.

This is called once by __init__() and is not called on connection restarts.

prepare_connection(config)

Override to perform per-connection setup.

This is called by run_forever and on connection restarts.

run_forever()

Run the bot, blocking forever.

classmethod command(*args, **kwargs)

A decorator to convert a function to a command.

A command’s docstring must be a docopt usage string. See docopt.org for what it supports.

Commands receive three arguments:

• opts: a dictionary output by docopt
• bot: the Bot instance handling the command (eg for storing state between commands)
• event: the Slack event that triggered the command (eg for finding the message’s sender)

Additional options may be passed in as keyword arguments:

• name: the string used to execute the command (no spaces allowed)

They must return one of three things:

• a string of response text. It will be sent via the RTM api to the channel where the bot received the message. Slack will format it as per https://api.slack.com/docs/message-formatting.
• None, to send no response.
• a dictionary of kwargs representing a message to send via https://api.slack.com/methods/chat.postMessage. Use this to send more complex messages, such as those with custom link text or DMs. For example, to respond with a DM containing custom link text, return {‘text’: ‘<http://example.com|my text>’, ‘channel’: event[‘user’], ‘username’: bot.name}. Note that this api has higher latency than the RTM api; use it only when necessary.

classmethod help_text()

Return a slack-formatted list of commands with their usage.