errbot.backends.base module

class errbot.backends.base.Backend(_)[source]

Bases: abc.ABC

Implements the basic Bot logic (logic independent from the backend) and leaves you to implement the missing parts.

MSG_ERROR_OCCURRED = 'Sorry for your inconvenience. An unexpected error occurred.'
__init__(_)[source]

Those arguments will be directly those put in BOT_IDENTITY

build_identifier(text_representation: str) → errbot.backends.base.Identifier[source]
build_message(text: str) → errbot.backends.base.Message[source]

You might want to override this one depending on your backend

build_reply(msg: errbot.backends.base.Message, text: str = None, private: bool = False, threaded: bool = False)[source]

Should be implemented by the backend

callback_presence(presence: errbot.backends.base.Presence) → None[source]

Implemented by errBot.

callback_room_joined(room: errbot.backends.base.Room) → None[source]

See ErrBot

callback_room_left(room: errbot.backends.base.Room) → None[source]

See ErrBot

callback_room_topic(room: errbot.backends.base.Room) → None[source]

See ErrBot

change_presence(status: str = 'online', message: str = '') → None[source]

Signal a presence change for the bot. Should be overridden by backends with a super().send_message() call.

cmd_history = {}
connect() → Any[source]

Connects the bot to server or returns current connection

connect_callback() → None[source]
disconnect_callback() → None[source]
is_from_self(msg: errbot.backends.base.Message) → bool[source]

Needs to be overridden to check if the incoming message is from the bot itself.

Return type:bool
Parameters:msg (Message) – The incoming message.
Returns:True if the message is coming from the bot.
mode
prefix_groupchat_reply(message: errbot.backends.base.Message, identifier: errbot.backends.base.Identifier)[source]

Patches message with the conventional prefix to ping the specific contact For example: @gbin, you forgot the milk !

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

Query a room for information.

Return type:Room
Parameters:room (str) – The room to query for.
Returns:An instance of Room.
reset_reconnection_count() → None[source]

Reset the reconnection count. Back-ends should call this after successfully connecting.

rooms

Return a list of rooms the bot is currently in.

Returns:A list of Room instances.
send_message(msg: errbot.backends.base.Message) → None[source]

Should be overridden by backends with a super().send_message() call.

serve_forever() → None[source]

Connect the back-end to the server and serve forever.

Back-ends MAY choose to re-implement this method, in which case they are responsible for implementing reconnection logic themselves.

Back-ends SHOULD trigger connect_callback() and disconnect_callback() themselves after connection/disconnection.

serve_once() → None[source]

Connect the back-end to the server and serve a connection once (meaning until disconnected for any reason).

Back-ends MAY choose not to implement this method, IF they implement a custom serve_forever().

This function SHOULD raise an exception or return a value that evaluates to False in order to signal something went wrong. A return value that evaluates to True will signal the bot that serving is done and a shut-down is requested.

class errbot.backends.base.Card(body: str = '', frm: errbot.backends.base.Identifier = None, to: errbot.backends.base.Identifier = None, parent: errbot.backends.base.Message = None, summary: str = None, title: str = '', link: str = None, image: str = None, thumbnail: str = None, color: str = None, fields: Tuple[Tuple[str, str]] = ())[source]

Bases: errbot.backends.base.Message

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 message formatted with the card.md template.

__init__(body: str = '', frm: errbot.backends.base.Identifier = None, to: errbot.backends.base.Identifier = None, parent: errbot.backends.base.Message = None, summary: str = None, title: str = '', link: str = None, image: str = None, thumbnail: str = None, color: str = None, fields: Tuple[Tuple[str, str]] = ())[source]

Creates a Card. :type color: str :type thumbnail: str :type image: str :type link: str :type title: str :type summary: str :type parent: Message :type to: Identifier :type frm: Identifier :type body: str :param body: main text of the card in markdown. :param frm: the card is sent from this identifier. :param to: the card is sent to this identifier (Room, RoomOccupant, Person…). :param parent: the parent message this card replies to. (threads the message if the backend supports it). :param summary: (optional) One liner summary of the card, possibly collapsed to it. :param title: (optional) Title possibly linking. :param link: (optional) url the title link is pointing to. :param image: (optional) link to the main image of the card. :param thumbnail: (optional) link to an icon / thumbnail. :param color: (optional) background color or color indicator. :param fields: (optional) a tuple of (key, value) pairs.

