Triggers

A Trigger is the main type of user input plugins will see.

Sopel uses PreTriggers internally while processing incoming IRC messages. Plugin authors can reasonably expect that their code will never receive one. They are documented here for completeness, and for the aid of Sopel’s core development.

class sopel.trigger.Trigger(config, message, match, account=None)

A line from the server, which has matched a callable’s rules.

Parameters
  • config (Config) – Sopel’s current configuration settings object

  • message (PreTrigger) – the message that matched the callable

  • match (Match object) – what in the message matched

  • account (str) – services account name of the message’s sender (optional; only applies on networks with the account-tag capability enabled)

A Trigger object itself can be used as a string; when used in this way, it represents the matching line’s full text.

The match is based on the matching regular expression rule; Sopel’s command decorators auto-generate rules containing specific numbered groups that are documented separately. (See group below.)

Note that CTCP messages (PRIVMSGes and NOTICEes which start and end with '\x01') will have the '\x01' bytes stripped, and the command (e.g. ACTION) placed mapped to the 'intent' key in Trigger.tags.

property account

The services account name of the user sending the message.

Type

str or None

Note: This is only available if the account-tag capability or both the account-notify and extended-join capabilities are available on the connected IRC network. If this is not the case, or if the user sending the message isn’t logged in to services, this property will be None.

property admin

Whether the triggering nick is one of the bot’s admins.

Type

bool

True if the triggering nick is a Sopel admin; False if not.

Note that Sopel’s owner is also considered to be an admin.

property args

A tuple containing each of the arguments to an event.

Type

tuple

These are the strings passed between the event name and the colon. For example, when setting mode -m on the channel #example, args would be ('#example', '-m')

property event

The IRC event which triggered the message.

Type

str

Most plugin callables primarily need to deal with PRIVMSG. Other event types like NOTICE, NICK, TOPIC, KICK, etc. must be requested using module.event().

property group

The group() function of the match attribute.

Type

method

Return type

str

Any regular-expression rules attached to the triggered callable() may define numbered or named groups that can be retrieved through this property.

Sopel’s command decorators each define a predetermined set of numbered groups containing fragments of the line that plugins commonly use.

See also

For more information on predefined numbered match groups in commands, see module.commands(), module.action_commands(), and module.nickname_commands().

Also see Python’s re.Match.group() documentation for details about this method’s behavior.

property groupdict

The groupdict() function of the match attribute.

Type

method

Return type

dict

See Python’s re.Match.groupdict() documentation for details.

property groups

The groups() function of the match attribute.

Type

method

Return type

tuple

See Python’s re.Match.groups() documentation for details.

property host

The hostname of the person who sent the message.

Type

str

property hostmask

Hostmask of the person who sent the message as <nick>!<user>@<host>.

Type

str

property is_privmsg

Whether the message was triggered in a private message.

Type

bool

True if the trigger was received in a private message; False if it came from a channel.

property match

The Match object for the triggering line.

Type

Match object

property nick

The nickname who sent the message.

Type

Identifier

property owner

Whether the nick which triggered the command is the bot’s owner.

Type

bool

True if the triggering nick is Sopel’s owner; False if not.

property raw

The entire raw IRC message, as sent from the server.

Type

str

This includes the CTCP \x01 bytes and command, if they were included.

property sender

Where the message arrived from.

Type

Identifier

This will be a channel name for “regular” (channel) messages, or the nick that sent a private message.

property tags

A map of the IRCv3 message tags on the message.

Type

dict

property time

When the message was received.

Type

datetime object

If the IRC server supports server-time, time will give that value. Otherwise, time will use the time when the message was received by Sopel.

property user

Local username of the person who sent the message.

Type

str

class sopel.trigger.PreTrigger(own_nick, line)

A parsed raw message from the server.

Parameters
  • own_nick (str) – the bot’s own IRC nickname

  • line (str) – the full line from the server

At the PreTrigger stage, the line has not been matched against any rules yet. This is what Sopel uses to perform matching.

own_nick is needed to correctly parse who sent the line (Sopel or someone else).

line can also be a simulated echo-message, useful if the connected server does not support the capability.

args

The IRC command’s arguments.

These are split on spaces, per the IRC protocol.

event

The IRC command name or numeric value.

See sopel.tools.events for a built-in mapping of names to numeric values.

host

The sender’s hostname.

hostmask

The sender’s hostmask, as sent by the IRC server.

line

The raw line received from the server.

nick

The nickname that sent this command.

sender

Channel name or query where this message was received.

tags

Any IRCv3 message tags attached to the line, as a dict.

text

The last argument of the IRC command.

If the line contains :, text will be the text following it.

For lines that do not contain :, text will be the last argument in args instead.

time

The time when the message was received.

If the IRC server sent a message tag indicating when it received the message, that is used instead of the time when Sopel received it.

user

The sender’s local username.