Additional Tools#

Sopel provides utilities for some commonly used plugin functionality. Most of these utility features have been collected into submodules for convenience:

Miscellaneous tools that don’t fit any particular category appear below.

Useful miscellaneous tools and shortcuts for Sopel plugins

New in version 3.0.

class, stderr=False, quiet=False)#

Redirect the output to the terminal and a log file.

A simplified object used to write to both the terminal and a log file.

Deprecated since version 8.0: Vestige of old logging system. Will be removed in Sopel 8.1.


Flush the file writing buffer.


Write the given string to the logfile and terminal.


string (str) – the string to write*lazy_loaders)#

Chain lazy loaders into one.


lazy_loaders (function) – one or more lazy loader functions


a lazy loader that combines all of the given ones

Return type:


This function takes any number of lazy loaders as arguments and merges them together into one. It’s primarily a helper for lazy rule decorators such as sopel.plugin.url_lazy().

New in version 7.1.


This function doesn’t check the uniqueness of regexes generated by all the loaders.

Get a compiled regex pattern for an IRC hostmask


mask (str) – the hostmask that the pattern should match


a compiled regex pattern matching the given mask

Return type:


New in version 4.4.

Get decoded input from the terminal (equivalent to Python 3’s input).


prompt (str) – what to display as a prompt on the terminal


the user’s input

Return type:


Deprecated since version 7.1: This function will be removed in Sopel 8.1.

Return a logger for a plugin.


plugin_name (str) – name of the plugin


the logger for the given plugin


from sopel import tools
LOGGER = tools.get_logger('my_custom_plugin')

is equivalent to this:

import logging
LOGGER = logging.getLogger('sopel.externals.my_custom_plugin')

Internally, Sopel configures logging for the sopel namespace, so external plugins can’t benefit from it with logging.getLogger(__name__) as they won’t be in the same namespace. This function uses the plugin_name with a prefix inside this namespace.

New in version 7.0., max_length=400)#

Get a sendable text message, with its excess when needed.

  • txt (str) – text to send (expects Unicode-encoded string)

  • max_length (int) – maximum length of the message to be sendable


a tuple of two values, the sendable text and its excess text

Return type:

(str, str)

We’re arbitrarily saying that the (default) max is 400 bytes of text when messages will be split, but callers can specify a different value (e.g. to account precisely for the bot’s hostmask).

The max_length is the max length of text in bytes, but we take care of multibyte UTF-8 characters by working on the Unicode string, then making sure the bytes version is smaller than the max length.


In most cases, letting the bot gracefully handle message truncation using optional arguments to bot.say() is preferable. However, this function is part of the public API to provide for more advanced use-cases.

See also the bot.safe_text_length() method, whose return value can be passed as this function’s max_length argument.

New in version 6.6.2.