Additional Tools#

sopel.tools#

Useful miscellaneous tools and shortcuts for Sopel plugins

Availability: 3+

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.

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().

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

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: Use of this function will become a warning when Python 2 support is dropped in Sopel 8.0. The 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.

New in version 6.6.2.