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()
).
-
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 ofMessage
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.
- 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 ofPresence
representing the new presence state that was received.
-
callback_reaction
(reaction: errbot.backends.base.Reaction) → None[source]¶ Triggered on every reaction event.
Parameters: reaction ( Reaction
) – An instance ofReaction
representing the new reaction event that was received.
-
callback_room_joined
(room: errbot.backends.base.Room, identifier: errbot.backends.base.Identifier, invited_by: Optional[errbot.backends.base.Identifier] = None)[source]¶ Triggered when a user has joined a MUC.
Parameters: - room (
Room
) – An instance ofMUCRoom
representing the room that was joined. - identifier (
Identifier
) – An instance of Identifier (Person). Defaults to bot - invited_by – An instance of Identifier (Person). Defaults to None
- room (
-
callback_room_left
(room: errbot.backends.base.Room, identifier: errbot.backends.base.Identifier, kicked_by: Optional[errbot.backends.base.Identifier] = None)[source]¶ Triggered when a user has left a MUC.
Parameters: - room (
Room
) – An instance ofMUCRoom
representing the room that was left. - identifier (
Identifier
) – An instance of Identifier (Person). Defaults to bot - kicked_by – An instance of Identifier (Person). Defaults to None
- room (
-
callback_room_topic
(room: errbot.backends.base.Room)[source]¶ Triggered when the topic in a MUC changes.
Parameters: room ( Room
) – An instance ofMUCRoom
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 transfer request. 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
- status (
-
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:
- in case of a dictionary, it will check if all the entries and from the same type are there and not more.
- 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.
-
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 withbuild_identifier()
.
- groupchat_nick_reply (
-
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.
- body (
-
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.
- user (
-
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
- interval (
-
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.
-
-
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
-
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.
- name (
-
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.
-
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
- interval (
-
-
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.
-
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.
-
class
errbot.botplugin.
ShlexArgParser
[source]¶ Bases:
errbot.botplugin.ArgParserBase
This argument splitter splits args using posix shell quoting rules, like
shlex.split()
does.