discomposer for discord.py

Validate, fetch and send Discord message templates as Components V2.
Design the message in the visual editor, send it from your bot with a code.

Website · Editor · Documentation

discomposer only builds messages. What a button or selection does (open a ticket, hand out a role) stays in your bot.

Install

pip install discomposer

Requires Python 3.11+ and discord.py 2.6+.

Fetch a template and send it

import discord
from discomposer import EditorClient, MediaStore, render_message, select_rows

editor = EditorClient(media=MediaStore("data/media"))

async def send(channel, code):
    design = await editor.fetch(code)  # validates and copies editor/Discord CDN images
    view = discord.ui.LayoutView(timeout=None)
    for item in render_message(
        design,
        guild=channel.guild,
        buttons={"ticket": lambda b: discord.ui.Button(label=b["label"], custom_id="mybot:ticket")},
        slots={"online": "12 members online"},
        selects=lambda menu, guild: select_rows(menu, f"mybot:{menu['id']}"),
    ):
        view.add_item(item)
    await channel.send(view=view, files=editor.media.files_for(design))

render_message returns the text outside the box (if any) and the filled container. Use render to fill a container you created yourself.

Offer your bot's features in the editor

from discomposer import guild_context

link = await editor.open({
    "title": "Ticket panel",
    "context": {
        **guild_context(guild),
        "buttons": [{"id": "ticket", "label": "Open ticket"}],
        "selects": [{"purpose": "ticket_categories", "label": "Ticket categories", "roles": "optional"}],
    },
    "design": {"blocks": [{"text": "## Support"}]},
})

The person designs the message at link and gives your bot the new code.

Handle a selection

Values and roles only ever come from the stored template, never from the interaction:

from discomposer import category_roles, chosen_category, ticket_overwrites

option = chosen_category(saved_design, "tickets", interaction.data["values"][0])
if option:
    roles = category_roles(guild, option)
    channel = await guild.create_text_channel(
        f"ticket-{interaction.user.name}",
        overwrites=ticket_overwrites(guild, interaction.user, roles),
    )

Use your own editor

editor = EditorClient(
    base_url="https://your-editor.example",
    media=MediaStore("data/media"),
)

Shared links supply a code; they never change the configured host. Your editor implements the same open HTTP protocol. The template format and bot library are independent of the closed-source hosted frontend. A reusable backend is available through the JS package's discomposer/server entry point; it serves both bot libraries.

API overview

Errors: TemplateError (format), EditorError (editor, network), MediaError (images). Messages are written for end users.

The template format is specified in spec/FORMAT.md. A JavaScript version for discord.js is available as discomposer on npm.

discomposer is not affiliated with or endorsed by Discord Inc.

Use one MediaStore instance per directory. Saves through that instance serialize quota checks and publish complete files through an atomic rename. Separate processes sharing a directory need coordination supplied by the application.

Image adoption copies editor uploads and Discord CDN images. Other HTTPS image URLs remain external references and depend on their host remaining available.