djotaku / matrix-nio

A Python Matrix client library, designed according to sans I/O (http://sans-io.readthedocs.io/) principles

nio

nio is a multilayered matrix client library. The underlying base layer doesn't do any IO on its own. On top of the base layer, a no-IO HTTP client implementation exists, as well as a full fledged batteries included asyncio layer using aiohttp.

Documentation

The full API documentation for nio can be found at https://matrix-nio.readthedocs.io

Installation

To install nio, simply use pip:

$ pip install matrix-nio

Note that this installs nio without end-to-end encryption support. For e2ee support, python-olm is needed which requires the libolm C library (version 3.x).

After libolm has been installed, the e2ee enabled version of nio can be installed using pip:

$ pip install "matrix-nio[e2e]"

Usage

Unless special requirements disallow the usage of asyncio, by far the easiest way to use nio is using the asyncio layer.

Please do note that these examples require python 3.5+ for the async/await syntax. nio on the other hand works with older python versions as well.

Sending a message

import asyncio
from nio import AsyncClient

async def main():
    client = AsyncClient("https://example.org", "@alice:example.org")

    await client.login("hunter1")
    await client.room_send(
        room_id="!test:example.org",
        message_type="m.room.message",
        content={
            "msgtype": "m.text",
            "body": "Hello World"
        }
    )
    await client.close()

asyncio.get_event_loop().run_until_complete(main())

Receiving messages

import asyncio
from nio import (AsyncClient, RoomMessageText)

async def message_cb(room, event):
    print(
        "Message received for room {} | {}: {}".format(
            room.display_name, room.user_name(event.sender), event.body
        )
    )

async def main():
    client = AsyncClient("https://example.org", "@alice:example.org")
    client.add_event_callback(message_cb, RoomMessageText)

    await client.login("hunter1")
    await client.sync_forever(timeout=30000)

asyncio.get_event_loop().run_until_complete(main())