Introduction

This is the documentation for discord.py-message-components, a library for Python to aid in creating applications that utilise the Discord API.

Prerequisites

discord.py-message-components works with Python 3.8 or higher. Support for earlier versions of Python is not provided. Python 2.7 or lower is not supported. Any version prior to 3.8 will no longer be supported as of v2.0 due to decisions regarding the quality of our codebase.

Installing

To install the library from PyPI using pip:

python3 -m pip install -U discord.py-message-components

py -m pip install -U discord.py-message-components

Voice support (e.g. playing audio in voice channels) is not enabled by default and can be enabled by installing discord.py-message-components[voice] instead of discord.py-message-components.:

python3 -m pip install -U discord.py-message-components[voice]

Note

On Linux environments, installing voice requires getting the following dependencies using your favourite package manager (e.g. apt, yum):

For a Debian-based system, the following command will get these dependencies:

$ apt install libffi-dev libnacl-dev python3-dev

Remember to check your permissions!

py -m pip install -U discord.py-message-components[voice]

Note

On Windows, you need to install the FFmpeg binary yourself. You can download it here.

Save/extract the files somewhere where you won’t accidentally delete them, e.g. C:\\ffmpeg or C:\\Program Files\ffmpeg.

You then need to add the directory containing the binary(s) (should be a folder named bin) to your system’s PATH environment variable.

The procedure for doing this varies depending on which version of Windows you are using.

  1. Open the Start Menu.

  2. Search for environment.

  3. Click Edit the system environment variables

  4. Click the Environment Variables… button.

  5. Select the Path variable under System variables.

  6. Click the Edit… button.

  7. Click the New button.

  8. Paste the path to the directory containing the FFmpeg binary.

  9. Click OK to close all the windows you have opened.

Installing the developer version

You can install the developer (alpha/beta) version from the developer-branch from GitHub. This version is not guaranteed to be stable and may have bugs. But it may have a lot of new features already implemented.

Warning

In order to “clone” and install the repository of this library from GitHub you need to have git installed on your system. If you need help with this take a look → here ←

python3 -m pip install -U git+https://github.com/mccoderpy/discord.py-message-components.git@developer

py -m pip install -U git+https://github.com/mccoderpy/discord.py-message-components.git@developer

Virtual Environments

Sometimes you want to keep libraries from polluting system installs or use a different version of libraries than the ones installed on the system. You might also not have permissions to install libraries system-wide. For this purpose, Pythons standard library comes with a concept called “Virtual Environment”s (often abbreviated to “venv”).

A more in-depth tutorial is found on Virtual Environments and Packages.

However, for the quick and dirty:

  1. Go to your project’s working directory:

    $ cd your-bot-source
$ python3 -m venv bot-env

  2. Activate the virtual environment:

    $ source bot-env/bin/activate

  3. Use pip like usual:

    $ pip install -U discord.py-message-components

  1. Go to your project’s working directory:

    $ cd your-bot-source
$ py -m venv bot-env

  2. Activate the virtual environment:

    $ .\bot-env\Scripts\activate

    Note

    This might show you show an error that tells you that you are not allowed to run scripts on your system. To fix this you need to run the following command in an elevated PowerShell:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

    More information about PowerShell execution policies

  3. Use pip like usual:

    $ pip install -U discord.py-message-components

Congratulations. You now have a virtual environment all set up.

Basic Concepts

discord.py-message-components revolves around the concept of events. An event is something you listen to and then respond to. For example, when a message happens, you will receive an event about it that you can respond to.

A quick example to showcase how events work:

import discord

class MyClient(discord.Client):
    async def on_ready(self):
        print('Logged on as {0}!'.format(self.user))

    async def on_message(self, message):
        print('Message from {0.author}: {0.content}'.format(message))

client = MyClient()
client.run('my token goes here')