Cardinal Methods

To avoid making you deal with Twisted's IRCClient implementation details, the CardinalBot class contains a few methods that are useful for plugin developers. These are accessible via the first argument passed to your commands (i.e. cardinal).

Sending messages

CardinalBot.sendMsg() lets you send a message to a channel or user.

Wrapper command to send messages.

Keyword arguments:
  channel -- Channel to send message to.
  message -- Message to send.
  length -- Length of message. Twisted will calculate if None given.

Raw messages

CardinalBot.send() can be used to send a raw message to the server.

Send a raw message to the server.

Keyword arguments:
  message -- Message to send.

Fetching configuration

CardinalBot.config() allows you to access the current state of configuration of any loaded plugin. DO NOT CALL THIS IN PLUGIN CONSTRUCTORS as CardinalBot.config() will not yet be loaded. It can however be called within other methods of your plugin (such as when responding to a command) to view the config values of other loaded plugins. You can find an example in the standard help plugin, where we look for bot owners specified in the admin plugin's config.

Returns a given loaded plugin's config.

Keyword arguments:
  plugin -- String containing a plugin name.

Returns:
  dict -- Dictionary containing plugin config.

Raises:
  ConfigNotFoundError - When config can't be found for the plugin.

Disconnecting from the server

CardinalBot.disconnect() safely disconnects from the network.

Wrapper command to quit Cardinal.

Keyword arguments:
  message -- Message to insert into QUIT, if any.

Receiving the user list for a channel

CardinalBot.who() allows you to request a list of users from the server. This method returns a Deferred with a result set to a list of user tuples: [(nick, ident, hostname), ...]

Lists the users in a channel.

Keyword arguments:
  channel -- A channel to list users of.

For example, you might do something like this in order to send a list of users in a channel to the channel/PM that the list was requested in:

from twisted.internet import defer
from cardinal.decorators import command

class WhoPlugin(object):
    @command('who')
    @defer.inlineCallbacks
    def who(self, cardinal, user, channel, msg):
        target = msg.split(' ')[1]

        users = yield cardinal.who(target)
        for user in users:
            cardinal.sendMsg(channel, "%s!%s@%s" % (user[0], user[1], user[2]))


def setup():
    return WhoPlugin()