Welcome to disnake-ext-components’s documentation!#

Getting Started

NOTE#

This branch is currently in a very unfinished, alpha state. As of right now, only buttons are supported. Help with development would be very much appreciated. If you’re interested in helping, please keep an eye on the repo’s issues and the TODO-section of this readme.

disnake-ext-components#

An extension for disnake aimed at making component interactions with listeners somewhat less cumbersome. Requires disnake version 2.5.0 or above and python 3.8.0 or above.

Key Features#

  • Smoothly integrates with disnake,

  • Uses an intuitive dataclass-like syntax to create stateless persistent components,

  • custom_id matching, conversion, and creation are automated for you,

  • (TODO for rewrite!) Allows you to implement custom RegEx for your listeners if you need more customized behavior.

Installing#

Python 3.8 or higher and disnake 2.5.0 or higher are required

To install the extension, run the following command in your command prompt/shell:

# Linux/macOS
python3 -m pip install -U git+https://github.com/DisnakeCommunity/disnake-ext-components.git@rewrite

# Windows
py -3 -m pip install -U git+https://github.com/DisnakeCommunity/disnake-ext-components@rewrite

It will be installed to your existing disnake installation as an extension. From there, it can be imported as:

from disnake.ext import components

Examples#

A very simple component that increments its label each time you click it can be written as follows:

import disnake
from disnake.ext import commands, components


bot = commands.InteractionBot()
manager = components.ComponentManager(bot)
manager.basic_config()


class MyButton(components.RichButton):
    label = "0"

    count: int

    async def callback(self, interaction: components.MessageInteraction) -> None:
        self.count += 1
        self.label = str(self.count)

        await interaction.response.edit_message(components=self)


@bot.slash_command()
async def test_button(inter: disnake.CommandInteraction) -> None:
    wrapped = components.wrap_interaction(inter)
    component = MyButton(count=0)

    await wrapped.send(components=component)


bot.run("TOKEN")

For extra examples, please see the examples folder.

To-Do#

  • Implement more parser types,

  • Implement selects and modals,

  • Implement customisable RegEx-based custom id,

  • Improve Cog support by somehow injecting the cog instance,

  • PyPI release,

  • Contribution guidelines,

Contributing#

Any contributions are welcome, feel free to open an issue or submit a pull request if you would like to see something added. Contribution guidelines will come soon.

Note: due to the file structure of disnake, poetry is unable to install disnake-ext-components into the disnake package in editable mode when you run poetry install. For this reason, I included the script scripts.symlink that automatically symlinks disnake-ext-components into the disnake installation of the python environment you used to run the script. It is exposed as a poetry entrypoint under the name dev-symlink. In other words, running poetry run dev-symlink will automatically symlink disnake-ext-components into your poetry virtual environment’s disnake installation, which should circumvent the issue.

API reference#

API Reference

Development#

Dev