The bot and its state

class sopel.bot.Sopel(config, daemon=False)
nick

Sopel’s current nick. Changing this while Sopel is running is unsupported.

user

Sopel’s user/ident.

name

Sopel’s “real name”, as used for whois.

action(text, dest)

Send text as a CTCP ACTION PRIVMSG to dest.

The same loop detection and length restrictions apply as with say(), though automatic message splitting is not available.

Within the context of a triggered callable, dest will default to the channel (or nickname, if a private message), in which the trigger happened.

cap_req(module_name, capability, arg=None, failure_callback=None, success_callback=None)

Tell Sopel to request a capability when it starts.

By prefixing the capability with -, it will be ensured that the capability is not enabled. Simmilarly, by prefixing the capability with =, it will be ensured that the capability is enabled. Requiring and disabling is “first come, first served”; if one module requires a capability, and another prohibits it, this function will raise an exception in whichever module loads second. An exception will also be raised if the module is being loaded after the bot has already started, and the request would change the set of enabled capabilities.

If the capability is not prefixed, and no other module prohibits it, it will be requested. Otherwise, it will not be requested. Since capability requests that are not mandatory may be rejected by the server, as well as by other modules, a module which makes such a request should account for that possibility.

The actual capability request to the server is handled after the completion of this function. In the event that the server denies a request, the failure_callback function will be called, if provided. The arguments will be a Sopel object, and the capability which was rejected. This can be used to disable callables which rely on the capability. It will be be called either if the server NAKs the request, or if the server enabled it and later DELs it.

The success_callback function will be called upon acknowledgement of the capability from the server, whether during the initial capability negotiation, or later.

If arg is given, and does not exactly match what the server provides or what other modules have requested for that capability, it is considered a conflict.

channels = None

A map of the channels that Sopel is in.

The keys are Identifiers of the channel names, and map to sopel.tools.target.Channel objects which contain the users in the channel and their permissions.

config = None

The sopel.config.Config for the current Sopel instance.

db = None

The bot’s database, as a sopel.db.SopelDB instance.

doc = None

A dictionary of command names to their docstring and example, if declared. The first item in a callable’s commands list is used as the key in version 3.2 onward. Prior to 3.2, the name of the function as declared in the source code was used.

enabled_capabilities = None

A set containing the IRCv3 capabilities that the bot has enabled.

join(channel, password=None)

Join a channel

If channel contains a space, and no password is given, the space is assumed to split the argument into the channel to join and its password. channel should not contain a space if password is given.

memory = None

A thread-safe dict for storage of runtime data to be shared between modules. See sopel.tools.Sopel.SopelMemory

notice(text, dest)

Send an IRC NOTICE to a user or a channel.

Within the context of a triggered callable, dest will default to the channel (or nickname, if a private message), in which the trigger happened.

part(channel, msg=None)

Part a channel.

privileges = None

A dictionary of channels to their users and privilege levels

The value associated with each channel is a dictionary of sopel.tools.Identifiers to a bitwise integer value, determined by combining the appropriate constants from sopel.module.

Deprecated since version 6.2.0: Use channels instead.

reply(text, dest, reply_to, notice=False)

Prepend reply_to to text, and send as a PRIVMSG to dest.

If notice is True, send a NOTICE rather than a PRIVMSG.

The same loop detection and length restrictions apply as with say(), though automatic message splitting is not available.

Within the context of a triggered callable, reply_to will default to the nickname of the user who triggered the call, and dest to the channel (or nickname, if a private message), in which the trigger happened.

say(text, recipient, max_messages=1)

Send text as a PRIVMSG to recipient.

In the context of a triggered callable, the recipient defaults to the channel (or nickname, if a private message) from which the message was received.

By default, this will attempt to send the entire text in one message. If the text is too long for the server, it may be truncated. If max_messages is given, the text will be split into at most that many messages, each no more than 400 bytes. The split is made at the last space character before the 400th byte, or at the 400th byte if no such space exists. If the text is too long to fit into the specified number of messages using the above splitting, the final message will contain the entire remainder, which may be truncated by the server.

server_capabilities = None

A dict mapping supported IRCv3 capabilities to their options.

For example, if the server specifies the capability sasl=EXTERNAL, it will be here as {"sasl": "EXTERNAL"}. Capabilities specified without any options will have None as the value.

For servers that do not support IRCv3, this will be an empty set.

users = None

A map of the users that Sopel is aware of.

The keys are Identifiers of the nicknames, and map to sopel.tools.target.User instances. In order for Sopel to be aware of a user, it must be in at least one channel which they are also in.

write(args, text=None)

Send a command to the server.

args is an iterable of strings, which are joined by spaces. text is treated as though it were the final item in args, but is preceeded by a :. This is a special case which means that text, unlike the items in args may contain spaces (though this constraint is not checked by write).

In other words, both sopel.write(('PRIVMSG',), 'Hello, world!') and sopel.write(('PRIVMSG', ':Hello, world!')) will send PRIVMSG :Hello, world! to the server.

Newlines and carriage returns (‘n’ and ‘r’) are removed before sending. Additionally, if the message (after joining) is longer than than 510 characters, any remaining characters will not be sent.