errbot.botplugin module

class errbot.botplugin.ArgParserBase[source]

Bases: object

The ArgSplitterBase class defines the API which is used for argument splitting (used by the split_args_with parameter on botcmd()).

parse_args(args: str)[source]

This method takes a string of un-split arguments and parses it, returning a list that is the result of splitting.

If splitting fails for any reason it should return an exception of some kind.

Parameters:args (str) – string to parse
class errbot.botplugin.BotPlugin(bot, name=None)[source]

Bases: errbot.botplugin.BotPluginBase

activate() → None[source]

Triggered on plugin activation.

Override this method if you want to do something at initialization phase (don’t forget to super().activate()).

build_identifier(txtrep: str) → errbot.backends.base.Identifier[source]

Transform a textual representation of a user identifier to the correct Identifier object you can set in Message.to and Message.frm.

Return type:Identifier
Parameters:txtrep (str) – the textual representation of the identifier (it is backend dependent).
Returns:a user identifier.
callback_botmessage(message: errbot.backends.base.Message)[source]

Triggered on every message coming from the bot itself.

Override this method to get notified on all messages coming from the bot itself (including those from other plugins).

Parameters:message (Message) – An instance of Message representing the message that was received.
callback_connect() → None[source]

Triggered when the bot has successfully connected to the chat network.

Override this method to get notified when the bot is connected.

callback_mention(message: errbot.backends.base.Message, mentioned_people: Sequence[errbot.backends.base.Identifier]) → None[source]

Triggered if there are mentioned people in message.

Override this method to get notified when someone was mentioned in message. [Note: This might not be implemented by all backends.]

Parameters:
  • message (Message) – representing the message that was received.
  • mentioned_people – all mentioned people in this message.
callback_message(message: errbot.backends.base.Message) → None[source]

Triggered on every message not coming from the bot itself.

Override this method to get notified on ANY message.

Parameters:message (Message) – representing the message that was received.
callback_presence(presence: errbot.backends.base.Presence) → None[source]

Triggered on every presence change.

Parameters:presence (Presence) – An instance of Presence representing the new presence state that was received.
callback_room_joined(room: errbot.backends.base.Room)[source]

Triggered when the bot has joined a MUC.

Parameters:room (Room) – An instance of MUCRoom representing the room that was joined.
callback_room_left(room: errbot.backends.base.Room)[source]

Triggered when the bot has left a MUC.

Parameters:room (Room) – An instance of MUCRoom representing the room that was left.
callback_room_topic(room: errbot.backends.base.Room)[source]

Triggered when the topic in a MUC changes.

Parameters:room (Room) – An instance of MUCRoom representing the room for which the topic changed.
callback_stream(stream: errbot.backends.base.Stream) → None[source]

Triggered asynchronously (in a different thread context) on every incoming stream request or file transfert requests. You can block this call until you are done with the stream. To signal that you accept / reject the file, simply call stream.accept() or stream.reject() and return.

Parameters:stream (Stream) – the incoming stream request.
change_presence(status: str = 'online', message: str = '') → None[source]
Changes the presence/status of the bot.
Parameters:
  • status (str) – One of the constant defined in base.py : ONLINE, OFFLINE, DND,…
  • message (str) – Additional message
Returns:

None

check_configuration(configuration: Mapping[KT, VT_co]) → None[source]

By default, this method will do only a BASIC check. You need to override it if you want to do more complex checks. It will be called before the configure callback. Note if the config_template is None, it will never be called.

It means recusively:

  1. in case of a dictionary, it will check if all the entries and from the same type are there and not more.
  2. in case of an array or tuple, it will assume array members of the same type of first element of the template (no mix typed is supported)

In case of validation error it should raise a errbot.ValidationException

Parameters:configuration – the configuration to be checked.
configure(configuration: Mapping[KT, VT_co]) → None[source]

By default, it will just store the current configuration in the self.config field of your plugin. If this plugin has no configuration yet, the framework will call this function anyway with None.

This method will be called before activation so don’t expect to be activated at that point.

Parameters:configuration – injected configuration for the plugin.
deactivate() → None[source]

Triggered on plugin deactivation.

Override this method if you want to do something at tear-down phase (don’t forget to super().deactivate()).

get_configuration_template() → Mapping[KT, VT_co][source]

If your plugin needs a configuration, override this method and return a configuration template.

For example a dictionary like: return {‘LOGIN’ : ‘example@example.com’, ‘PASSWORD’ : ‘password’}

Note: if this method returns None, the plugin won’t be configured

query_room(room: str) → errbot.backends.base.Room[source]

Query a room for information.

