Automatic documentation

This is automatically generated documentation of the simplematrixbotlib package.

Creds

class simplematrixbotlib.Creds(homeserver, username=None, password=None, login_token=None, access_token=None, session_stored_file='session.txt')[source]

A class to store and handle login credentials.

…

homeserver

The homeserver for the bot to connect to. Begins with “https://”.

Type:: str

username

The username for the bot to connect as.

Type:: str

password

The password for the bot to connect with.

Type:: str

session_read_file()[source]: Reads and decrypts the device_id and access_token from file

session_write_file()[source]: Encrypts and writes to file the device_id and access_token.

Bot

class simplematrixbotlib.Bot(creds, config=None)[source]

A class for the bot library user to interact with.

…

api

An instance of the simplematrixbotlib.Api class.

Type:: simplematrixbotlib.Api

async main()[source]

run()[source]: Runs the bot.

Listener

class simplematrixbotlib.Listener(bot)[source]

on_custom_event(event)[source]

on_message_event(func)[source]

on_reaction_event(func)[source]

on_startup(func)[source]

MessageMatch

class simplematrixbotlib.MessageMatch(room, event, bot, prefix='')[source]

Class with methods to filter message events

…

args()[source]

Returns:: Returns a list of strings that are the “words” of the message, except for the first “word”, which would be the command.
Return type:: list

command(command=None, case_sensitive=True)[source]

Parameters:

command (str, Optional) – Beginning of messages that are intended to be commands, but after the prefix; e.g. “help”.
case_sensitive (bool, Optional) – Whether the string should be matched case sensitive.

Returns:

boolean – Returns True if the string after the prefix and before the first space is the same as the given arg.
str – Returns the string after the prefix and before the first space if no arg is passed to this method.

contains(string)[source]

Returns:: Returns True if the string argument is found within the body of the message.
Return type:: boolean

prefix()[source]

Returns:: Returns True if the message begins with the prefix, and False otherwise. If there is no prefix specified during the creation of this MessageMatch object, then return True.
Return type:: boolean

Api

class simplematrixbotlib.Api(creds: Creds, config: Config)[source]

A class to interact with the matrix-nio library. Usually used by the Bot class, and sparingly by the bot developer.

…

creds

Type:: simplematrixbotlib.Creds

config

Type:: simplematrixbotlib.Config

async_client

Type:: simplematrixbotlib.AsyncClient

async login()[source]: Login the client to the homeserver

async send_image_message(room_id: str, image_filepath: str)[source]

Send an image message in a Matrix room.

Parameters:

room_id (str) – The room id of the destination of the message.
image_filepath (str) – The path to the image on your machine.

async send_markdown_message(room_id: str, message, msgtype: str = 'm.text')[source]

Send a markdown message in a Matrix room.

Parameters:

room_id (str) – The room id of the destination of the message.
message (str) – The content of the message to be sent.
msgtype (str, optional) – The type of message to send: m.text (default), m.notice, etc

async send_reaction(room_id: str, event, key: str)[source]

Send a reaction to a message in a Matrix room.

Parameters:

room_id (str) – The room id of the destination of the message.
event – The event object you want to react to.
key (str) – The content of the reaction. This is usually an emoji, but may technically be any text.

async send_text_message(room_id: str, message: str, msgtype: str = 'm.text', reply_to: str = '')[source]

Send a text message in a Matrix room.

Parameters:

room_id (str) – The room id of the destination of the message.
message (str) – The content of the message to be sent.
msgtype (str, optional) – The type of message to send: m.text (default), m.notice, etc
reply_to (str, optional) – The event id for replying message.

async send_video_message(room_id: str, video_filepath: str)[source]

Send a video message in a Matrix room.

Parameters:

room_id (str) – The room id of the destination of the message.
video_filepath (str) – The path to the video on your machine.

Config

class simplematrixbotlib.Config(_timeout: int = 65536, _join_on_invite: bool = True, _encryption_enabled: bool = False, _emoji_verify: bool = False, _ignore_unverified_devices: bool = True, _store_path: str = './store/', _allowlist: ~typing.Set[~re.Pattern] = <factory>, _blocklist: ~typing.Set[~re.Pattern] = <factory>)[source]

A class to handle built-in user-configurable settings, including support for saving to and loading from a file. Can be inherited from by bot developers to implement custom settings.

add_allowlist(value: Set[str]) → None[source]

Parameters:: value (Set[str]) – A set of strings which represent Matrix IDs or a regular expression matching Matrix IDs to be added to allowlist.

add_blocklist(value: Set[str]) → None[source]

Parameters:: value (Set[str]) – A set of strings which represent Matrix IDs or a regular expression matching Matrix IDs to be added to blocklist.

property allowlist: Set[Pattern]

returns: A set of regular expressions matching Matrix IDs.: Can be used in conjunction with blocklist to check if the sender is allowed to issue a command to the bot. An empty set implies that everyone is allowed.

Return type:: Set[re.Pattern]

property blocklist: Set[Pattern]

returns: A set of regular expressions matching Matrix IDs.: Can be used in conjunction with allowlist to check if the sender is disallowed to issue a command to the bot.

Return type:: Set[re.Pattern]

property emoji_verify: bool: returns: Whether emoji verification requests should be handled by the built in callback function :rtype: boolean

property encryption_enabled: bool

returns: Whether to enable encryption support.: Requires encryption-specific dependencies to be met, see install instructions.

Return type:: boolean

property ignore_unverified_devices: bool

returns: If True, ignore that devices are not verified and send the message to them regardless.: If False, distrust unverified devices.

Return type:: boolean

property join_on_invite: bool: returns: Whether the bot is configured to automatically accept all invites it receives :rtype: boolean

load_toml(file_path: str) → None[source]

remove_allowlist(value: Set[str]) → None[source]

Parameters:: value (Set[str]) – A set of strings which represent Matrix IDs or a regular expression matching Matrix IDs to be removed from allowlist.

remove_blocklist(value: Set[str]) → None[source]

Parameters:: value (Set[str]) – A set of strings which represent Matrix IDs or a regular expression matching Matrix IDs to be removed from blocklist.

save_toml(file_path: str) → None[source]

property store_path: str: returns: Where to store crypto-related data including keys :rtype: string

property timeout: int: returns: Connection timeout for the Matrix client (in milliseconds) :rtype: int