errbot.backends.base module

class errbot.backends.base.Backend(_)

Bases: 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

abstract build_identifier(text_representation: str) → Identifier

build_message(text: str) → Message

You might want to override this one depending on your backend

abstract build_reply(msg: Message, text: str = None, private: bool = False, threaded: bool = False)

Should be implemented by the backend

abstract callback_presence(presence: Presence) → None

Implemented by errBot.

abstract callback_room_joined(room: Room) → None

See ErrBot

abstract callback_room_left(room: Room) → None

See ErrBot

abstract callback_room_topic(room: Room) → None

See ErrBot

abstract 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

abstract connect_callback() → None

abstract disconnect_callback() → None

is_from_self(msg: 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.

abstract property mode: str

abstract prefix_groupchat_reply(message: Message, identifier: Identifier)

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

abstract query_room(room: str) → 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.

abstract property rooms: Sequence[Room]

Return a list of rooms the bot is currently in.

Returns:

A list of Room instances.

abstract send_message(msg: 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: Identifier = None, to: Identifier = None, parent: 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: Message

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

__init__(body: str = '', frm: Identifier = None, to: Identifier = None, parent: 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.

property color: str

property fields: Tuple[Tuple[str, str]]

property image: str

property link: str

property summary: str

property text_color: str

property thumbnail: str

property title: str

class errbot.backends.base.Identifier

Bases: 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: Identifier = None, to: Identifier = None, parent: Message = None, delayed: bool = False, partial: bool = False, extras: Mapping = 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: Identifier = None, to: Identifier = None, parent: Message = None, delayed: bool = False, partial: bool = False, extras: Mapping = 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.

property body: str

Get the plaintext body of the message.

Returns:

The body as a string.

clone() → Message

property delayed: bool

property extras: Mapping

property flow: errbot.Flow

Get the conversation flow for this message.

Returns:

A Flow

property frm: Identifier

Get the sender of the message.

Returns:

An Identifier identifying the sender.

property is_direct: bool

property is_group: bool

property is_threaded: bool

property parent: Message | None

property partial: bool

property to: Identifier

Get the recipient of the message.

Returns:

A backend specific identifier representing the recipient.

class errbot.backends.base.Person

Bases: 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.

abstract property aclattr: str

Returns:

returns the unique identifier that will be used for ACL matches.

abstract property client: str

Returns:

a backend specific unique identifier representing the device or client the person is using to talk.

property email: str

Some backends have the email of a user.

Returns:

the email of this user if available.

abstract property fullname: str

Some backends have the full name of a user.

Returns:

the fullname of this user if available.

abstract property nick: str

Returns:

a backend specific nick returning the nickname of this person if available.

abstract property person: str

Returns:

a backend specific unique identifier representing the person you are talking to.

class errbot.backends.base.Presence(identifier: 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: Identifier, status: str = None, message: str = None)

property identifier: Identifier

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

property message: str

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)

property status: str

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: Identifier = None, reacted_to_owner: Identifier = None, action: str = None, timestamp: str = None, reaction_name: str = None, reacted_to: Mapping = None)

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: Identifier = None, reacted_to_owner: Identifier = None, action: str = None, timestamp: str = None, reaction_name: str = None, reacted_to: Mapping = None)

property action: str

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

property reacted_to: Mapping

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

property reacted_to_owner: Identifier

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

property reaction_name: str

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

property reactor: Identifier

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

property timestamp: str

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

class errbot.backends.base.Room

Bases: Identifier

This class represents a Multi-User Chatroom.

property aclattr: str

Returns:

returns the unique identifier that will be used for ACL matches.

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.

property exists: bool

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.

Parameters:

*args –

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.

property joined: bool

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.

property occupants: List[RoomOccupant]

The room’s occupants.

Getter:

Returns a list of occupant identities.

Raises:

MUCNotJoinedError if the room has not yet been joined.

property topic: str

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: 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: RoomError

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

class errbot.backends.base.RoomOccupant

Bases: Identifier

abstract property room: Any

Some backends have the full name of a user.

Returns:

the fullname of this user if available.

class errbot.backends.base.Stream(identifier: Identifier, fsource: BinaryIO, name: str = None, size: int = None, stream_type: str = None)

Bases: BufferedReader

This class represents a stream request.

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

__init__(identifier: Identifier, fsource: BinaryIO, name: str = None, size: int = None, stream_type: str = None)

accept() → None

Signal that the stream has been accepted.

ack_data(length: int) → None

Acknowledge data has been transfered.

clone(new_fsource: BinaryIO) → Stream

Creates a clone and with an alternative stream

error(reason='unknown') → None

An internal plugin error prevented the transfer.

property identifier: Identifier

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

property name: str

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.

property size: int

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

property status: str

The status for this stream.

property stream_type: str

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

success() → None

The streaming finished normally.

property transfered: int

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

exception errbot.backends.base.UserNotUniqueError

Bases: Exception

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

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