Return type:Room
Parameters:room (str) – The JID/identifier of the room to query for.
Returns:An instance of MUCRoom.
Raises:RoomDoesNotExistError if the room doesn’t exist.
rooms() → Sequence[errbot.backends.base.Room][source]

The list of rooms the bot is currently in.

send(identifier: errbot.backends.base.Identifier, text: str, in_reply_to: errbot.backends.base.Message = None, groupchat_nick_reply: bool = False) → None[source]

Send a message to a room or a user.

Parameters:
  • groupchat_nick_reply (bool) – if True the message will mention the user in the chatroom.
  • in_reply_to (Message) – the original message this message is a reply to (optional). In some backends it will start a thread.
  • text (str) – markdown formatted text to send to the user.
  • identifier (Identifier) – An Identifier representing the user or room to message. Identifiers may be created with build_identifier().
send_card(body: str = '', to: errbot.backends.base.Identifier = None, in_reply_to: errbot.backends.base.Message = None, summary: str = None, title: str = '', link: str = None, image: str = None, thumbnail: str = None, color: str = 'green', fields: Tuple[Tuple[str, str], ...] = ()) → None[source]

Sends a card.

A Card is a special type of preformatted message. If it matches with a backend similar concept like on Slack or Hipchat it will be rendered natively, otherwise it will be sent as a regular formatted message.

Parameters:
  • body (str) – main text of the card in markdown.
  • to (Identifier) – the card is sent to this identifier (Room, RoomOccupant, Person…).
  • in_reply_to (Message) – the original message this message is a reply to (optional).
  • summary (str) – (optional) One liner summary of the card, possibly collapsed to it.
  • title (str) – (optional) Title possibly linking.
  • link (str) – (optional) url the title link is pointing to.
  • image (str) – (optional) link to the main image of the card.
  • thumbnail (str) – (optional) link to an icon / thumbnail.
  • color (str) – (optional) background color or color indicator.
  • fields – (optional) a tuple of (key, value) pairs.
send_stream_request(user: errbot.backends.base.Identifier, fsource: io.IOBase, name: str = None, size: int = None, stream_type: str = None)[source]

Sends asynchronously a stream/file to a user.

Parameters:
  • user (Identifier) – is the identifier of the person you want to send it to.
  • fsource (IOBase) – is a file object you want to send.
  • name (str) – is an optional filename for it.
  • size (int) – is optional and is the espected size for it.
  • stream_type (str) – is optional for the mime_type of the content.

It will return a Stream object on which you can monitor the progress of it.

send_templated(identifier: errbot.backends.base.Identifier, template_name: str, template_parameters: Mapping[KT, VT_co], in_reply_to: errbot.backends.base.Message = None, groupchat_nick_reply: bool = False) → None[source]

Sends asynchronously a message to a room or a user.

Same as send but passing a template name and parameters instead of directly the markdown text. :type groupchat_nick_reply: bool :type in_reply_to: Message :type template_name: str :type identifier: Identifier :param template_parameters: arguments for the template. :param template_name: name of the template to use. :param groupchat_nick_reply: if True it will mention the user in the chatroom. :param in_reply_to: optionally, the original message this message is the answer to. :param identifier: identifier of the user or room to which you want to send a message to.

start_poller(interval: float, method: Callable[[...], None], times: int = None, args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]

Start to poll a method at specific interval in seconds.

Note: it will call the method with the initial interval delay for the first time

Also, you can program for example : self.program_poller(self, 30, fetch_stuff) where you have def fetch_stuff(self) in your plugin

Parameters:
  • interval (float) – interval in seconds
  • method – targetted method
  • times (int) – number of times polling should happen (defaults to``None`` which causes the polling to happen indefinitely)
  • args – args for the targetted method
  • kwargs – kwargs for the targetting method
stop_poller(method: Callable[[...], None], args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]

stop poller(s).

If the method equals None -> it stops all the pollers you need to regive the same parameters as the original start_poller to match a specific poller to stop

Parameters:
  • kwargs – The initial kwargs you gave to start_poller.
  • args – The initial args you gave to start_poller.
  • method – The initial method you passed to start_poller.
warn_admins(warning: str) → None[source]

Send a warning to the administrators of the bot.

Parameters:warning (str) – The markdown-formatted text of the message to send.
class errbot.botplugin.BotPluginBase(bot, name=None)[source]

Bases: errbot.storage.StoreMixin

This class handle the basic needs of bot plugins like loading, unloading and creating a storage It is the main contract between the plugins and the bot

__init__(bot, name=None)[source]

Initialize self. See help(type(self)) for accurate signature.

activate() → None[source]

