https://github.com/matrix-org/matrix-python-sdk
Matrix Client-Server SDK for Python 2 and 3
https://github.com/matrix-org/matrix-python-sdk
Last synced: 9 months ago
JSON representation
Matrix Client-Server SDK for Python 2 and 3
- Host: GitHub
- URL: https://github.com/matrix-org/matrix-python-sdk
- Owner: matrix-org
- License: apache-2.0
- Created: 2015-01-06T09:17:45.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2022-10-16T09:13:19.000Z (over 3 years ago)
- Last Synced: 2025-05-10T16:48:40.646Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 2.72 MB
- Stars: 256
- Watchers: 53
- Forks: 119
- Open Issues: 59
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
Awesome Lists containing this project
README
Matrix Client SDK for Python
============================
.. image:: https://img.shields.io/pypi/v/matrix-client.svg?maxAge=600
:target: https://pypi.python.org/pypi/matrix-client
:alt: Latest Version
.. image:: https://travis-ci.org/matrix-org/matrix-python-sdk.svg?branch=master
:target: https://travis-ci.org/matrix-org/matrix-python-sdk
:alt: Travis-CI Results
.. image:: https://coveralls.io/repos/github/matrix-org/matrix-python-sdk/badge.svg?branch=master
:target: https://coveralls.io/github/matrix-org/matrix-python-sdk?branch=master
:alt: coveralls.io Results
.. image:: https://img.shields.io/matrix/matrix-python-sdk:matrix.org
:target: https://matrix.to/#/%23matrix-python-sdk:matrix.org
:alt: Matrix chatroom
.. image:: https://img.shields.io/badge/docs-stable-blue
:target: https://matrix-org.github.io/matrix-python-sdk/
:alt: Documentation
Matrix client-server SDK for Python 2.7 and 3.4+
Project Status
--------------
We strongly recommend using the `matrix-nio`_ library rather than this
sdk. It is both more featureful and more actively maintained.
This sdk is currently lightly maintained without any person ultimately
responsible for the project. Pull-requests **may** be reviewed, but no
new-features or bug-fixes are being actively developed. For more info
or to volunteer to help, please see
https://github.com/matrix-org/matrix-python-sdk/issues/279 or come
chat in `#matrix-python-sdk:matrix.org`_.
.. _`matrix-nio`: https://github.com/poljar/matrix-nio
.. _`#matrix-python-sdk:matrix.org`: https://matrix.to/#/%23matrix-python-sdk:matrix.org
Installation
============
Stable release
--------------
Install with pip from pypi. This will install all necessary dependencies as well.
.. code:: shell
pip install matrix_client
Development version
-------------------
Install using ``setup.py`` in root project directory. This will also install all
needed dependencies.
.. code:: shell
git clone https://github.com/matrix-org/matrix-python-sdk.git
cd matrix-python-sdk
python setup.py install
Usage
=====
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:
.. code:: python
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:
.. code:: python
from matrix_client.api import MatrixHttpApi
matrix = MatrixHttpApi("https://matrix.org", token="some_token")
response = matrix.send_message("!roomid:matrix.org", "Hello!")
Structure
=========
The SDK is split into two modules: ``api`` and ``client``.
API
---
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.
Client
------
This encapsulates the API module and provides object models such as ``Room``.
Samples
=======
A collection of samples are included, written in Python 3.
You can either install the SDK, or run the sample like this:
.. code:: shell
PYTHONPATH=. python samples/samplename.py
Building the Documentation
==========================
The documentation can be built by installing ``sphinx`` and ``sphinx_rtd_theme``.
Simple run ``make`` inside ``docs`` which will list the avaliable output formats.