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.'¶
-
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
-
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
= {}¶
-
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.
-
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()
anddisconnect_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
¶
-
link
¶
-
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 theMESSAGE_SIZE_LIMIT
.
- body (
-
body
¶ Get the plaintext body of the message.
Returns: The body as a string.
-
delayed
¶
-
extras
¶
-
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.
-
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.
Room
[source]¶ Bases:
errbot.backends.base.Identifier
This class represents a Multi-User Chatroom.
-
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.
-
clone
(new_fsource: BinaryIO) → errbot.backends.base.Stream[source]¶ Creates a clone and with an alternative stream
-
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.
-
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.
-
transfered
¶ The currently transfered size.
-