mautrix.types

class mautrix.types.JSON

Bases: Union[str, int, float, bool, None, Dict[str, JSON], List[JSON]]

A union type that covers all JSON-serializable data.

class mautrix.types.UserID

Bases: str

A Matrix user ID (@user:example.com)

class mautrix.types.EventID

Bases: str

A Matrix event ID ($base64 or $legacyid:example.com)

class mautrix.types.RoomID

Bases: str

An internal Matrix room ID (!randomstring:example.com)

class mautrix.types.RoomAlias

Bases: str

A Matrix room address (#alias:example.com)

class mautrix.types.FilterID

Bases: str

A filter ID returned by POST /filter (mautrix.client.ClientAPI.create_filter())

class mautrix.types.ContentURI

Bases: str

A Matrix content URI, used by the content repository.

class mautrix.types.SyncToken

Bases: str

A next_batch token from a /sync response (mautrix.client.ClientAPI.sync())

class mautrix.types.DeviceID

Bases: str

A Matrix device ID. Arbitrary, potentially client-specified string.

class mautrix.types.SessionID

Bases: str

A Megolm session ID.

class mautrix.types.SigningKey

Bases: str

A ed25519 public key as unpadded base64

class mautrix.types.IdentityKey

Bases: str

A curve25519 public key as unpadded base64

class mautrix.types.DiscoveryInformation

.well-known discovery information, as specified in the GET /.well-known/matrix/client endpoint

homeserver: Optional[mautrix.types.DiscoveryServer]
identity_server: Optional[mautrix.types.DiscoveryServer]
integrations: Optional[mautrix.types.DiscoveryServer]
class mautrix.types.DiscoveryIntegrations
managers: List[mautrix.types.DiscoveryIntegrationServer]
class mautrix.types.DiscoveryIntegrationServer
ui_url: Optional[str]
api_url: Optional[str]
class mautrix.types.DiscoveryServer
base_url: Optional[str]
class mautrix.types.LoginFlow

A login flow, as specified in the GET /login endpoint

type: mautrix.types.LoginType
class mautrix.types.LoginFlowList
get_first_of_type(*types)
Parameters

types (mautrix.types.LoginType) –

Return type

Optional[mautrix.types.LoginFlow]

supports_type(*types)
Parameters

types (mautrix.types.LoginType) –

Return type

bool

flows: List[mautrix.types.LoginFlow]
class mautrix.types.LoginResponse

The response for a login request, as specified in the POST /login endpoint

user_id: mautrix.types.UserID
device_id: mautrix.types.DeviceID
access_token: str
well_known: mautrix.types.DiscoveryInformation
class mautrix.types.LoginType

A login type, as specified in the POST /login endpoint

PASSWORD: LoginType = <LoginType.PASSWORD: 'm.login.password'>
TOKEN: LoginType = <LoginType.TOKEN: 'm.login.token'>
SSO: LoginType = <LoginType.SSO: 'm.login.sso'>
APPSERVICE: LoginType = <LoginType.APPSERVICE: 'm.login.application_service'>
UNSTABLE_JWT: LoginType = <LoginType.UNSTABLE_JWT: 'org.matrix.login.jwt'>
class mautrix.types.MatrixUserIdentifier

A client can identify a user using their Matrix ID. This can either be the fully qualified Matrix user ID, or just the localpart of the user ID.

user: str
type: mautrix.types.UserIdentifierType
class mautrix.types.PhoneIdentifier

A client can identify a user using a phone number associated with the user’s account, where the phone number was previously associated using the /account/3pid API. The phone number can be passed in as entered by the user; the homeserver will be responsible for canonicalising it. If the client wishes to canonicalise the phone number, then it can use the m.id.thirdparty identifier type with a medium of msisdn instead.

country: str
phone: str
type: mautrix.types.UserIdentifierType
class mautrix.types.ThirdPartyIdentifier

A client can identify a user using a 3PID associated with the user’s account on the homeserver, where the 3PID was previously associated using the /account/3pid API. See the 3PID Types Appendix for a list of Third-party ID media.

medium: str
address: str
type: mautrix.types.UserIdentifierType
class mautrix.types.UserIdentifierType

A user identifier type, as specified in the Identifier types section of the login spec.

MATRIX_USER: UserIdentifierType = <UserIdentifierType.MATRIX_USER: 'm.id.user'>
THIRD_PARTY: UserIdentifierType = <UserIdentifierType.THIRD_PARTY: 'm.id.thirdparty'>
PHONE: UserIdentifierType = <UserIdentifierType.PHONE: 'm.id.phone'>
class mautrix.types.WhoamiResponse

The response for a whoami request, as specified in the GET /account/whoami endpoint

user_id: mautrix.types.UserID
device_id: Optional[mautrix.types.DeviceID]
is_guest: bool
class mautrix.types.ClaimKeysResponse
failures: Dict[str, Any]
one_time_keys: Dict[mautrix.types.UserID, Dict[mautrix.types.DeviceID, Dict[str, Any]]]
class mautrix.types.DecryptedOlmEvent
keys: mautrix.types.OlmEventKeys
recipient: mautrix.types.UserID
recipient_keys: mautrix.types.OlmEventKeys
sender_device: Optional[mautrix.types.DeviceID]
sender_key: mautrix.types.IdentityKey
class mautrix.types.DeviceIdentity
user_id: mautrix.types.UserID
device_id: mautrix.types.DeviceID
identity_key: mautrix.types.IdentityKey
signing_key: mautrix.types.SigningKey
trust: mautrix.types.TrustState
deleted: bool
name: str
class mautrix.types.DeviceKeys
property curve25519: Optional[mautrix.types.IdentityKey]
property ed25519: Optional[mautrix.types.SigningKey]
user_id: mautrix.types.UserID
device_id: mautrix.types.DeviceID
algorithms: List[mautrix.types.EncryptionAlgorithm]
keys: Dict[str, str]
signatures: Dict[mautrix.types.UserID, Dict[str, str]]
unsigned: mautrix.types.UnsignedDeviceInfo
class mautrix.types.OlmEventKeys
ed25519: mautrix.types.SigningKey
class mautrix.types.QueryKeysResponse
failures: Dict[str, Any]
device_keys: Dict[mautrix.types.UserID, Dict[mautrix.types.DeviceID, mautrix.types.DeviceKeys]]
class mautrix.types.TrustState

An enumeration.

UNSET = 0
VERIFIED = 1
BLACKLISTED = 2
IGNORED = 3
class mautrix.types.UnsignedDeviceInfo
device_display_name: Optional[str]
class mautrix.types.AccountDataEvent
classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (mautrix.types.JSON) –

Return type

mautrix.types.AccountDataEvent

static deserialize_content(data)
Parameters

data (mautrix.types.JSON) –

Return type

Union[mautrix.types.RoomTagAccountDataEventContent, Dict[mautrix.types.UserID, List[mautrix.types.RoomID]], mautrix.types.Obj]

content: Union[mautrix.types.RoomTagAccountDataEventContent, Dict[mautrix.types.UserID, List[mautrix.types.RoomID]], mautrix.types.Obj]
class mautrix.types.AudioInfo

Information about an audio message.

duration: int
class mautrix.types.BaseEvent

Base event class. The only things an event must have are content and event type.

content: mautrix.types.Obj
type: mautrix.types.EventType
class mautrix.types.BaseFileInfo
mimetype: str
size: int
class mautrix.types.BaseMessageEventContent

Base event content for all m.room.message-type events.

msgtype: mautrix.types.MessageType
body: str
external_url: str
class mautrix.types.BaseMessageEventContentFuncs

Base class for the contents of all message-type events (currently m.room.message and m.sticker). Contains relation helpers.

get_edit()
Return type

Optional[mautrix.types.EventID]

get_reply_to()
Return type

Optional[mautrix.types.EventID]

get_thread_parent()
Return type

Optional[mautrix.types.EventID]

property relates_to: mautrix.types.RelatesTo
serialize()
Return type

mautrix.types.JSON

set_edit(edits)
Parameters

edits (Union[mautrix.types.EventID, mautrix.types.MessageEvent]) –

Return type

None

set_reply(reply_to, **kwargs)
Parameters

reply_to (Union[mautrix.types.EventID, mautrix.types.MessageEvent]) –

Return type

None

set_thread_parent(thread_parent, last_event_in_thread=None, disable_reply_fallback=False, **kwargs)
Parameters
Return type

None

trim_reply_fallback()
Return type

None

body: str
class mautrix.types.BaseRoomEvent

Base room event class. Room events must have a room ID, event ID, sender and timestamp in addition to the content and type in the base event.

room_id: mautrix.types.RoomID
event_id: mautrix.types.EventID
sender: mautrix.types.UserID
timestamp: int
class mautrix.types.BaseUnsigned

Base unsigned information.

age: int
class mautrix.types.CallAnswerEventContent
call_id: str
version: int
answer: mautrix.types.CallData
party_id: Optional[str]
class mautrix.types.CallCandidate
candidate: str
sdp_m_line_index: int
sdp_mid: str
class mautrix.types.CallCandidatesEventContent
call_id: str
version: int
candidates: List[mautrix.types.CallCandidate]
party_id: Optional[str]
class mautrix.types.CallData
sdp: str
type: mautrix.types.CallDataType
class mautrix.types.CallDataType
value: Any
class mautrix.types.CallEvent
classmethod deserialize(data, event_type=None)

Convert the given data parsed from JSON into an object of this type.

Parameters
Return type

mautrix.types.CallEvent

content: mautrix.types.event.voip.T
class mautrix.types.CallHangupEventContent
call_id: str
version: int
reason: mautrix.types.CallHangupReason
party_id: Optional[str]
class mautrix.types.CallHangupReason
value: Any
class mautrix.types.CallInviteEventContent
call_id: str
lifetime: int
version: int
offer: mautrix.types.CallData
party_id: Optional[str]
invitee: Optional[mautrix.types.UserID]
class mautrix.types.CallNegotiateEventContent
call_id: str
version: int
lifetime: int
party_id: str
description: mautrix.types.CallData
class mautrix.types.CallRejectEventContent
call_id: str
version: int
party_id: str
class mautrix.types.CallSelectAnswerEventContent
call_id: str
version: int
party_id: str
selected_party_id: str
class mautrix.types.CanonicalAliasStateEventContent

The content of a m.room.canonical_alias event (EventType.ROOM_CANONICAL_ALIAS).

This event is used to inform the room about which alias should be considered the canonical one, and which other aliases point to the room. This could be for display purposes or as suggestion to users which alias to use to advertise and access the room.

See also: m.room.canonical_alias in the spec

canonical_alias: mautrix.types.RoomAlias
alt_aliases: List[mautrix.types.RoomAlias]
class mautrix.types.EncryptedEvent

A m.room.encrypted event

property unsigned: mautrix.types.BaseUnsigned
content: mautrix.types.EncryptedEventContent
class mautrix.types.EncryptedFile
key: mautrix.types.JSONWebKey
iv: str
hashes: Dict[str, str]
url: Optional[mautrix.types.ContentURI]
version: str
class mautrix.types.EncryptedMegolmEventContent

The content of an m.room.encrypted event

property relates_to: mautrix.types.RelatesTo
ciphertext: str
sender_key: mautrix.types.IdentityKey
device_id: mautrix.types.DeviceID
session_id: mautrix.types.SessionID
algorithm: mautrix.types.EncryptionAlgorithm
class mautrix.types.EncryptedOlmEventContent
ciphertext: Dict[str, mautrix.types.OlmCiphertext]
sender_key: mautrix.types.IdentityKey
algorithm: mautrix.types.EncryptionAlgorithm
class mautrix.types.EncryptionAlgorithm
OLM_V1: EncryptionAlgorithm = <EncryptionAlgorithm.OLM_V1: 'm.olm.v1.curve25519-aes-sha2'>
MEGOLM_V1: EncryptionAlgorithm = <EncryptionAlgorithm.MEGOLM_V1: 'm.megolm.v1.aes-sha2'>
class mautrix.types.EncryptionKeyAlgorithm
CURVE25519: EncryptionKeyAlgorithm = <EncryptionKeyAlgorithm.CURVE25519: 'curve25519'>
ED25519: EncryptionKeyAlgorithm = <EncryptionKeyAlgorithm.ED25519: 'ed25519'>
SIGNED_CURVE25519: EncryptionKeyAlgorithm = <EncryptionKeyAlgorithm.SIGNED_CURVE25519: 'signed_curve25519'>
class mautrix.types.EventType

An immutable enum-like class that represents a specific Matrix event type.

In addition to the plain event type string, this also includes the context that the event is used in (see: Class). Comparing EventType instances for equality will check both the type string and the class.

The idea behind the wrapper is that incoming event parsers will always create an EventType instance with the correct class, regardless of what the usual context for the event is. Then when the event is being handled, the type will not be equal to EventType instances with a different class. For example, if someone sends a non-state m.room.name event, checking if event.type == EventType.ROOM_NAME would return False, because the class would be different. Bugs caused by not checking the context of an event (especially state event vs message event) were very common in the past, and using a wrapper like this helps prevent them.

t: str
t_class: mautrix.types.event.type.EventType.Class
ALL = EventType("__ALL__", EventType.Class.UNKNOWN)
CALL_ANSWER = EventType("m.call.answer", EventType.Class.MESSAGE)
CALL_CANDIDATES = EventType("m.call.candidates", EventType.Class.MESSAGE)
CALL_HANGUP = EventType("m.call.hangup", EventType.Class.MESSAGE)
CALL_INVITE = EventType("m.call.invite", EventType.Class.MESSAGE)
CALL_NEGOTIATE = EventType("m.call.negotiate", EventType.Class.MESSAGE)
CALL_REJECT = EventType("m.call.reject", EventType.Class.MESSAGE)
CALL_SELECT_ANSWER = EventType("m.call.select_answer", EventType.Class.MESSAGE)
class Class

The context that an event type is used in.

UNKNOWN = 'unknown'
STATE = 'state'

Room state events

MESSAGE = 'message'

Room message events, i.e. room events that are not state events

ACCOUNT_DATA = 'account_data'

Account data events, user-specific storage used for synchronizing info between clients. Can be global or room-specific.

EPHEMERAL = 'ephemeral'

Ephemeral events. Currently only typing notifications, read receipts and presence are in this class, as custom ephemeral events are not yet possible.

TO_DEVICE = 'to_device'

Device-to-device events, primarily used for exchanging encryption keys

DIRECT = EventType("m.direct", EventType.Class.ACCOUNT_DATA)
FORWARDED_ROOM_KEY = EventType("m.forwarded_room_key", EventType.Class.TO_DEVICE)
IGNORED_USER_LIST = EventType("m.ignored_user_list", EventType.Class.ACCOUNT_DATA)
ORG_MATRIX_ROOM_KEY_WITHHELD = EventType("org.matrix.room_key.withheld", EventType.Class.TO_DEVICE)
PRESENCE = EventType("m.presence", EventType.Class.EPHEMERAL)
PUSH_RULES = EventType("m.push_rules", EventType.Class.ACCOUNT_DATA)
REACTION = EventType("m.reaction", EventType.Class.MESSAGE)
RECEIPT = EventType("m.receipt", EventType.Class.EPHEMERAL)
ROOM_AVATAR = EventType("m.room.avatar", EventType.Class.STATE)
ROOM_CANONICAL_ALIAS = EventType("m.room.canonical_alias", EventType.Class.STATE)
ROOM_CREATE = EventType("m.room.create", EventType.Class.STATE)
ROOM_ENCRYPTED = EventType("m.room.encrypted", EventType.Class.MESSAGE)
ROOM_ENCRYPTION = EventType("m.room.encryption", EventType.Class.STATE)
ROOM_HISTORY_VISIBILITY = EventType("m.room.history_visibility", EventType.Class.STATE)
ROOM_JOIN_RULES = EventType("m.room.join_rules", EventType.Class.STATE)
ROOM_KEY = EventType("m.room_key", EventType.Class.TO_DEVICE)
ROOM_KEY_REQUEST = EventType("m.room_key_request", EventType.Class.TO_DEVICE)
ROOM_KEY_WITHHELD = EventType("m.room_key.withheld", EventType.Class.TO_DEVICE)
ROOM_MEMBER = EventType("m.room.member", EventType.Class.STATE)
ROOM_MESSAGE = EventType("m.room.message", EventType.Class.MESSAGE)
ROOM_NAME = EventType("m.room.name", EventType.Class.STATE)
ROOM_PINNED_EVENTS = EventType("m.room.pinned_events", EventType.Class.STATE)
ROOM_POWER_LEVELS = EventType("m.room.power_levels", EventType.Class.STATE)
ROOM_REDACTION = EventType("m.room.redaction", EventType.Class.MESSAGE)
ROOM_TOMBSTONE = EventType("m.room.tombstone", EventType.Class.STATE)
ROOM_TOPIC = EventType("m.room.topic", EventType.Class.STATE)
SPACE_CHILD = EventType("m.space.child", EventType.Class.STATE)
SPACE_PARENT = EventType("m.space.parent", EventType.Class.STATE)
STICKER = EventType("m.sticker", EventType.Class.MESSAGE)
TAG = EventType("m.tag", EventType.Class.ACCOUNT_DATA)
TO_DEVICE_DUMMY = EventType("m.dummy", EventType.Class.TO_DEVICE)
TO_DEVICE_ENCRYPTED = EventType("m.room.encrypted", EventType.Class.TO_DEVICE)
TYPING = EventType("m.typing", EventType.Class.EPHEMERAL)
classmethod deserialize(raw)

Convert the given data parsed from JSON into an object of this type.

Parameters

raw (mautrix.types.JSON) –

Return type

Any

classmethod find(t, t_class=None)

Create a new EventType instance with the given type and class.

If an EventType instance with the same type string and class has been created before, or if no class is specified here, this will return the same instance instead of making a new one.

Examples

>>> from mautrix.client import Client
>>> from mautrix.types import EventType
>>> MY_CUSTOM_TYPE = EventType.find("com.example.custom_event", EventType.Class.STATE)
>>> client = Client(...)
>>> @client.on(MY_CUSTOM_TYPE)
... async def handle_event(evt): ...
Parameters
Returns

An EventType instance with the given parameters.

Return type

mautrix.types.EventType

property is_account_data: bool

A shortcut for type.t_class == EventType.Class.ACCOUNT_DATA

property is_ephemeral: bool

A shortcut for type.t_class == EventType.Class.EPHEMERAL

property is_message: bool

A shortcut for type.t_class == EventType.Class.MESSAGE

property is_state: bool

A shortcut for type.t_class == EventType.Class.STATE

property is_to_device: bool

A shortcut for type.t_class == EventType.Class.TO_DEVICE

json()

Serialize this object and dump the output as JSON.

Return type

str

classmethod parse_json(data)

Parse the given string as JSON and deserialize the result into this type.

Parameters

data (str) –

Return type

mautrix.types.EventType

serialize()

Convert this object into objects directly serializable with json.

Return type

mautrix.types.JSON

with_class(t_class)

Return a copy of this EventType with the given class. If the given class is the same as what this instance has, or if the given class is None, this returns self instead of making a copy.

Parameters

t_class (Optional[mautrix.types.event.type.EventType.Class]) –

Return type

mautrix.types.EventType

class mautrix.types.FileInfo

Information about a document message.

thumbnail_info: Optional[mautrix.types.ThumbnailInfo]
thumbnail_file: Optional[mautrix.types.EncryptedFile]
thumbnail_url: Optional[mautrix.types.ContentURI]
class mautrix.types.Format

A message format. Currently only org.matrix.custom.html is available. This will probably be deprecated when extensible events are implemented.

HTML: Format = <Format.HTML: 'org.matrix.custom.html'>
class mautrix.types.ForwardedRoomKeyEventContent
sender_key: mautrix.types.IdentityKey
signing_key: mautrix.types.SigningKey
forwarding_key_chain: List[str]
class mautrix.types.GenericEvent

An event class that contains all possible top-level event keys and uses generic Obj’s for object keys (content and unsigned)

content: mautrix.types.Obj
type: mautrix.types.EventType
room_id: Optional[mautrix.types.RoomID]
event_id: Optional[mautrix.types.EventID]
sender: Optional[mautrix.types.UserID]
timestamp: Optional[int]
state_key: Optional[str]
unsigned: mautrix.types.Obj
redacts: Optional[mautrix.types.EventID]
class mautrix.types.ImageInfo

Information about an image message.

height: int
width: int
orientation: int
class mautrix.types.InReplyTo
event_id: mautrix.types.EventID
class mautrix.types.JoinRule

An enumeration.

PUBLIC = 'public'
KNOCK = 'knock'
RESTRICTED = 'restricted'
INVITE = 'invite'
PRIVATE = 'private'
class mautrix.types.JoinRulesStateEventContent
join_rule: mautrix.types.JoinRule
allow: Optional[List[mautrix.types.event.state.JoinRestriction]]
class mautrix.types.JSONWebKey
key: str
algorithm: str
extractable: bool
key_type: str
key_ops: List[str]
class mautrix.types.KeyRequestAction
REQUEST: KeyRequestAction = <KeyRequestAction.REQUEST: 'request'>
CANCEL: KeyRequestAction = <KeyRequestAction.CANCEL: 'request_cancellation'>
class mautrix.types.LocationInfo

Information about a location message.

thumbnail_url: Optional[mautrix.types.ContentURI]
thumbnail_info: Optional[mautrix.types.ThumbnailInfo]
thumbnail_file: Optional[mautrix.types.EncryptedFile]
class mautrix.types.LocationMessageEventContent
geo_uri: str
info: mautrix.types.LocationInfo
class mautrix.types.MediaMessageEventContent

The content of a media message event (m.image, m.audio, m.video, m.file)

static deserialize_info(data)
Parameters

data (mautrix.types.JSON) –

Return type

Union[mautrix.types.ImageInfo, mautrix.types.VideoInfo, mautrix.types.AudioInfo, mautrix.types.FileInfo, mautrix.types.Obj]

url: Optional[mautrix.types.ContentURI]
info: Optional[Union[mautrix.types.ImageInfo, mautrix.types.VideoInfo, mautrix.types.AudioInfo, mautrix.types.FileInfo, mautrix.types.Obj]]
file: Optional[mautrix.types.EncryptedFile]
class mautrix.types.Membership

The membership state of a user in a room as specified in section 8.4 Room membership of the spec.

JOIN = 'join'
LEAVE = 'leave'
INVITE = 'invite'
BAN = 'ban'
KNOCK = 'knock'
class mautrix.types.MemberStateEventContent

The content of a membership event. Spec link

membership: mautrix.types.Membership
avatar_url: mautrix.types.ContentURI
displayname: str
is_direct: bool
reason: str
third_party_invite: mautrix.types.JSON
class mautrix.types.MessageEvent

An m.room.message event

static deserialize_content(data)
Parameters

data (mautrix.types.JSON) –

Return type

Union[mautrix.types.TextMessageEventContent, mautrix.types.MediaMessageEventContent, mautrix.types.LocationMessageEventContent, mautrix.types.Obj]

make_reply_fallback_html(displayname=None)

Generate the HTML fallback for messages replying to this event.

Parameters

displayname (Optional[str]) –

Return type

str

make_reply_fallback_text(displayname=None)

Generate the plaintext fallback for messages replying to this event.

Parameters

displayname (Optional[str]) –

Return type

str

content: Union[mautrix.types.TextMessageEventContent, mautrix.types.MediaMessageEventContent, mautrix.types.LocationMessageEventContent, mautrix.types.Obj]
unsigned: Optional[mautrix.types.MessageUnsigned]
class mautrix.types.MessageType

A message type.

property is_media: bool
property is_text: bool
TEXT: MessageType = <MessageType.TEXT: 'm.text'>
EMOTE: MessageType = <MessageType.EMOTE: 'm.emote'>
NOTICE: MessageType = <MessageType.NOTICE: 'm.notice'>
IMAGE: MessageType = <MessageType.IMAGE: 'm.image'>
STICKER: MessageType = <MessageType.STICKER: 'm.sticker'>
VIDEO: MessageType = <MessageType.VIDEO: 'm.video'>
AUDIO: MessageType = <MessageType.AUDIO: 'm.audio'>
FILE: MessageType = <MessageType.FILE: 'm.file'>
LOCATION: MessageType = <MessageType.LOCATION: 'm.location'>
class mautrix.types.MessageUnsigned

Unsigned information sent with message events.

transaction_id: str
class mautrix.types.OlmCiphertext
body: str
type: mautrix.types.OlmMsgType
class mautrix.types.OlmMsgType

An enumeration.

PREKEY = 0
MESSAGE = 1
__new__(value)
class mautrix.types.PowerLevelStateEventContent

The content of a power level event.

ensure_event_level(event_type, level)
Parameters
Return type

bool

ensure_user_level(user_id, level)
Parameters
Return type

bool

get_event_level(event_type)
Parameters

event_type (mautrix.types.EventType) –

Return type

int

get_user_level(user_id)
Parameters

user_id (mautrix.types.UserID) –

Return type

int

set_event_level(event_type, level)
Parameters
Return type

None

set_user_level(user_id, level)
Parameters
Return type

None

users: Dict[mautrix.types.UserID, int]
users_default: int
events: Dict[mautrix.types.EventType, int]
events_default: int
state_default: int
invite: int
kick: int
ban: int
redact: int
class mautrix.types.PresenceEvent
sender: mautrix.types.UserID
content: mautrix.types.PresenceEventContent
class mautrix.types.PresenceEventContent
presence: mautrix.types.PresenceState
last_active_ago: int
status_msg: str
currently_active: bool
class mautrix.types.PresenceState

An enumeration.

ONLINE = 'online'
OFFLINE = 'offline'
UNAVAILABLE = 'unavailable'
class mautrix.types.ReactionEvent

A m.reaction event

property unsigned: mautrix.types.BaseUnsigned
content: mautrix.types.ReactionEventContent
class mautrix.types.ReactionEventContent

The content of an m.reaction event

property relates_to: mautrix.types.RelatesTo
class mautrix.types.ReceiptEvent
room_id: mautrix.types.RoomID
content: Dict[mautrix.types.EventID, Dict[mautrix.types.ReceiptType, Dict[mautrix.types.UserID, mautrix.types.SingleReceiptEventContent]]]
class mautrix.types.ReceiptType

An enumeration.

READ = 'm.read'
class mautrix.types.RedactionEvent

A m.room.redaction event

property unsigned: mautrix.types.BaseUnsigned
content: mautrix.types.RedactionEventContent
redacts: mautrix.types.EventID
class mautrix.types.RedactionEventContent

The content of an m.room.redaction event

reason: str
class mautrix.types.RelatesTo

Message relations. Used for reactions, edits and replies.

serialize()

Convert this object into objects directly serializable with json.

Return type

mautrix.types.JSON

rel_type: mautrix.types.RelationType
event_id: Optional[mautrix.types.EventID]
key: Optional[str]
is_falling_back: Optional[bool]
in_reply_to: Optional[mautrix.types.InReplyTo]
class mautrix.types.RelationType
ANNOTATION: RelationType = <RelationType.ANNOTATION: 'm.annotation'>
REFERENCE: RelationType = <RelationType.REFERENCE: 'm.reference'>
REPLACE: RelationType = <RelationType.REPLACE: 'm.replace'>
THREAD: RelationType = <RelationType.THREAD: 'm.thread'>
class mautrix.types.RequestedKeyInfo
algorithm: mautrix.types.EncryptionAlgorithm
room_id: mautrix.types.RoomID
sender_key: mautrix.types.IdentityKey
session_id: mautrix.types.SessionID
class mautrix.types.RoomAvatarStateEventContent
url: Optional[mautrix.types.ContentURI]
class mautrix.types.RoomCreateStateEventContent
room_version: str
federate: bool
predecessor: Optional[mautrix.types.RoomPredecessor]
type: Optional[mautrix.types.RoomType]
class mautrix.types.RoomEncryptionStateEventContent
algorithm: mautrix.types.EncryptionAlgorithm
rotation_period_ms: int
rotation_period_msgs: int
class mautrix.types.RoomKeyEventContent
algorithm: mautrix.types.EncryptionAlgorithm
room_id: mautrix.types.RoomID
session_id: mautrix.types.SessionID
session_key: str
class mautrix.types.RoomKeyRequestEventContent
action: mautrix.types.KeyRequestAction
requesting_device_id: mautrix.types.DeviceID
request_id: str
body: Optional[mautrix.types.RequestedKeyInfo]
class mautrix.types.RoomKeyWithheldCode
BLACKLISTED: RoomKeyWithheldCode = <RoomKeyWithheldCode.BLACKLISTED: 'm.blacklisted'>
UNVERIFIED: RoomKeyWithheldCode = <RoomKeyWithheldCode.UNVERIFIED: 'm.unverified'>
UNAUTHORIZED: RoomKeyWithheldCode = <RoomKeyWithheldCode.UNAUTHORIZED: 'm.unauthorized'>
UNAVAILABLE: RoomKeyWithheldCode = <RoomKeyWithheldCode.UNAVAILABLE: 'm.unavailable'>
NO_OLM_SESSION: RoomKeyWithheldCode = <RoomKeyWithheldCode.NO_OLM_SESSION: 'm.no_olm'>
class mautrix.types.RoomKeyWithheldEventContent
algorithm: mautrix.types.EncryptionAlgorithm
sender_key: mautrix.types.IdentityKey
code: mautrix.types.RoomKeyWithheldCode
reason: Optional[str]
room_id: Optional[mautrix.types.RoomID]
session_id: Optional[mautrix.types.SessionID]
class mautrix.types.RoomNameStateEventContent
name: str
class mautrix.types.RoomPinnedEventsStateEventContent
pinned: List[mautrix.types.EventID]
class mautrix.types.RoomPredecessor
room_id: mautrix.types.RoomID
event_id: mautrix.types.EventID
class mautrix.types.RoomTagAccountDataEventContent
tags: Dict[str, mautrix.types.RoomTagInfo]
class mautrix.types.RoomTagInfo
order: Union[int, float, str]
class mautrix.types.RoomTombstoneStateEventContent
body: str
replacement_room: mautrix.types.RoomID
class mautrix.types.RoomTopicStateEventContent
topic: str
class mautrix.types.RoomType
value: Any
class mautrix.types.SingleReceiptEventContent
ts: int
class mautrix.types.SpaceChildStateEventContent
via: List[str]
order: str
suggested: bool
class mautrix.types.SpaceParentStateEventContent
via: List[str]
canonical: bool
class mautrix.types.StateEvent

A room state event.

classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (mautrix.types.JSON) –

Return type

mautrix.types.StateEvent

static deserialize_content(data)
Parameters

data (mautrix.types.JSON) –

Return type

Union[mautrix.types.PowerLevelStateEventContent, mautrix.types.MemberStateEventContent, mautrix.types.CanonicalAliasStateEventContent, mautrix.types.RoomNameStateEventContent, mautrix.types.RoomAvatarStateEventContent, mautrix.types.RoomTopicStateEventContent, mautrix.types.RoomPinnedEventsStateEventContent, mautrix.types.RoomTombstoneStateEventContent, mautrix.types.RoomEncryptionStateEventContent, mautrix.types.RoomCreateStateEventContent, mautrix.types.SpaceChildStateEventContent, mautrix.types.SpaceParentStateEventContent, mautrix.types.JoinRulesStateEventContent, mautrix.types.Obj]

property prev_content: Union[mautrix.types.PowerLevelStateEventContent, mautrix.types.MemberStateEventContent, mautrix.types.CanonicalAliasStateEventContent, mautrix.types.RoomNameStateEventContent, mautrix.types.RoomAvatarStateEventContent, mautrix.types.RoomTopicStateEventContent, mautrix.types.RoomPinnedEventsStateEventContent, mautrix.types.RoomTombstoneStateEventContent, mautrix.types.RoomEncryptionStateEventContent, mautrix.types.RoomCreateStateEventContent, mautrix.types.SpaceChildStateEventContent, mautrix.types.SpaceParentStateEventContent, mautrix.types.JoinRulesStateEventContent, mautrix.types.Obj]
state_key: str
content: Union[mautrix.types.PowerLevelStateEventContent, mautrix.types.MemberStateEventContent, mautrix.types.CanonicalAliasStateEventContent, mautrix.types.RoomNameStateEventContent, mautrix.types.RoomAvatarStateEventContent, mautrix.types.RoomTopicStateEventContent, mautrix.types.RoomPinnedEventsStateEventContent, mautrix.types.RoomTombstoneStateEventContent, mautrix.types.RoomEncryptionStateEventContent, mautrix.types.RoomCreateStateEventContent, mautrix.types.SpaceChildStateEventContent, mautrix.types.SpaceParentStateEventContent, mautrix.types.JoinRulesStateEventContent, mautrix.types.Obj]
unsigned: Optional[mautrix.types.StateUnsigned]
class mautrix.types.StateUnsigned
invite_room_state: Optional[List[mautrix.types.StrippedStateEvent]]
class mautrix.types.StrippedStateEvent

Stripped state events included with some invite events.

classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (mautrix.types.JSON) –

Return type

mautrix.types.StrippedStateEvent

property prev_content: Union[mautrix.types.PowerLevelStateEventContent, mautrix.types.MemberStateEventContent, mautrix.types.CanonicalAliasStateEventContent, mautrix.types.RoomNameStateEventContent, mautrix.types.RoomAvatarStateEventContent, mautrix.types.RoomTopicStateEventContent, mautrix.types.RoomPinnedEventsStateEventContent, mautrix.types.RoomTombstoneStateEventContent, mautrix.types.RoomEncryptionStateEventContent, mautrix.types.RoomCreateStateEventContent, mautrix.types.SpaceChildStateEventContent, mautrix.types.SpaceParentStateEventContent, mautrix.types.JoinRulesStateEventContent, mautrix.types.Obj]
content: Union[mautrix.types.PowerLevelStateEventContent, mautrix.types.MemberStateEventContent, mautrix.types.CanonicalAliasStateEventContent, mautrix.types.RoomNameStateEventContent, mautrix.types.RoomAvatarStateEventContent, mautrix.types.RoomTopicStateEventContent, mautrix.types.RoomPinnedEventsStateEventContent, mautrix.types.RoomTombstoneStateEventContent, mautrix.types.RoomEncryptionStateEventContent, mautrix.types.RoomCreateStateEventContent, mautrix.types.SpaceChildStateEventContent, mautrix.types.SpaceParentStateEventContent, mautrix.types.JoinRulesStateEventContent, mautrix.types.Obj]
room_id: mautrix.types.RoomID
sender: mautrix.types.UserID
type: mautrix.types.EventType
state_key: str
unsigned: Optional[mautrix.types.event.state.StrippedStateUnsigned]
class mautrix.types.TextMessageEventContent

The content of a text message event (m.text, m.notice, m.emote)

ensure_has_html()
Return type

None

formatted(format)
Parameters

format (mautrix.types.Format) –

Return type

Optional[str]

set_reply(reply_to, *, displayname=None)
Parameters
Return type

None

trim_reply_fallback()
Return type

None

format: mautrix.types.Format
formatted_body: str
class mautrix.types.ThumbnailInfo

Information about the thumbnail for a document, video, image or location.

height: int
width: int
orientation: int
class mautrix.types.ToDeviceEvent
classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (mautrix.types.JSON) –

Return type

mautrix.types.ToDeviceEvent

static deserialize_content(data)
Parameters

data (mautrix.types.JSON) –

Return type

Union[mautrix.types.Obj, mautrix.types.EncryptedOlmEventContent, mautrix.types.RoomKeyWithheldEventContent, mautrix.types.RoomKeyEventContent, mautrix.types.RoomKeyRequestEventContent, mautrix.types.ForwardedRoomKeyEventContent]

sender: mautrix.types.UserID
content: Union[mautrix.types.Obj, mautrix.types.EncryptedOlmEventContent, mautrix.types.RoomKeyWithheldEventContent, mautrix.types.RoomKeyEventContent, mautrix.types.RoomKeyRequestEventContent, mautrix.types.ForwardedRoomKeyEventContent]
class mautrix.types.TypingEvent
room_id: mautrix.types.RoomID
content: mautrix.types.TypingEventContent
class mautrix.types.TypingEventContent
user_ids: List[mautrix.types.UserID]
class mautrix.types.VideoInfo

Information about a video message.

duration: int
orientation: int
class mautrix.types.EventFilter

Event filter object, as specified in the create filter endpoint.

limit: int
not_senders: List[mautrix.types.UserID]
not_types: List[mautrix.types.EventType]
senders: List[mautrix.types.UserID]
types: List[mautrix.types.EventType]
class mautrix.types.Filter

Base filter object, as specified in the create filter endpoint.

event_fields: List[str]
event_format: mautrix.types.filter.EventFormat
presence: mautrix.types.EventFilter
account_data: mautrix.types.EventFilter
room: mautrix.types.RoomFilter
class mautrix.types.RoomEventFilter

Room event filter object, as specified in the create filter endpoint.

lazy_load_members: bool
include_redundant_members: bool
not_rooms: List[mautrix.types.RoomID]
rooms: List[mautrix.types.RoomID]
contains_url: bool
class mautrix.types.RoomFilter

Room filter object, as specified in the create filter endpoint.

not_rooms: List[mautrix.types.RoomID]
rooms: List[mautrix.types.RoomID]
ephemeral: mautrix.types.RoomEventFilter
include_leave: bool
state: mautrix.types.StateFilter
timeline: mautrix.types.RoomEventFilter
account_data: mautrix.types.RoomEventFilter
class mautrix.types.StateFilter

State event filter object, as specified in the create filter endpoint. Currently this is the same as RoomEventFilter.

class mautrix.types.IdentifierType

The type qualifier for entities in a Matrix URI.

EVENT = '$'
USER = '@'
ROOM_ALIAS = '#'
ROOM_ID = '!'
property sigil: str

The sigil of the identifier, used in Matrix events, matrix.to URLs and other places

property uri_type_qualifier: str

The type qualifier of the identifier, only used in matrix: URIs.

classmethod from_sigil(sigil)

Get the IdentifierType corresponding to the given sigil.

Parameters

sigil (str) –

Return type

mautrix.types.IdentifierType

classmethod from_uri_type_qualifier(uri_type_qualifier)

Get the IdentifierType corresponding to the given matrix: URI type qualifier.

Parameters

uri_type_qualifier (str) –

Return type

mautrix.types.IdentifierType

class mautrix.types.MatrixURI

A container for Matrix URI data. Supports parsing and generating both matrix: URIs and https://matrix.to URLs with the same interface.

URI_BY_DEFAULT: ClassVar[bool] = False
__init__()

Internal initializer for MatrixURI, external users should use either build() or parse().

Return type

None

classmethod build(part1, part2=None, via=None, action=None)

Construct a MatrixURI instance using an identifier.

Parameters
Returns

The constructed MatrixURI.

Raises

ValueError – if one of the identifiers doesn’t have a valid sigil.

Return type

mautrix.types.MatrixURI

Examples

>>> from mautrix.types import MatrixURI, UserID, RoomAlias, EventID
>>> MatrixURI.build(UserID("@user:example.com")).matrix_to_url
'https://matrix.to/#/%40user%3Aexample.com'
>>> MatrixURI.build(UserID("@user:example.com")).matrix_uri
'matrix:u/user:example.com'
>>> # Picks the format based on the URI_BY_DEFAULT field.
>>> # The default value will be changed to True in a later release.
>>> str(MatrixURI.build(UserID("@user:example.com")))
'https://matrix.to/#/%40user%3Aexample.com'
>>> MatrixURI.build(RoomAlias("#room:example.com"), EventID("$abc123")).matrix_uri
'matrix:r/room:example.com/e/abc123'
property event_id: Optional[mautrix.types.EventID]

Get the event ID from this parsed URI.

Returns

The event ID in this URI, or None if this is not a link to an event in a room.

property matrix_to_url: str

Convert this parsed URI into a https://matrix.to URL.

Returns

The link as a matrix.to URL.

property matrix_uri: str

Convert this parsed URI into a matrix: URI.

Returns

The link as a matrix: URI.

classmethod parse(url)

Parse a matrix: URI or https://matrix.to URL into parts.

Parameters

url (str | yarl.URL) – The URI to parse, either as a string or a yarl.URL instance.

Returns

The parsed data.

Raises
  • ValueError – if yarl fails to parse the given URL string.

  • MatrixURIError – if the URL isn’t valid in the Matrix spec.

Return type

mautrix.types.MatrixURI

Examples

>>> from mautrix.types import MatrixURI
>>> MatrixURI.parse("https://matrix.to/#/@user:example.com").user_id
'@user:example.com'
>>> MatrixURI.parse("https://matrix.to/#/#room:example.com/$abc123").event_id
'$abc123'
>>> MatrixURI.parse("matrix:r/room:example.com/e/abc123").event_id
'$abc123'
property room_alias: Optional[mautrix.types.RoomAlias]

Get the room alias from this parsed URI.

Returns

The room alias in this URI, or None if this is not a link to a room (or event).

property room_id: Optional[mautrix.types.RoomID]

Get the room ID from this parsed URI.

Returns

The room ID in this URI, or None if this is not a link to a room (or event).

classmethod try_parse(url)

Try to parse a matrix: URI or https://matrix.to URL into parts. If parsing fails, return None instead of throwing an error.

Parameters

url (str | yarl.URL) – The URI to parse, either as a string or a yarl.URL instance.

Returns

The parsed data, or None if parsing failed.

Return type

mautrix.types.MatrixURI | None

property user_id: Optional[mautrix.types.UserID]

Get the user ID from this parsed URI.

Returns

The user ID in this URI, or None if this is not a link to a user.

via: list[str] | None
action: URIAction | None
exception mautrix.types.MatrixURIError

Raised by MatrixURI.parse() when parsing a URI fails.

class mautrix.types.URIAction

Represents an intent for what the client should do with a Matrix URI.

value: Any
class mautrix.types.MediaRepoConfig

Matrix media repo config. See GET /_matrix/media/v3/config.

upload_size: int
class mautrix.types.MXOpenGraph

Matrix URL preview response. See GET /_matrix/media/v3/preview_url.

title: str
description: str
image: mautrix.types.OpenGraphImage
video: mautrix.types.OpenGraphVideo
audio: mautrix.types.OpenGraphAudio
class mautrix.types.OpenGraphAudio
url: mautrix.types.ContentURI
mimetype: str
class mautrix.types.OpenGraphImage
url: mautrix.types.ContentURI
mimetype: str
height: int
width: int
size: int
class mautrix.types.OpenGraphVideo
url: mautrix.types.ContentURI
mimetype: str
height: int
width: int
size: int
class mautrix.types.BatchSendResponse
state_event_ids: List[mautrix.types.EventID]
event_ids: List[mautrix.types.EventID]
insertion_event_id: mautrix.types.EventID
batch_event_id: mautrix.types.EventID
base_insertion_event_id: mautrix.types.EventID
next_batch_id: mautrix.types.BatchID
class mautrix.types.DeviceLists
changed: List[mautrix.types.UserID]
left: List[mautrix.types.UserID]
class mautrix.types.DeviceOTKCount
curve25519: int
signed_curve25519: int
class mautrix.types.PaginatedMessages

PaginatedMessages(start, end, events)

static __new__(_cls, start, end, events)

Create new instance of PaginatedMessages(start, end, events)

Parameters
end: mautrix.types.SyncToken

Alias for field number 1

events: List[mautrix.types.Event]

Alias for field number 2

start: mautrix.types.SyncToken

Alias for field number 0

class mautrix.types.PaginationDirection

Pagination direction used in various endpoints that support pagination.

FORWARD = 'f'
BACKWARD = 'b'
class mautrix.types.RoomAliasInfo

Room alias query result, as specified in the alias resolve endpoint

room_id: mautrix.types.RoomID
servers: List[str]
class mautrix.types.RoomCreatePreset

Room creation preset, as specified in the createRoom endpoint

PRIVATE = 'private_chat'
TRUSTED_PRIVATE = 'trusted_private_chat'
PUBLIC = 'public_chat'
class mautrix.types.RoomDirectoryResponse
chunk: List[mautrix.types.misc.PublicRoomInfo]
next_batch: mautrix.types.DirectoryPaginationToken
prev_batch: mautrix.types.DirectoryPaginationToken
total_room_count_estimate: int
class mautrix.types.RoomDirectoryVisibility

Room directory visibility, as specified in the createRoom endpoint

PRIVATE = 'private'
PUBLIC = 'public'
class mautrix.types.VersionsResponse
property has_legacy_versions: bool
property has_modern_versions: bool
versions: List[str]
unstable_features: Dict[str, bool]
class mautrix.types.PushActionDict
set_tweak: Optional[str]
value: Optional[str]
class mautrix.types.PushActionType
value: Any
class mautrix.types.PushCondition
kind: mautrix.types.PushConditionKind
key: Optional[str]
pattern: Optional[str]
operator: mautrix.types.PushOperator
class mautrix.types.PushConditionKind
value: Any
class mautrix.types.PushOperator
value: Any
class mautrix.types.PushRule
rule_id: Union[mautrix.types.RoomID, mautrix.types.UserID, str]
default: bool
enabled: bool
actions: List[Union[mautrix.types.PushActionDict, mautrix.types.PushActionType]]
conditions: List[mautrix.types.PushCondition]
pattern: Optional[str]
class mautrix.types.PushRuleKind
value: Any
class mautrix.types.PushRuleScope
value: Any
class mautrix.types.Member
membership: mautrix.types.Membership
avatar_url: mautrix.types.ContentURI
displayname: str
class mautrix.types.User
user_id: mautrix.types.UserID
avatar_url: mautrix.types.ContentURI
displayname: str
class mautrix.types.UserSearchResults

UserSearchResults(results, limit)

static __new__(_cls, results, limit)

Create new instance of UserSearchResults(results, limit)

Parameters
limit: int

Alias for field number 1

results: List[mautrix.types.User]

Alias for field number 0

class mautrix.types.ExtensibleEnum
static __new__(cls, value)
Parameters
Return type

mautrix.types.ExtensibleEnum

classmethod deserialize(raw)

Convert the given data parsed from JSON into an object of this type.

Parameters

raw (mautrix.types.JSON) –

Return type

Any

property key: str
serialize()

Convert this object into objects directly serializable with json.

Return type

mautrix.types.JSON

value: Any
class mautrix.types.Lst
classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (list[mautrix.types.JSON]) –

Return type

mautrix.types.Lst

serialize()

Convert this object into objects directly serializable with json.

Return type

list[mautrix.types.JSON]

class mautrix.types.Obj
classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (dict[str, mautrix.types.JSON]) –

Return type

mautrix.types.Obj

get(key, default=None)
popitem()
serialize()

Convert this object into objects directly serializable with json.

Return type

dict[str, mautrix.types.JSON]

class mautrix.types.Serializable

Serializable is the base class for types with custom JSON serializers.

classmethod deserialize(raw)

Convert the given data parsed from JSON into an object of this type.

Parameters

raw (mautrix.types.JSON) –

Return type

mautrix.types.util.serializable.SerializableSubtype

json()

Serialize this object and dump the output as JSON.

Return type

str

classmethod parse_json(data)

Parse the given string as JSON and deserialize the result into this type.

Parameters

data (Union[str, bytes]) –

Return type

mautrix.types.util.serializable.SerializableSubtype

serialize()

Convert this object into objects directly serializable with json.

Return type

mautrix.types.JSON

class mautrix.types.SerializableAttrs

An abstract Serializable that assumes the subclass is an attrs dataclass.

Examples

>>> from attr import dataclass
>>> from mautrix.types import SerializableAttrs
>>> @dataclass
... class Foo(SerializableAttrs):
...     index: int
...     field: Optional[str] = None
classmethod deserialize(data)

Convert the given data parsed from JSON into an object of this type.

Parameters

data (mautrix.types.JSON) –

Return type

mautrix.types.util.serializable.SerializableSubtype

get(item, default=None)
Parameters
  • item (str) –

  • default (Optional[Any]) –

Return type

Any

serialize()

Convert this object into objects directly serializable with json.

Return type

mautrix.types.JSON

unrecognized_: Dict[str, mautrix.types.JSON]
class mautrix.types.SerializableEnum

A simple Serializable implementation for Enums.

Examples

>>> class MyEnum(SerializableEnum):
...     FOO = "foo value"
...     BAR = "hmm"
>>> MyEnum.FOO.serialize()
"foo value"
>>> MyEnum.BAR.json()
'"hmm"'
__init__(_)

A fake __init__ to stop the type checker from complaining. Enum’s __new__ overrides this.

Return type

None

__new__(value)
exception mautrix.types.SerializerError

SerializerErrors are raised if something goes wrong during serialization or deserialization.

mautrix.types.deserializer(elem_type)

Define a custom deserialization function for a given type hint.

Parameters

elem_type (Type[mautrix.types.util.serializable_attrs.T]) – The type hint to define the deserializer for.

Returns

Decorator for the function. The decorator will simply add the function to a map of deserializers and return the function.

Return type

Callable[[mautrix.types.util.serializable_attrs.Deserializer], mautrix.types.util.serializable_attrs.Deserializer]

Examples

>>> from datetime import datetime
>>> from mautrix.types import deserializer, JSON
>>> @deserializer(datetime)
... def deserialize_datetime(data: JSON) -> datetime:
...     return datetime.fromtimestamp(data)
mautrix.types.field(default=NOTHING, factory=None, json=None, flatten=False, hidden=False, ignore_errors=False, omit_empty=True, omit_default=False, metadata=None, **kwargs)

A wrapper around attr.ib() to conveniently add SerializableAttrs metadata fields.

Parameters
  • default (Any) – Same as attr.ib, the default value for the field.

  • factory (Optional[Callable[[], Any]]) – Same as attr.ib, a factory function that creates the default value.

  • json (Optional[str]) – The JSON key used for de/serializing the object.

  • flatten (bool) – Set to flatten subfields inside this field to be a part of the parent object in serialized objects. When deserializing, the input data will be deserialized into both the parent and child fields, so the classes should ignore unknown keys.

  • hidden (bool) – Set to always omit the key from serialized objects.

  • ignore_errors (bool) – Set to ignore type errors while deserializing.

  • omit_empty (bool) – Set to omit the key from serialized objects if the value is None.

  • omit_default (bool) – Set to omit the key from serialized objects if the value is equal to the default.

  • metadata (Optional[Dict[str, Any]]) – Additional metadata for attr.ib.

  • **kwargs – Additional keyword arguments for attr.ib.

Returns

The decorator function returned by attr.ib.

Examples

>>> from attr import dataclass
>>> from mautrix.types import SerializableAttrs, field
>>> @dataclass
... class SomeData(SerializableAttrs):
...     my_field: str = field(json="com.example.namespaced_field", default="hi")
...
>>> SomeData().serialize()
{'com.example.namespaced_field': 'hi'}
>>> SomeData.deserialize({"com.example.namespaced_field": "hmm"})
SomeData(my_field='hmm')
mautrix.types.serializer(elem_type)

Define a custom serialization function for the given type.

Parameters

elem_type (Type[mautrix.types.util.serializable_attrs.T]) – The type to define the serializer for.

Returns

Decorator for the function. The decorator will simply add the function to a map of deserializers and return the function.

Return type

Callable[[mautrix.types.util.serializable_attrs.Serializer], mautrix.types.util.serializable_attrs.Serializer]

Examples

>>> from datetime import datetime
>>> from mautrix.types import serializer, JSON
>>> @serializer(datetime)
... def serialize_datetime(dt: datetime) -> JSON:
...     return dt.timestamp()