nio Documentation Release 0.18.6 Damir Jelic´ Sep 17, 2021 Contents 1 Documentation 3 2 Features 5 3 Installation 7 4 Examples 9 5 Api Documentation 11 5.1 API.................................................... 11 5.2 Examples................................................. 124 5.3 Contributing............................................... 145 6 Indices and tables 147 Python Module Index 149 Index 151 i ii nio Documentation, Release 0.18.6 nio is a multilayered Matrix client library. The underlying base layer doesn’t do any network IO on its own, but on top of that is a full fledged batteries-included asyncio layer using aiohttp. File IO is only done if you enable end-to-end encryption (E2EE). Contents 1 nio Documentation, Release 0.18.6 2 Contents CHAPTER 1 Documentation The full API documentation for nio can be found at https://matrix-nio.readthedocs.io 3 nio Documentation, Release 0.18.6 4 Chapter 1. Documentation CHAPTER 2 Features nio has most of the features you’d expect in a Matrix library, but it’s still a work in progress. • transparent end-to-end encryption (EE2E) • encrypted file uploads & downloads • manual and emoji verification • custom authentication types • well-integrated type system • kick, ban and unban • typing notifications • message redaction • token based login • user registration • read receipts • live syncing • m.tags • python 2.7 support • cross-signing support • user deactivation (#112) • in-room emoji verification • room upgrades and m.room.tombstone events (#47) 5 nio Documentation, Release 0.18.6 6 Chapter 2. Features CHAPTER 3 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). On Debian and Ubuntu one can use apt-get to install package libolm-dev. On Fedora one can use dnf to install package libolm-devel. On MacOS one can use brew to install package libolm. Make sure version 3 is installed. After libolm has been installed, the e2ee enabled version of nio can be installed using pip: $ pip install "matrix-nio[e2e]" Additionally, a docker image with the e2ee enabled version of nio is provided in the docker/ directory. 7 nio Documentation, Release 0.18.6 8 Chapter 3. Installation CHAPTER 4 Examples For examples of how to use nio, and how others are using it, read the docs 9 nio Documentation, Release 0.18.6 10 Chapter 4. Examples CHAPTER 5 Api Documentation 5.1 API This document details the API of nio. 5.1.1 Api class nio.Api Matrix API class. Static methods reflecting the Matrix REST API. static content_repository_config(access_token: str) ! Tuple[str, str] Get the content repository configuration, such as upload limits. Returns the HTTP method and HTTP path for the request. Parameters access_token (str) – The access token to be used with the request. static delete_devices(access_token, devices, auth_dict=None) Delete a device. This API endpoint uses the User-Interactive Authentication API. This tells the server to delete the given devices and invalidate their associated access tokens. Should first be called with no additional authentication information. Returns the HTTP method, HTTP path and data for the request. Parameters • access_token (str) – The access token to be used with the request. • devices (List[str]) – A list of devices which will be deleted. • auth_dict (Dict) – Additional authentication information for the user-interactive au- thentication API. 11 nio Documentation, Release 0.18.6 static delete_pushrule(access_token: str, scope: str, kind: nio.api.PushRuleKind, rule_id: str) ! Tuple[str, str] Delete an existing user-created push rule. Returns the HTTP method and HTTP path for the request. Parameters • access_token (str) – The access token to be used with the request. • scope (str) – The scope of this rule, e.g. "global". • kind (PushRuleKind) – The kind of rule. • rule_id (str) – The identifier of the rule. Must be unique within its scope and kind. static devices(access_token) Get the list of devices for the current user. Returns the HTTP method and HTTP path for the request. Parameters access_token (str) – The access token to be used with the request. static discovery_info() ! Tuple[str, str] Get discovery information about a domain. Returns the HTTP method and HTTP path for the request. static download(server_name, media_id, filename=None, allow_remote=True) Get the content of a file from the content repository. Returns the HTTP method and HTTP path for the request. Parameters • server_name (str) – The server name from the mxc:// URI. • media_id (str) – The media ID from the mxc:// URI. • filename (str, optional) – A filename to be returned in the response by the server. If None (default), the original name of the file will be returned instead, if there is one. • allow_remote (bool) – Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. static enable_pushrule(access_token: str, scope: str, kind: nio.api.PushRuleKind, rule_id: str, enable: bool) ! Tuple[str, str, str] Enable or disable an existing built-in or user-created push rule. Returns the HTTP method, HTTP path and data for the request. Parameters • access_token (str) – The access token to be used with the request. • scope (str) – The scope of this rule, e.g. "global". • kind (PushRuleKind) – The kind of rule. • rule_id (str) – The identifier of the rule. Must be unique within its scope and kind. • enable (bool) – Whether to enable or disable the rule. static encrypted_mxc_to_plumb(mxc, key, hash, iv, homeserver=None, mimetype=None) Convert a matrix content URI to a encrypted mxc URI. 12 Chapter 5. Api Documentation nio Documentation, Release 0.18.6 The return value of this function will have a URI schema of emxc://. The path of the URI will be converted just like the mxc_to_http() function does, but it will also contain query parameters that are necessary to decrypt the payload the URI is pointing to. This function is useful to present a clickable URI that can be passed to a plumber program that will download and decrypt the content that the matrix content URI is pointing to. The returned URI should never be converted to http and opened directly, as that would expose the decryp- tion parameters to any middleman or ISP. Parameters • mxc (str) – The matrix content URI. • key (str) – The encryption key that can be used to decrypt the payload the URI is pointing to. • hash (str) – The hash of the payload. • iv (str) – The initial value needed to decrypt the payload. • mimetype (str) – The mimetype of the payload. static get_presence(access_token: str, user_id: str) ! Tuple[str, str] Get the given user’s presence state. Returns the HTTP method and HTTP path for the request. Parameters • access_token (str) – The access token to be used with the request. • user_id (str) – User id whose presence state to get. static join(access_token, room_id) Join a room. Returns the HTTP method, HTTP path and data for the request. Parameters • access_token (str) – The access token to be used with the request. • room_id (str) – The room identifier or alias to join. static joined_members(access_token, room_id) Get the list of joined members for a room. Returns the HTTP method and HTTP path for the request. Parameters • access_token (str) – The access token to be used with the request. • room_id (str) – Room id of the room where the user is typing. static joined_rooms(access_token) Get the list of joined rooms for the logged in account. Returns the HTTP method and HTTP path for the request. Parameters access_token (str) – The access token to be used with the request. static keys_claim(access_token, user_set) Claim one-time keys for use in Olm pre-key messages. Returns the HTTP method, HTTP path and data for the request. 5.1. API 13 nio Documentation, Release 0.18.6 Parameters • access_token (str) – The access token to be used with the request. • user_set (Dict[str, List[str]]) – The users and devices for which to claim one-time keys to be claimed. A map from user ID, to a list of device IDs. static keys_query(access_token, user_set, token=None) Query the current devices and identity keys for the given users. Returns the HTTP method, HTTP path and data for the request. Parameters • access_token (str) – The access token to be used with the request. • user_set (Set[str]) – The users for which the keys should be downloaded. • token (Optional[str]) – If the client is fetching keys as a result of a device update received in a sync request, this should be the ‘since’ token of that sync request, or any later sync token. static keys_upload(access_token, key_dict) Publish end-to-end encryption keys. Returns the HTTP method, HTTP path and data for the request. Parameters • access_token (str) – The access token to be used with the request. • key_dict (Dict) – The dictionary containing device and one-time keys that will be published to the server. static login(user, password=None, device_name=”, device_id=”, token=None) Authenticate the user. Returns the HTTP method, HTTP path and data for the request. Parameters • user (str) – The fully qualified user ID or just local part of the user ID, to log in. If the user ID contains an ‘@’, but no ‘:’, the user ID will be considered to be an email address. • password (str) – The user’s password. • device_name (str) – A display name to assign to a newly-created device. Ignored if device_id corresponds to a known device • device_id (str) – ID of the client device. If this does not correspond to a known client device, a new device will be created. static login_info() ! Tuple[str, str] Get the homeserver’s supported login types Returns the HTTP method and HTTP path for the request. static login_raw(auth_dict) Login to the homeserver using a raw dictionary.