Override if you want to do something at initialization phase (don’t forget to super(Gnagna, self).activate())

bot_config

Get the bot configuration from config.py. For example you can access: self.bot_config.BOT_DATA_DIR

bot_identifier

Get bot identifier on current active backend.

:return Identifier

create_dynamic_plugin(name: str, commands: Tuple[errbot.botplugin.Command], doc: str = '')[source]

Creates a plugin dynamically and exposes its commands right away.

Parameters:
  • name (str) – name of the plugin.
  • commands – a tuple of command definition.
  • doc (str) – the main documentation of the plugin.
deactivate() → None[source]

Override if you want to do something at tear down phase (don’t forget to super(Gnagna, self).deactivate())

destroy_dynamic_plugin(name: str)[source]

Reverse operation of create_dynamic_plugin.

This allows you to dynamically refresh the list of commands for example. :type name: str :param name: the name of the dynamic plugin given to create_dynamic_plugin.

get_plugin(name) → errbot.botplugin.BotPlugin[source]

Gets a plugin your plugin depends on. The name of the dependency needs to be listed in [Code] section key DependsOn of your plug file. This method can only be used after your plugin activation (or having called super().activate() from activate itself). It will return a plugin object.

Parameters:name – the name
Returns:the BotPlugin object requested.
init_storage() → None[source]
mode

Get the current active backend.

Returns:the mode like ‘tox’, ‘xmpp’ etc…
name

Get the name of this plugin as described in its .plug file.

Returns:The plugin name.
poller(interval: float, method: Callable[[...], None], times: int = None, args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]
program_next_poll(interval: float, method: Callable[[...], None], times: int = None, args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]
start_poller(interval: float, method: Callable[[...], None], times: int = None, args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]

Starts a poller that will be called at a regular interval

Parameters:
  • interval (float) – interval in seconds
  • method – targetted method
  • times (int) – number of times polling should happen (defaults to``None`` which causes the polling to happen indefinitely)
  • args – args for the targetted method
  • kwargs – kwargs for the targetting method
stop_poller(method: Callable[[...], None], args: Tuple = None, kwargs: Mapping[KT, VT_co] = None)[source]
class errbot.botplugin.Command(function, cmd_type=None, cmd_args=None, cmd_kwargs=None, name=None, doc=None)[source]

Bases: object

This is a dynamic definition of an errbot command.

__init__(function, cmd_type=None, cmd_args=None, cmd_kwargs=None, name=None, doc=None)[source]

Create a Command definition.

Parameters:
  • function – a function or a lambda with the correct signature for the type of command to inject for example def mycmd(plugin, msg, args) for a botcmd. Note: the first parameter will be the plugin itself (equivalent to self).
  • cmd_type – defaults to botcmd but can be any decorator function used for errbot commands.
  • cmd_args – the parameters of the decorator.
  • cmd_kwargs – the kwargs parameter of the decorator.
  • name – defaults to the name of the function you are passing if it is a first class function or needs to be set if you use a lambda.
  • doc – defaults to the doc of the given function if it is a first class function. It can be set for a lambda or overridden for a function with this.
exception errbot.botplugin.CommandError(reason: str, template: str = None)[source]

Bases: Exception

Use this class to report an error condition from your commands, the command did not proceed for a known “business” reason.

__init__(reason: str, template: str = None)[source]
Parameters:
  • reason (str) – the reason for the error in the command.
  • template (str) – apply this specific template to report the error.
class errbot.botplugin.SeparatorArgParser(separator: str = None, maxsplit: int = -1)[source]

Bases: errbot.botplugin.ArgParserBase

This argument splitter splits args on a given separator, like str.split() does.

__init__(separator: str = None, maxsplit: int = -1)[source]
Parameters:
  • separator (str) – The separator on which arguments should be split. If sep is None, any whitespace string is a separator and empty strings are removed from the result.
  • maxsplit (int) – If given, do at most this many splits.
parse_args(args: str)[source]

This method takes a string of un-split arguments and parses it, returning a list that is the result of splitting.

If splitting fails for any reason it should return an exception of some kind.

Parameters:args (str) – string to parse
class errbot.botplugin.ShlexArgParser[source]

Bases: errbot.botplugin.ArgParserBase

This argument splitter splits args using posix shell quoting rules, like shlex.split() does.

parse_args(args)[source]

This method takes a string of un-split arguments and parses it, returning a list that is the result of splitting.

If splitting fails for any reason it should return an exception of some kind.

Parameters:args – string to parse
exception errbot.botplugin.ValidationException[source]

Bases: Exception

errbot.botplugin.recurse_check_structure(sample, to_check)[source]