Configuration

Introduction

The Config class is the central configuration handler used by Matrix.py. It manages all settings required to connect and authenticate with a Matrix homeserver, including:

• Homeserver URL
• Username (Matrix ID)
• Authentication (password or access token)
• Command prefix
• Loading settings from a YAML file

This documentation explains how to use Config in your bot project.

Overview

Matrix.py's Config allows you to configure your bot in two ways:

• Via a YAML configuration file (recommended)
• Manually through constructor parameters

If a YAML file is provided, it loads values from that file. Otherwise, configuration values can be passed directly. At least one authentication method, either password or token, must be provided.

Warning

If neither PASSWORD nor TOKEN is supplied (either via the YAML file or via parameters), the bot will fail to log in and will raise a ConfigError.

Configuration Options

• HOMESERVER — Matrix homeserver URL (default: https://matrix.org).
• USERNAME — Your bot's Matrix ID (required).
• PASSWORD — Password for your bot account (required unless TOKEN is provided).
• TOKEN — Matrix access token (optional alternative to password).
• PREFIX — Command prefix for bot commands (default: !).

Usage Examples

Load From YAML

from matrix import Bot

bot = Bot(config="config.yaml")

This method loads the configuration from the YAML file and initializes the bot with those settings.

Manual Configuration

You can also configure the bot programmatically without a YAML file:

from matrix import Bot, Config

bot = Bot(
    config=Config(
        homeserver="https://matrix.org",
        username="@yourbot:matrix.org",
        password="your_password",
        prefix="!"
    )
)

This is useful for dynamic setups or scripts where configuration files aren’t necessary.

Behavior and Defaults

• If a configuration file path is passed, Config will load settings from that file.
• If no file is provided, values passed via constructor parameters (username, password, etc.) are used.
• The default homeserver URL is https://matrix.org if none is specified.
• A command prefix is always set, either via YAML or defaulting to "!".