AppService

class appservice_framework.AppService(matrix_server, server_domain, access_token, user_namespace, room_namespace, sender_localpart, database_url, loop=None, invite_only_rooms=False)

Bases: object

Run the Matrix Appservice.

This needs to maintain state of matrix rooms and bridged users in those rooms.

Attributes Summary

api	The matrix API object for the appservice.
http_session	The HTTP session object.

Methods Summary

add_authenticated_user(matrixid, auth_token)	Add an authenticated user to the appservice.
get_connection([serviceid, wait_for_connect])	Get the connection object for a given user.
get_room([matrixid, serviceid])	Get a appservice_framework.database.Room object based on IDs.
get_user([matrixid, serviceid, user_type])	Get a appservice_framework.database.User object based on IDs.
matrix_recieve_image(coro)	A matrix ‘m.room.message’ event with ‘m.image’ type.
matrix_recieve_message(coro)	A matrix ‘m.room.message’ event with ‘m.text’ type.
matrix_user_join(coro)	coro(appservice, event)
matrix_user_part(coro)	coro(appservice, event)
matrix_user_typing(coro)	coro(appservice, event)
run([host, port])	Run the appservice.
service_change_profile_image(coro)	Decorator for when an authenticated user changes profile picture
service_connect(coro)	A decorator to register the connection function.
service_join_room(coro)	This function is called when an authenticated user joins a new service room, i.e.
service_part_room(coro)	This is called when a matrix user leaves a room.
service_room_exists(coro)	Decorator to query if a service room exists.

Attributes Documentation

api

The matrix API object for the appservice.

Note

This is only acceible inside the run context manager.

http_session

The HTTP session object.

Note

This is only acceible inside the run context manager.

Methods Documentation

add_authenticated_user(matrixid, auth_token, serviceid=None, nick=None)

Add an authenticated user to the appservice.

This user will connect when the appservice is run, if serviceid was not specified it must be returned by the connect decorator.

Parameters:

• matrixid (str) – The matrix id of the user to add.
• auth_token (str) – The authentication token for this user.
• serviceid (str, optional) – The username/id for the service user.
• nick (str, optional) – A nickname for this user.

Returns:

connection (object) – A connection object, as returned by the @appservice.service_connect decorator.

get_connection(serviceid=None, wait_for_connect=False)

Get the connection object for a given user.

Parameters:

• serviceid (str) – The service user id for the connection.
• wait_for_connect (bool, optional, default: False) – If True this function will block until the connection is made, if False it will return the asyncio.Task object for the connection attempt.

Returns:

connection (object or asyncio.Task) – The connection object as returned by @appservice.service_connect.

get_room(matrixid=None, serviceid=None)

Get a appservice_framework.database.Room object based on IDs.

Parameters:

• matrixid (str, optional) – The matrix id of the room to lookup.
• serviceid (str, optional) – Ther service id of the room to lookup.

Returns:

user (appservice_framework.database.Room or None) – The user in the database or None if the room was not found.

get_user(matrixid=None, serviceid=None, user_type='service')

Get a appservice_framework.database.User object based on IDs.

Parameters:

• matrixid (str, optional) – The matrix id of the user to lookup.
• serviceid (str, optional) – The service id of the user to lookup.

Returns:

user (appservice_framework.database.User or None) – The user in the database or None if the user was not found.

matrix_recieve_image(coro)

A matrix ‘m.room.message’ event with ‘m.image’ type.

coro(appservice, auth_user, room, content)

matrix_recieve_message(coro)

A matrix ‘m.room.message’ event with ‘m.text’ type.

coro(appservice, auth_user, room, content)

matrix_user_join(coro)

coro(appservice, event)

matrix_user_part(coro)

coro(appservice, event)

matrix_user_typing(coro)

coro(appservice, event)

run(host='127.0.0.1', port=5000)

Run the appservice.

Example

>>> apps = AppService(...)
>>> with apps.run() as run_forever:
...     run_forever()

service_change_profile_image(coro)

Decorator for when an authenticated user changes profile picture

coro(appservice)

Returns:mxid image_url force_update

service_connect(coro)

A decorator to register the connection function.

This function is called for every AuthenticatedUser on run().

Function Signature

coro(appservice, serviceid, auth_token)

Returns

service : object

An object representing the connection.

service_userid : str or None

The service user id of the connected user

service_userid : str or None

The service user id of the connected usu

service_join_room(coro)

This function is called when an authenticated user joins a new service room, i.e. a room that exists but the service account is not currently a member of.

coro(appservice, service_userid, service_roomid)

service_part_room(coro)

This is called when a matrix user leaves a room.

coro(appservice, user, room)

service_room_exists(coro)

Decorator to query if a service room exists.

coro(appservice, service_roomid)