Triggers#

Triggers are how Sopel tells callables about their runtime context.

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.PreTrigger( own_nick: Identifier, line: str, url_schemes: Sequence | None = None, identifier_factory: IdentifierFactory = Identifier, statusmsg_prefixes: tuple[str, ...] = tuple(), )#

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
url_schemes (tuple) – allowed schemes for URL detection

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.

ctcp#: The CTCP command name, if present (None otherwise)

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.

Warning

The sender Will be None for commands that have no implicit channel or private-message context, for example AWAY or QUIT.

The COMMANDS_WITH_CONTEXT attribute lists IRC commands for which sender can be relied upon.

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.

urls: tuple#

List of URLs found in the text.

This is for PRIVMSG and NOTICE messages only. For other messages, this will be an empty tuple.

plain#: The last argument of the IRC command with control codes stripped.

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.

Changed in version 8.0: Now a timezone-aware datetime object.

user#: The sender’s local username.

class sopel.trigger.Trigger( settings: config.Config, message: PreTrigger, match: Match, account: str | None = 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 trigger.ctcp will contain the command (e.g. ACTION).

Note

CTCP used to be stored as the intent tag. Since message intents never made it past the IRCv3 draft stage, Sopel dropped support for them in Sopel 8.

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 list containing each of the arguments to an event.

Type:: list[str]

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 ctcp#

The CTCP command (if any).

Type:: str

Common CTCP commands are ACTION, VERSION, and TIME. Other commands include USERINFO, PING, and various DCC operations.

New in version 7.1.

Important

Use this attribute instead of the intent tag in tags. Message intents never made it past the IRCv3 draft stage, and Sopel dropped support for them in Sopel 8.

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 plugin.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 plugin.command(), plugin.action_command(), and plugin.nickname_command().

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 plain#

The text without formatting control codes.

Type:: str

This is the text of the trigger object without formatting control codes.

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.

You can check if the trigger comes from a channel or a nick with its is_nick() method:

if trigger.sender.is_nick():
    # message sent from a private message
else:
    # message sent from a channel

Important

If the message was sent to a specific status prefix, the sender does not include the status prefix. Be sure to use the status_prefix when replying.

Note that the bot argument passed to plugin callables is a SopelWrapper that handles this for the default destination of the methods it overrides (most importantly, say() & reply()).

Warning

The sender Will be None for commands that have no implicit channel or private-message context, for example AWAY or QUIT.

The COMMANDS_WITH_CONTEXT attribute lists IRC commands for which sender can be relied upon.

property status_prefix#

The prefix used for the sender for status-specific messages.

Type:: Optional[str]

This will be None by default. If a message is sent to a channel, it may have a status prefix for status-specific messages. In that case, the prefix is removed from the channel’s identifier (see sender) and saved to this attribute.

property tags#

A map of the IRCv3 message tags on the message.

Type:: dict

property time#

When the message was received.

Type:: naïve datetime object (no timezone)

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. In both cases, this time is in UTC.

property urls#

A tuple containing all URLs found in the text.

Type:: tuple

URLs are listed only for PRIVMSG or a NOTICE, otherwise this is an empty tuple.

property user#

Local username of the person who sent the message.

Type:: str

Command context#

sopel.trigger.COMMANDS_WITH_CONTEXT = frozenset({'INVITE', 'JOIN', 'KICK', 'MODE', 'NOTICE', 'PART', 'PRIVMSG', 'TOPIC'})#

Set of commands with a trigger.sender.

Most IRC messages a plugin will want to handle (channel messages and PMs) are associated with a context, exposed in the Trigger’s sender property. However, not all commands can be directly associated to a channel or nick.

For IRC message types other than those listed here, the trigger’s sender property will be None.