errbot.backends.base module

class errbot.backends.base.Backend(_)

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__(_)

Those arguments will be directly those put in BOT_IDENTITY

build_identifier(text_representation: str) → errbot.backends.base.Identifier

build_message(text: str) → errbot.backends.base.Message

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)

Should be implemented by the backend

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

Implemented by errBot.

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

See ErrBot

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

See ErrBot

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

See ErrBot

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

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

cmd_history = {}

connect() → Any

Connects the bot to server or returns current connection

connect_callback() → None

disconnect_callback() → None

is_from_self(msg: errbot.backends.base.Message) → bool

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)

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

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

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

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

serve_forever() → None

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

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]] = ())

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]] = ())

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

link

summary

text_color

thumbnail

title

class errbot.backends.base.Identifier

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)

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)

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

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

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.

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)

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)

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.Room

Bases: errbot.backends.base.Identifier

This class represents a Multi-User Chatroom.

create() → None

Create the room.

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

destroy() → None

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

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

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

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

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

Bases: Exception

General exception class for MUC-related errors

exception errbot.backends.base.RoomNotJoinedError

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

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)

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)

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

accept() → None

Signal that the stream has been accepted.

ack_data(length: int) → None

Acknowledge data has been transfered.

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

Creates a clone and with an alternative stream

error(reason='unknown') → None

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

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

The streaming finished normally.

transfered

The currently transfered size.

exception errbot.backends.base.UserDoesNotExistError

Bases: Exception

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

Previous: errbot.backends package | Next: errbot.backends.hipchat module