Commands

Defines the decorators for bot commands.

Decorators

@irc_api.commands.command(name: str, alias: tuple = (), desc: str = '')

Create a new bot’s command. Note that’s a decorator.

Parameters

namestr: The name of the command; i.e. the string by which the command will be called.
aliastuple, optionnal: The others name by which the command will be called (in addition to the given name). This parameter can be left empty if the command has no alias.
descstr, optionnal: This is the description of the command. It allows you to make an auto-generated documentation with this field.

Returns

decoratorfunction: This function take in argument the function you want to transform into a command and returns a BotCommand’s instance.

Examples

For example, assuming the module was imported as follow: from irc_api import commands You can make a command:

@commands.command(name="ping", desc="Answer 'pong' when the user enters 'ping'.")
def foo(bot, message):
    bot.send(message.to, "pong")

@irc_api.commands.channel(channel_name: str, desc: str = '')

Allow to create a command when the message come from a given channel. This decorator can be used with another one to have more complex commands.

Parameters

channel_namestr: The channel’s name on which the command will be called.
descstr, optionnal: This is the description of the command. It allows you to make an auto-generated documentation with this field.

Returns

decoratorfunction: This function take in argument the function you want to transform into a command and returns a BotCommand’s instance.

Examples

Assuming the module was imported as follow: from irc_api import commands If you want to react on every message on a specific channel, you can make a command like:

@commands.channel(channel_name="bot-test", desc="The bot will react on every message post on #bot-test")
def spam(bot, message):
    bot.send("#bot-test", "This is MY channel.")

You can also cumulate this decorator with @commands.command, @commands.on and @commands.user:

@commands.channel(channel_name="bot-test") # note that the description given here isn't taken into account
@commands.command(name="troll", desc="Some troll command")
def troll_bot(bot, message):
    emotions = ("happy", "sad", "angry")
    bot.send("#bot-test", f"*{choice(emotions)} troll's noises*")

@irc_api.commands.every(time: float, desc='')

This is not a command but it allows you to call some routines at regular intervals.

Parameters

timefloat

The time in seconds between two calls.

descstr, optionnal: This is the description of the command. It allows you to make an auto-generated documentation with this field.

Returns

decoratorfunction: This function take in argument the function you want to transform into a command and returns a BotCommand’s instance.

Examples

Assuming the module was imported as follow: from irc_api import commands. You can make a routine:

@commands.every(time=5, desc="This routine says 'hello' on #general every 5 seconds")
def spam(bot, message):
    bot.send("#general", "Hello there!") # please don't do that (.><)'

@irc_api.commands.on(event, desc: str = '')

Make a command on a custom event. It can be useful if you want to have a complex calling processus. Such as a regex recognition or a specific pattern. This decorator allows you to call a command when a specific event is verified.

You can use several @commands.on on one function.

Parameters

eventfunction: The event function should take the processed message (please refer to irc_api.irc.Message for more informations) in argument and returns a bool’s instance.
descstr, optionnal: This is the description of the command. It allows you to make an auto-generated documentation with this field.

Returns

decoratorfunction: This function take in argument the function you want to transform into a command and returns a BotCommand’s instance.

Examples

Assuming the module was imported as follow: from irc_api import commands You can make a new command:

@commands.on(lambda m: isinstance(re.match(r"(.*)(merci|merci beaucoup|thx|thanks|thank you)(.*)", m.text, re.IGNORECASE), re.Match))
def thanks(bot, message):
    bot.send(message.to, f"You're welcome {message.author}! ;)")

@irc_api.commands.user(user_name: str, desc: str = '')

Allow to create a command when the message come from a given user. This decorator can be used with another one to have more complex commands.

Parameters

user_namestr: The user’s name on which the command will be called.
descstr, optionnal: This is the description of the command. It allows you to make an auto-generated documentation with this field.

Returns

decoratorfunction: This function take in argument the function you want to transform into a command and returns a BotCommand’s instance.

Examples

Assuming the module was imported as follow: from irc_api import commands. If you want to react on every message from a specific user, you can make a command like:

@commands.user(user_name="my_pseudo", desc="The bot will react on every message post by my_pseudo")
def spam(bot, message):
    bot.send(message.to, "I subscribe to what my_pseudo said.")

You can also cumulate this decorator with @commands.command, @commands.on and @commands.channel:

@commands.user(user_name="my_pseudo")
@commands.command(name="test", desc="Some test command.")
def foo(bot, message):
    bot.send(message.to, "Test received, my_pseudo.")