mautrix-python

The mautrix.client module provides several specialized mixins that add specific capabilities to a client implementation:

• Syncer: Handles synchronization logic.
• DecryptionDispatcher: Manages the dispatching of decrypted messages.
• EncryptingAPI: Provides interfaces for encrypting data.
• StoreUpdatingAPI: Provides interfaces for updating the internal state/store.

The mautrix.appservice module provides the client API for interacting with Matrix appservices. It contains two primary classes for managing appservice functionality:

• AppServiceAPI: The main interface for an appservice client.
• ChildAppServiceAPI: An interface designed for child appservices (sub-services) within a larger appservice hierarchy.

The mautrix.client.state_store.StateStore class defines the interface for storing and retrieving client state. To persist or manage state in a custom way, you must provide an implementation of this class.

Available implementations include:

• In-memory: Uses RAM for storage (volatile).
• Async database: Uses asyncpg (PostgreSQL) or aiosqlite (SQLite) for persistent storage.
• Flat file: Uses local files for storage.

The mautrix.util.opt_prometheus module provides no-op (no-operation) implementations of Prometheus metrics: Counter, Gauge, Summary, Histogram, Info, and Enum.

Use this module to write code that uses metrics without forcing a hard dependency on the prometheus_client library. This allows your application to function normally even if prometheus_client is not installed in the environment. You can check if the library is available using the is_installed boolean.

The mautrix.client.Client class is a lightweight wrapper. Most of its high-level functionality is provided by various mixins that are included in the class.

While most users should use the high-level Client class, developers building specialized components (like those in the appservice module) may need to extend specific mixins directly. For example, mautrix.appservice.api.IntentAPI extends mautrix.client.StoreUpdatingAPI rather than the full Client class.

The mautrix.types module provides specialized classes for common Matrix identifiers used throughout the library. Instead of using raw strings, you should use these types to ensure data integrity and clarity when interacting with the API.

Key identifier types include:

• UserID: Represents a Matrix user ID (e.g., @user:example.com).
• RoomID: Represents a unique Matrix room ID.
• RoomAlias: Represents a human-readable room alias.
• EventID: Represents a unique identifier for a specific event.
• DeviceID: Represents a specific device identifier.
• SessionID: Represents a session identifier.
• SyncToken: Used for pagination and state tracking during sync operations.
• ContentURI: Represents a URI pointing to content.
• FilterID: Represents an identifier for a filter.
• SigningKey and IdentityKey: Used for cryptographic operations and identity verification.

To extend the bridge with new commands, you can use the command_handler decorator to register a function as a command handler. Commands are processed via a CommandProcessor which receives CommandEvent objects.

Available command categories (sections) for organizing help documentation include:

• SECTION_GENERAL
• SECTION_ADMIN
• SECTION_AUTH
• SECTION_RELAY

from mautrix.bridge.commands import command_handler, CommandEvent

@command_handler
def my_custom_command(event: CommandEvent) -> None:
    # Implementation logic here
    pass

The CommandProcessor is responsible for receiving raw command strings from the bridge and routing them to the correct CommandHandler.

Workflow:

1. Normalization: The command is converted to lowercase.
2. Lookup: The processor checks registered command_handlers and command_aliases.
3. Delegation: If a command is unknown, the processor checks if the sender has a command_status marked as "next". If so, it treats the current input as arguments for the previously pending command.
4. Execution: The handler is called. If an unhandled exception occurs, the processor logs the error and (if evt.print_error_traceback is enabled for admins) sends the traceback to the user.