color
fields
image
summary
text_color
thumbnail
title
class errbot.backends.base.Identifier[source]

Bases: abc.ABC

This is just use for type hinting representing the Identifier contract, NEVER TRY TO SUBCLASS IT OUTSIDE OF A BACKEND, it is just here to show you what you can expect from an Identifier. To get an instance of a real identifier, always use the properties from Message (to, from) or self.build_identifier

to make an identifier from a String.

The semantics is anything you can talk to: Person, Room, RoomOccupant etc.

class errbot.backends.base.Message(body: str = '', frm: errbot.backends.base.Identifier = None, to: errbot.backends.base.Identifier = None, parent: Optional[errbot.backends.base.Message] = None, delayed: bool = False, partial: bool = False, extras: Mapping[KT, VT_co] = None, flow=None)[source]

Bases: object

A chat message.

This class represents chat messages that are sent or received by the bot.

__init__(body: str = '', frm: errbot.backends.base.Identifier = None, to: errbot.backends.base.Identifier = None, parent: Optional[errbot.backends.base.Message] = None, delayed: bool = False, partial: bool = False, extras: Mapping[KT, VT_co] = None, flow=None)[source]
Parameters:
  • body (str) – The markdown body of the message.
  • extras – Extra data attached by a backend
  • flow – The flow in which this message has been triggered.
  • parent – The parent message of this message in a thread. (Not supported by all backends)
  • partial (bool) – Indicates whether the message was obtained by breaking down the message to fit the MESSAGE_SIZE_LIMIT.
body

Get the plaintext body of the message.

Returns:The body as a string.
clone()[source]
delayed
extras
flow

Get the conversation flow for this message.

Returns:A Flow
frm

Get the sender of the message.

Returns:An Identifier identifying the sender.
is_direct
is_group
is_threaded
parent
partial
to

Get the recipient of the message.

Returns:A backend specific identifier representing the recipient.
class errbot.backends.base.Person[source]

Bases: errbot.backends.base.Identifier

This is just use for type hinting representing the Identifier contract, NEVER TRY TO SUBCLASS IT OUTSIDE OF A BACKEND, it is just here to show you what you can expect from an Identifier. To get an instance of a real identifier, always use the properties from Message (to, from) or self.build_identifier

to make an identifier from a String.
aclattr
Returns:returns the unique identifier that will be used for ACL matches.
client
Returns:a backend specific unique identifier representing the device or client the person is using to talk.
email

Some backends have the email of a user.

Returns:the email of this user if available.
fullname

Some backends have the full name of a user.

Returns:the fullname of this user if available.
nick
Returns:a backend specific nick returning the nickname of this person if available.
person
Returns:a backend specific unique identifier representing the person you are talking to.
class errbot.backends.base.Presence(identifier: errbot.backends.base.Identifier, status: str = None, message: str = None)[source]

Bases: object

This class represents a presence change for a user or a user in a chatroom.

Instances of this class are passed to callback_presence() when the presence of people changes.

__init__(identifier: errbot.backends.base.Identifier, status: str = None, message: str = None)[source]

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

identifier

Identifier for whom its status changed. It can be a RoomOccupant or a Person. :return: the person or roomOccupant

message

Returns a human readable message associated with the status if any. like : “BRB, washing the dishes” It can be None if it is only a general status update (see get_status)

status

Returns the status of the presence change. It can be one of the constants ONLINE, OFFLINE, AWAY, DND, but can also be custom statuses depending on backends. It can be None if it is just an update of the status message (see get_message)

class errbot.backends.base.Reaction(reactor: errbot.backends.base.Identifier = None, reacted_to_owner: errbot.backends.base.Identifier = None, action: str = None, timestamp: str = None, reaction_name: str = None, reacted_to: Mapping[KT, VT_co] = None)[source]

Bases: object

This class represents a reaction event, either an added or removed reaction, to some message or object.

Instances of this class are passed to callback_reaction() when the reaction event is received.

Note: Reactions, at the time of implementation, are only provided by the Slack backend. This class is largely based on the Slack reaction event data.

