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.

sopel.tools#

Useful miscellaneous tools and shortcuts for Sopel plugins

New in version 3.0.

class sopel.tools.OutputRedirect(logpath, 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()#: Flush the file writing buffer.

write(string)#

Write the given string to the logfile and terminal.

Parameters:: string (str) – the string to write

sopel.tools.chain_loaders(*lazy_loaders)#

Chain lazy loaders into one.

Parameters:: lazy_loaders (function) – one or more lazy loader functions
Returns:: a lazy loader that combines all of the given ones
Return type:: function

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.

Important

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

sopel.tools.get_hostmask_regex(mask)#

Get a compiled regex pattern for an IRC hostmask

Parameters:: mask (str) – the hostmask that the pattern should match
Returns:: a compiled regex pattern matching the given mask
Return type:: re.Pattern

New in version 4.4.

sopel.tools.get_input(prompt)#

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

Parameters:: prompt (str) – what to display as a prompt on the terminal
Returns:: the user’s input
Return type:: str

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

sopel.tools.get_logger(plugin_name)#

Return a logger for a plugin.

Parameters:: plugin_name (str) – name of the plugin
Returns:: the logger for the given plugin

This:

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.

sopel.tools.get_sendable_message(text, max_length=400)#

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

Parameters:

txt (str) – text to send (expects Unicode-encoded string)
max_length (int) – maximum length of the message to be sendable

Returns:

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.

Note

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.