UICord Dev Module

The uicord.dev module provides tools for creating and managing development commands within Discord bots using interactive UI panels, modals, and select menus. It simplifies building commands that accept various argument types (strings, integers, files, channels, roles, etc.) via Discord components.

Note

This module is intended for developer only commands

Installation

pip install uicord

Then import the development module:

import uicord.dev

Quick Start

  1. Register a command using the @register decorator.

  2. Create a Panel with the registered commands.

  3. Show the panel in response to a Discord interaction.

Example:

import discord
from uicord.dev import register, Panel
from uicord.components import View  # if needed

@register()
async def hello(ctx, name: str = "World"):
    await ctx.respond(f"Hello, {name}!")

@register("echo")
async def repeat(ctx, message: str):
    await ctx.respond(f"You said: {message}")

# Inside a command or event
@bot.slash_command()
async def dev_panel(ctx: discord.ApplicationContext):
    panel = Panel(state.DEV_CMDS)   # state.DEV_CMDS holds all registered commands
    await panel.show(ctx)

API Reference

Decorators

uicord.dev.register(name=None)

Classes

class uicord.dev.Option(options)
class uicord.dev.MultiStr

Bases: str

class uicord.dev.Panel(cmds)

Helper Types

class uicord.dev.Option(options)

Detailed Documentation

register

uicord.dev.register(name=None)

Decorator to register a function as a development command.

Parameters:

name (str, optional) – Optional custom name for the command. If not provided, the function’s __name__ is used.

The decorated function can have parameters with type hints. The panel will automatically generate a modal or selector based on the type annotation.

Supported parameter types:

  • str, int → short text input

  • MultiStr → long text input (paragraph)

  • discord.File → file upload (single)

  • bool → checkbox

  • discord.User / discord.Member → user select menu

  • discord.TextChannel → channel select menu

  • discord.Role → role select menu

  • Option[list] → choice select menu (see Option below)

Example:

@register("greet")
async def greet(ctx, user: discord.User, message: str = "Hi!"):
    await ctx.respond(f"{user.mention}: {message}")

The command will be stored in state.DEV_CMDS dictionary.

Option

class uicord.dev.Option(options)

Used to create a choice select menu for a command parameter.

Parameters:

options (list) – List of possible values. Each value will be displayed as a label.

Usage in a parameter annotation:

from uicord.dev import Option

@register()
async def choose(ctx, color: Option["red", "green", "blue"]):
    await ctx.respond(f"You chose {color}")

MultiStr

class uicord.dev.MultiStr

A marker class that indicates a parameter should be a multi-line text input.

Example:

from uicord.dev import MultiStr

@register()
async def feedback(ctx, comment: MultiStr):
    await ctx.respond("Thank you for your feedback!")

Panel

class uicord.dev.Panel(cmds)

Creates an interactive panel that displays registered commands as buttons.

Parameters:

cmds (dict) – Dictionary mapping command names to callables (usually state.DEV_CMDS).

The panel organizes buttons into rows (maximum 5 per row). When a button is clicked, a modal is shown to collect arguments based on the command’s signature.

show(ctx)

Sends the panel as an ephemeral message.

Parameters:

ctx (discord.Interaction) – Discord interaction context (must have respond and author attributes).

run(ctx, cmd)

Internal method that builds and sends a modal for the given command, then executes it upon submission.

Example:

from uicord.dev import Panel, state

panel = Panel(state.DEV_CMDS)
await panel.show(ctx)

The panel will only be visible to the user who invoked it (ephemeral).

How It Works

  1. Registration: The @register decorator adds the function to state.DEV_CMDS.

  2. Panel Creation: Panel iterates over the registered commands and creates a button for each.

  3. Interaction: When a button is clicked, the panel analyses the command’s signature and generates a modal with appropriate input components: - Required parameters are marked as required in the modal. - Default values are pre-filled. - Supported types map to Discord UI elements (text inputs, select menus, file uploads, etc.).

  4. Execution: After the user submits the modal, the panel calls the command with the collected arguments.

Notes

  • The module depends on discord.py (or a fork like py-cord) and the custom .components module (presumably from UICord).

  • Commands are stored in a global state dictionary; restarting the bot clears them.

  • Use only for development – not secure for production because any user who can trigger the panel can execute arbitrary registered commands.

Full Example

import discord
from discord.ext import commands
from uicord.dev import register, Panel, Option, MultiStr, state

bot = commands.Bot(command_prefix="!")

@register()
async def ping(ctx):
    await ctx.respond("Pong!")

@register("add")
async def add_numbers(ctx, a: int, b: int = 0):
    await ctx.respond(f"Result: {a + b}")

@register()
async def announce(ctx, channel: discord.TextChannel, message: MultiStr):
    await channel.send(message)
    await ctx.respond(f"Sent to {channel.mention}")

@register()
async def pick_role(ctx, role: Option(["admin", "mod", "member"])):
    await ctx.respond(f"You picked {role}")

@bot.slash_command()
async def dev(ctx: discord.ApplicationContext):
    panel = Panel(state.DEV_CMDS)
    await panel.show(ctx)

bot.run("TOKEN")

Warning

Ensure the bot has the required intents (e.g., message_content, members) for some features to work.