mautrix.api

class mautrix.api.APIPath

Bases: enum.Enum

The known Matrix API path prefixes. These don’t start with a slash so they can be used nicely with yarl.

CLIENT = '_matrix/client/r0'
CLIENT_UNSTABLE = '_matrix/client/unstable'
MEDIA = '_matrix/media/r0'
SYNAPSE_ADMIN = '_synapse/admin'
class mautrix.api.Method

Bases: enum.Enum

A HTTP method.

GET = 'GET'
POST = 'POST'
PUT = 'PUT'
DELETE = 'DELETE'
PATCH = 'PATCH'
class mautrix.api.PathBuilder

Bases: object

A utility class to build API paths.

Examples

>>> from mautrix.api import Path
>>> room_id = "!foo:example.com"
>>> event_id = "$bar:example.com"
>>> str(Path.rooms[room_id].event[event_id])
"_matrix/client/r0/rooms/%21foo%3Aexample.com/event/%24bar%3Aexample.com"
__init__(path='')
Parameters

path (str | mautrix.api.APIPath) –

Return type

None

raw(append)

Directly append a string to the path.

Parameters

append (str) – The string to append.

Return type

mautrix.api.PathBuilder

mautrix.api.ClientPath

A path builder with the standard client r0 prefix ( /_matrix/client/r0, APIPath.CLIENT)

mautrix.api.Path

A shorter alias for ClientPath

mautrix.api.UnstableClientPath

A path builder for client endpoints that haven’t reached the spec yet (/_matrix/client/unstable, APIPath.CLIENT_UNSTABLE)

mautrix.api.MediaPath

A path builder for standard media r0 paths (/_matrix/media/r0, APIPath.MEDIA)

Examples

>>> from mautrix.api import MediaPath
>>> str(MediaPath.config)
"_matrix/media/r0/config"
mautrix.api.SynapseAdminPath

A path builder for synapse-specific admin API paths (/_synapse/admin/v1, APIPath.SYNAPSE_ADMIN)

Examples

>>> from mautrix.api import SynapseAdminPath
>>> user_id = "@user:example.com"
>>> str(SynapseAdminPath.users[user_id]/login)
"_synapse/admin/v1/users/%40user%3Aexample.com/login"
class mautrix.api.HTTPAPI

Bases: object

HTTPAPI is a simple asyncio Matrix API request sender.

default_ua: ClassVar[str] = 'mautrix-python/0.12.3 aiohttp/3.8.1 Python/3.10.0'

The default value for the User-Agent header.

You should prepend your program name and version here before creating any HTTPAPI instances in order to have proper user agents for all requests.

global_default_retry_count: ClassVar[int] = 0

The default retry count to use if an instance-specific value is not passed.

__init__(base_url, token='', *, client_session=None, default_retry_count=None, txn_id=0, log=None, loop=None)
Parameters

  • base_url (yarl.URL | str) – The base URL of the homeserver’s client-server API to use.

  • token (str) – The access token to use.

  • client_session (Optional[aiohttp.ClientSession]) – The aiohttp client session to use.

  • txn_id (int) – The outgoing transaction ID to start with.

  • log (Optional[mautrix.util.logging.TraceLogger]) – The logging.Logger instance to log requests with.

  • default_retry_count (Optional[int]) – Default number of retries to do when encountering network errors.

  • loop (Optional[asyncio.events.AbstractEventLoop]) –

Return type

None

base_url: yarl.URL

The base URL of the homeserver’s client-server API to use.

token: str

The access token to use in requests.

log: mautrix.util.logging.TraceLogger

The logging.Logger instance to log requests with.

session: aiohttp.ClientSession

The aiohttp ClientSession instance to make requests with.

txn_id: int | None

A counter used for generating transaction IDs.

default_retry_count: int

The default retry count to use if a custom value is not passed to request()

async request(method, path, content=None, headers=None, query_params=None, retry_count=None)

Make a raw Matrix API request.

Parameters

  • method (Method) – The HTTP method to use.

  • path (PathBuilder | str) – The full API endpoint to call (including the _matrix/… prefix)

  • content (dict | list | bytes | str | None) – The content to post as a dict/list (will be serialized as JSON) or bytes/str (will be sent as-is).

  • headers (dict[str, str] | None) – A dict of HTTP headers to send. If the headers don’t contain Content-Type, it’ll be set to application/json. The Authorization header is always overridden if token is set.

  • query_params (Mapping[str, str] | None) – A dict of query parameters to send.

  • retry_count (int | None) – Number of times to retry if the homeserver isn’t reachable. Defaults to default_retry_count.

Returns

The parsed response JSON.

Return type

JSON

get_txn_id()

Get a new unique transaction ID.

Return type

str

get_download_url(mxc_uri, download_type='download')

Get the full HTTP URL to download a mxc:// URI.

Parameters

  • mxc_uri (str) – The MXC URI whose full URL to get.

  • download_type (str) – The type of download (“download” or “thumbnail”).

Returns

The full HTTP URL.

Raises

ValueError – If mxc_uri doesn’t begin with mxc://.

Return type

yarl.URL

Examples

>>> api = HTTPAPI(...)
>>> api.get_download_url("mxc://matrix.org/pqjkOuKZ1ZKRULWXgz2IVZV6")
"https://matrix.org/_matrix/media/r0/download/matrix.org/pqjkOuKZ1ZKRULWXgz2IVZV6"