This is a Matrix client-server SDK for Python 2.7 and 3.4+

Community discussion on usage of this SDK and development of this SDK can be found at #matrix-python-sdk:matrix.org.

Documentation can be found at http://matrix-org.github.io/matrix-python-sdk/

This sdk is currently lightly maintained (without any sort of official or semi-official "lead" maintainer). In general pull-requests might be reviewed but little to no new-feature or bug-fix development is happening outside of that. For more info or to volunteer to help, please see matrix-org#279. Or come chat in #matrix-python-sdk:matrix.org.

Install with pip from pypi. This will install all necessary dependencies as well.

pip install matrix_client

Install using setup.py in root project directory. This will also install all needed dependencies.

git clone https://github.com/matrix-org/matrix-python-sdk.git
cd matrix-python-sdk
python setup.py install

The Olm bindings are not yet hosted on PyPI. Hence it it necessary to pass --process-dependency-links when installing with pip, in order to fetch them from their Git repository. For example replace python setup.py install in the above instructions by pip install --process-dependency-links .[e2e].

The SDK provides 2 layers of interaction. The low-level layer just wraps the raw HTTP API calls. The high-level layer wraps the low-level layer and provides an object model to perform actions on.

Client:

from matrix_client.client import MatrixClient

client = MatrixClient("http://localhost:8008")

# New user
token = client.register_with_password(username="foobar", password="monkey")

# Existing user
token = client.login(username="foobar", password="monkey")

room = client.create_room("my_room_alias")
room.send_text("Hello!")

API:

from matrix_client.api import MatrixHttpApi

matrix = MatrixHttpApi("https://matrix.org", token="some_token")
response = matrix.send_message("!roomid:matrix.org", "Hello!")

The SDK is split into two modules: api and client.

This contains the raw HTTP API calls and has minimal business logic. You can set the access token (token) to use for requests as well as set a custom transaction ID (txn_id) which will be incremented for each request.

This encapsulates the API module and provides object models such as Room.

A collection of samples are included, written in Python 3.

You can either install the SDK, or run the sample like this:

PYTHONPATH=. python samples/samplename.py

The documentation can be built by installing sphinx and sphinx_rtd_theme.

Simple run make inside docs which will list the avaliable output formats.