Skip to main content

Simple framework for creating IRC bots

Project description

Simple framework for creating IRC bots.


from pyromancer.objects import Pyromancer

HOST = ''
PORT = 6667
NICK = 'PyromancerBot'

settings = {'host': HOST, 'port': PORT, 'nick': NICK, 'encoding': 'ISO-8859-1',
            'packages': ['.test_examples']}

p = Pyromancer(settings)

Custom commands

Writing own commands is fairly simple. Create a folder which will be the package name, with a folder named “commands” in it and a module to hold the commands in there. In your module, you can register functions to be a command with the built-in command decorator. After that you need to register it in your settings, and you can use it.


File layout:


from pyromancer.decorators import command

@command(r'bye (.*)')
def bye(match):
    return 'Bye {m[1]}!'

settings['packages'] = ['test.test_commands']


<User> bye everyone
<Bot> Bye everyone!

Pyromancer scans the modules in the settings automatically for functions decorated using the commands decorator, so all your commands in are used automatically.

The command decorator

You must apply this to a function to mark it as a command. It will be used when scanning for and collecting commands.


  • patterns - a regular expression or a list of expressions. When a list is given, all patterns are attempted when matching the input, and only when all patterns in the list fail to match, the command is not executed.

    @command(['hi', 'hello'])
    def hi(match):
        return 'Hello!'
  • prefix - a boolean which defaults to True. When true, the command pattern is only attempted to match when the message line starts with the prefix defined in the settings of the bot. This is useful for commands which are very bot-like (in contrary to commands which look and behave like natural language). Using a boolean and a setting allows the same command to be triggered in different ways, depending on the settings of the bot which installed the command package.

Messaging from a command

Messaging from inside the function which makes up the command is as easy as can be for simple use cases, but can be done in numerous ways for the more complex situations.

Most of the times, arguments are passed to the Match.msg function, which applies formatting by default and provides some additional utilities. The most important of those is that when no target has been passed on as an argument, it will use either the channel or the user (in case of a PM) whose input line triggered the command to be executed as the target, effectively replying.


  • message - the message to be send to the server. Formatting will be applied using any additional args and kwargs, so you can apply the full power of the Python Format Mini-Language on the message.
  • args and kwargs - arguments to be passed on through the formatting which is applied on message.

Methods of messaging

  • Return a message

    @command(r'bye (.*)')
    def bye(match):
        return 'Bye {m[1]}!'
  • Return a tuple of message and optional args and kwargs to be used when formatting message. args can be both a list of arguments, or simply all the middle elements of the tuple.

    def gibberish(match):
        return 'A = {}, B = {}, C = {c_char}', 'a', 'b', {'c_char': 'c'}
  • Yield a message or a tuple of message and optional args and kwargs. Yielding can be done as much as you want, which is the easiest way of sending multiple messages from one command.

    @command(r'say (.*)')
    def say(match):
        for part in match[1].split(', '):
            yield 'Saying {}', part
  • Return a list of message or a tuple of message and optional args and kwargs.

    def hi(match):
        return ['Hi', 'Hello']
  • Use Match.msg. This is the only way to benefit from the non-default functionalities provided by this function.

    def raw(match):
        match.msg('Raw {} message {m[1]}', raw=True)

Extra parameters for Match.msg

  • target - the target to send the message to. If not provided, it will attempt to use either the channel or user whose input line triggered the command, which effectively results in replying.
  • raw - defaults to False. When true, no formatting is applied on message.


To do

  • Ability to process raw lines through custom commands
  • Figure out how to do translation of messages through the Match.msg function.
  • Add timers
  • Make a module of settings (like Django), with settings for each installed package prioritized based on place in packages setting (not like Django).
  • Add a command module which keeps track of channels joined and users in them which other commands can use.
  • Redo commands loading so you can use for custom commands instead of a mandatory commands directory.
  • Redo package loading so you just have to specify the package name and it loads the commands and any future things like settings.


0.2 - 2014-03-14

  • Add tests
  • Add multiple and easier ways to send messages from a command.
  • Add support for multiple patterns for the same command.
  • Add a configurable command prefix setting for the more bot-like commands.
  • Trying to access a word in a Line now correctly returns an empty string when the index does not exist.
  • Fix passing positional arguments to Match.msg not working properly.

0.1 - 2013-11-17

  • Initial release

Project details

Release history Release notifications

History Node


History Node


History Node


This version
History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
Pyromancer-0.2.tar.gz (7.1 kB) Copy SHA256 hash SHA256 Source None Mar 22, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page