__init__(reactor: errbot.backends.base.Identifier = None, reacted_to_owner: errbot.backends.base.Identifier = None, action: str = None, timestamp: str = None, reaction_name: str = None, reacted_to: Mapping[KT, VT_co] = None)[source]

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

action

Returns the action performed It can be one of the constants REACTION_ADDED or REACTION_REMOVED It can also be backend specific

reacted_to

Returns the item that was reacted to Structure of the reacted to item is backend specific

reacted_to_owner

Identifier of the owner, if any, of the item that was reacted to. It can be a RoomOccupant or a Person. :return: the person or roomOccupant

reaction_name

Returns the reaction that was added or removed Format of the reaction is backend specific

reactor

Identifier of the reacting individual. It can be a RoomOccupant or a Person. :return: the person or roomOccupant

timestamp

Returns the timestamp string in which the event occurred Format of the timestamp string is backend specific

class errbot.backends.base.Room[source]

Bases: errbot.backends.base.Identifier

This class represents a Multi-User Chatroom.

create() → None[source]

Create the room.

Calling this on an already existing room is a no-op.

destroy() → None[source]

Destroy the room.

Calling this on a non-existing room is a no-op.

exists

Boolean indicating whether this room already exists or not.

Getter:Returns True if the room exists, False otherwise.
invite(*args) → None[source]

Invite one or more people into the room.

*argsargs:One or more identifiers to invite into the room.
join(username: str = None, password: str = None) → None[source]

Join the room.

If the room does not exist yet, this will automatically call create() on it first.

joined

Boolean indicating whether this room has already been joined.

Getter:Returns True if the room has been joined, False otherwise.
leave(reason: str = None) → None[source]

Leave the room.

Parameters:reason (str) – An optional string explaining the reason for leaving the room.
occupants

The room’s occupants.

Getter:Returns a list of occupant identities.
Raises:MUCNotJoinedError if the room has not yet been joined.
topic

The room topic.

Getter:

Returns the topic (a string) if one is set, None if no topic has been set at all.

Note

Back-ends may return an empty string rather than None when no topic has been set as a network may not differentiate between no topic and an empty topic.

Raises:

MUCNotJoinedError if the room has not yet been joined.

exception errbot.backends.base.RoomDoesNotExistError[source]

Bases: errbot.backends.base.RoomError

Exception that is raised when performing an operation on a room that doesn’t exist

exception errbot.backends.base.RoomError[source]

Bases: Exception

General exception class for MUC-related errors

exception errbot.backends.base.RoomNotJoinedError[source]

Bases: errbot.backends.base.RoomError

Exception raised when performing MUC operations that require the bot to have joined the room

class errbot.backends.base.RoomOccupant[source]

Bases: errbot.backends.base.Identifier

room

Some backends have the full name of a user.

Returns:the fullname of this user if available.
class errbot.backends.base.Stream(identifier: errbot.backends.base.Identifier, fsource: BinaryIO, name: str = None, size: int = None, stream_type: str = None)[source]

Bases: _io.BufferedReader

This class represents a stream request.

Instances of this class are passed to callback_stream() when an incoming stream is requested.

__init__(identifier: errbot.backends.base.Identifier, fsource: BinaryIO, name: str = None, size: int = None, stream_type: str = None)[source]

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

accept() → None[source]

Signal that the stream has been accepted.

ack_data(length: int) → None[source]

Acknowledge data has been transfered.

clone(new_fsource: BinaryIO) → errbot.backends.base.Stream[source]

Creates a clone and with an alternative stream

error(reason='unknown') → None[source]

An internal plugin error prevented the transfer.

identifier

The identity the stream is coming from if it is an incoming request or to if it is an outgoing request.

name

The name of the stream/file if it has one or None otherwise. !! Be carefull of injections if you are using this name directly as a filename.

reject() → None[source]

Signal that the stream has been rejected.

size

The expected size in bytes of the stream if it is known or None.

status

The status for this stream.

stream_type

The mimetype of the stream if it is known or None.

success() → None[source]

The streaming finished normally.

transfered

The currently transfered size.

exception errbot.backends.base.UserDoesNotExistError[source]

Bases: Exception

Exception that is raised when performing an operation on a user that doesn’t exist

exception errbot.backends.base.UserNotUniqueError[source]

Bases: Exception

Exception raised to report a user has not been uniquely identified on the chat service.