A discord.py extension for using discord ui/interaction features
pip package
βͺ
read the docs
βͺ
examples
This is a discord.py ui extension made by 404kuso and RedstoneZockt for using discord's newest ui features like buttons, slash commands and context commands.
py -m pip install discord-ui
python3 -m pip install discord-ui
This project is under MIT License
If you find any issues, please report them
https://github.com/discord-py-ui/discord-ui/issues
If you want to use slash commands, in the oauth2 invite link generation,
you have to check both bot
and application.commands
fields
Example for creating a simple slash command
import discord
from discord.ext import commands
from discord_ui import UI, SlashOption
client = commands.Bot(" ")
ui = UI(client)
@ui.slash.command("hello_world", options=[SlashOption(bool, "cool", "whether this libary is cool", required=False)], guild_ids=[785567635802816595])
async def command(ctx, cool=True):
"""This is a simple slash command"""
# you can use docstrings for the slash command description too
await ctx.respond("You said this libary is " + str(cool))
client.run("your_token")
Example for creating a user-context command
import discord
from discord.ext import commands
from discurd_ui import UI
client = commands.Bot(" ")
ui = UI(client)
@ui.slash.user_command("avatar", guild_ids=[785567635802816595])
async def avatar(ctx, user: discord.Member):
"""Sends the avatar of a user"""
await ctx.respond(embed=discord.Embed(description=user.display_name).set_image(url=user.avatar_url))
client.run("your_token")
Example for autocompletion of choices
import discord
from discord_ui import UI, SlashOption, AutocompleteInteraction
async def generator(ctx: AutocompleteInteraction):
available_choices = ["hmm", "this", "is", "a", "an", "test", "testing"]
return [(x, x) for x in available_choices if x.startswith(ctx.value_query)]
@ui.slash.command("search_word", options=[SlashOption(str, "query", choice_generator=generator)])
async def search_word(ctx, query):
await ctx.send("got " + query + " for query")
client.run("your_token")
Example for sending a button and receiving it
import discord
from discord.ext import commands
from discord_ui import UI, LinkButton, Button
from asyncio import TimeoutError
client = commands.Bot(" ")
ui = UI(client)
@client.listen("on_message")
async def on_message(message: discord.Message):
if message.content == "!btn":
msg = await message.channel.send("you", components=[
[Button("press me", color="green"), LinkButton("https://discord.com", emoji="π")],
Button(custom_id="my_custom_id")
])
try:
btn = await msg.wait_for("button", client, by=message.author, timeout=20)
await btn.respond("you pressed `" + btn.content + "`")
except TimeoutError:
await msg.delete()
client.run("your_token_here")
Example for sending Selectmenus and receiving them
import discord
from discord.ext import commands
from discord_ui import UI, SelectMenu, SelectOption
from asyncio import TimeoutError
client = commands.Bot(" ")
ui = UI(client)
@client.listen("on_message")
async def on_message(message: discord.Message):
if message.content == "!sel":
msg = await message.channel.send("you", components=[SelectMenu(options=[
SelectOption("my_value", label="test", description="this is a test"),
SelectOption("my_other_value", emoji="π€", description="this is a test too")
], "custom_id", max_values=2)])
try:
sel = await msg.wait_for("select", client, by=message.author, timeout=20)
await sel.respond("you selected `" + str([x.content for x in sel.selected_options]) + "`")
except TimeoutError:
await msg.delete()
client.run("your_token_here")
Example for cogs
from discord.ext import commands
from discord_ui import UI
from discord_ui.cogs import slash_command, subslash_command, listening_component
bot = commands.Bot(" ")
ui = UI(bot)
class Example(commands.Cog):
def __init__(self, bot):
self.bot = bot
@slash_command(name="example", guild_ids=[785567635802816595])
async def example(self, ctx):
await ctx.respond("gotchu")
@subslash_command(base_names="example", name="command"):
async def example_command(self, ctx):
await ctx.respond("okayy")
bot.add_cog(Example(bot))
bot.run("your token")
You can find more (and better) examples here
You can contact us on discord
This will be moved to https://discord-py-ui.github.io/discord-ui/
-
5.1.0
- Component custom ids are now optional, if no custom id is passed, a 100 characters long random string will be used and because of that the order of Component init params changed
- The order of SelectMenus init params changed,
custom_id
comes now afteroptions
SelectMenu("my_custom_id", [options...here]) # is now SelectMenu([options...here], "my_custom_id")
- Same for Buttons
Button("my_custom_id", "label") # is now Button("label", "my_custom_id")
- ButtonStyles is now ButtonStyle
- renamed cog decorators, the old ones still work but they will show a deprecation warning:
slash_command
->slash_command
,subslash_command
->subslash_command
,context_cog
->context_command
,listening_component
->listening_component
- Removed
Slash.edit_command
andSlash.edit_subcommand
, "moved" toCommand.edit
SlashedCommand
is nowSlashInteraction
,SlashedSubCommand
is nowSubSlashInteraction
andSlashedContext
is nowContextInteraction
- The command attributes of CommandInteractions (SlashedCommand, ...) are now moved to
Interaction.command.
(the.command
attribute is a reference to the real command, if you change properties of the command they will be updated) - The component attributes of an interaction are now moved to
.component
- ContextCommands
.param
attribute is now.target
argument_type
in SlashOption is nowtype
ButtonStyle
value names changed: color names are now capitalized andDanger
is nowDestructive
Listener.target_user
is nowListener.target_users
and can take users, members and ids as the valueBaseCommand.options
andSlashOption.options
is now of typeSlashOptionCollection
, which allows you to acces options by index and name
my_command.options["option name"] # or my_command.options[0]
You can also use some methods like
.get
,.set
(which will return itself after it set something, soSlashOption.set(key, value).set(key, value)
would work) andSlashOption.options + SlashOption.option
will add both SlashOptions together- If an invalid guild id was passed to a slashcommand, no exception will be raised anymore, it will just be printed into the console and ignored
logging.error()
- Moved the
discord_ui.ext.py
module into a folder on_button_press
andon_menu_select
is nowon_button
andon_select
. The old event names will still work but will be removed in the next release
- disable_action_row
ActionRow.disable
- no interaction events being dispatched because subclasses of dpy2
commands.Bot
instances wouldn't get overriden which lead to not enabling needed debug events - when no matching component listener in
Listener
could be found, the events for components events wouldn't be dispatched delete_after
keyword in message send override not working- mentionable type in slashoptions not being parsed to objects
@discord.ext.commands.Cooldown
not working on cog slashcommands
**fields
to all functions that edit the message components (like.disable_components
,.disable_component
, ...). The**fields
parameter can be used to edit other properties of the message without using.edit
again and send a "useless" request@Lister.on_error
and@Listener.wrong_user
decorators for handling Exceptions in Listeners- When no keyword was passed to
@Listener.button
or@Listener.select
, the function will be called on every button/slect channel_type
to SlashOption, list ofdiscord.ChannelType
. This will restrict the shown channels for channel slash options to this list.- support for nextcord. Other libs should work too, but they are not tested.
Mentionable
type for SlashOptions- description for short slashoptions. If you set the options for a slash command via callback params, you can add a description (and a type) to them with your docstring. There are 3 different styles you can use:
# style 1 @ui.slash.command() async def my_command(ctx, my_option, my_other_option): """This is my command description my_option: `int`: This is the description for the my_option parameter my_other_option: `str`: This is the description for another option """ ... # style 2 @ui.slash.command() async def my_command(ctx, my_option: int, my_other_option: str): """This is my command description my_option: This is the description for the my_option parameter my_other_option: This is the description for another option """ ... # style 3 @ui.slash.command() async def my_command(ctx, my_option, my_other_option: str): """This is my command description `int`: This is the description for the my_option parameter This is the description for another option """ ...
Note: You don't have to use
`type`
, you can just usetype
- Empty descriptions for slashcommands and slashoptions. The default description value is now
\u200b
which is an "empty" char - Modifying slashcommand options is now WWAAYYYY easier. You can just do
.options[name or index].name = "new name"
and the option will be updated - You can set the autocomplete choice generator with a decorator now
ui.slash.command(options=[SlashOption(str, "my_option")]) async def my_command(ctx, my_option): ... @my_command.options["my_option"].autocomplete_function async def my_generator(ctx): ... # or @my_command.options[0].autocomplete_function async def my_generator(ctx): ...
- All apllication command decorators will now return the created Command
@ui.slash.command(...) async my_command(ctx): ... type(my_command) # SlashCommand
- Added edit and delete method to slashcommand. You can use this for editing or deleting the command later
# edit await my_command.edit(name="test") # delete await my_command.delete()
id
to SlashCommandcommands_synced
event which will be dispatched when all commands where synced with the api (UI.Slash.sync_commands
)BaseCommmand.update
method which updates the api command with the lcoal changesSlashSubCommand.base
, which will be shared among all subslashcommands with the same base
discord.ext.commands.Bot
override for enabling the debug event, this will be enabled when creating a UI instance from the bot
-
5.0.0
- Roles not being parsed correctly
- default_permission
default_permission can now be of type
discord.Permissions
but the api doesn't support that yet.- slash http
some code changes to slash-http features
- ChoiceGeneratorContext
Context class for choice generation
- SlashOption
choice_generator
keyword andautocomplete
keyword.autocomplete
is not needed if you pass choice_generator- File sending
You are now able to send hidden files
-
4.3.7
- SlashOption
Required is now
True
by defaultAttributeError: 'LinkButton' object has no attribute 'component_type'
- decompressing
The lib now doesn't decompress byte data anymore, which means everything before the dpy commit
848d752
doesn't work with this lib.message reference in discordpy discord server
-
4.3.0
Message.wait_for
by keyword doesn't work properly
- Hash
Removed the hash property from Buttons and SelectMenus due to the removal of it from the api
discord_ui.ext
A module with useful tools and decorators to use more information
- BaseCommand
BaseCommand (the superclass for all applicationcommands) has now some extra properties:
- is_chat_input > Whether this command is a slash command - is_message_context > Whether this command is a message context command - is_user_context > Whether this command is a user context command
- SlashedCommand
Added properties:
- is_alias > Whether the invoked command is an alias or not - aliases > All the available aliases for the command
- Listeners
Listeners are something that you can use for a better processing of received components. You could see them as a cog to the message components more information
- SelectInteraction
SelectInteraction.selected_values
are not the raw values that were selected,SelectMenu.selected_options
are the options of typeSlashOption
that were selected- MISSING => None
All instance values that were
MISSING
by default are nowNone
-
4.2.7
on_component
There is now an event with the name
component
that will be dispatched whenever a component was received If you useMessage.wait_for
, there is now a new event choice with the namecomponent
(message.wait_for("component", client)
)- #94
DM issue with deleting messages
edit
Edit now takes "content" as not positional (
.edit("the content")
works now)- component lenght
You are now able to set component values with the right max lenght
-
4.2.0
- cog_remove sync
when you remove a cog the slash commands will now get deleted if you set
delete_unused
to True and setsync_on_cog
to True- alternativ slash options
you don't have to specify options in one of the slash decorators anymore. Instead, you can set them in your callback function Example
@ui.slash.command() async def greet(ctx, user): # This will add an required option with the name "user" of type "user" """Greets a user You can use multiline docstrings, because only the first line will be used for the description """ ... @ui.slash.command() async def tag(ctx, target: discord.User = None): # This will add an optional option with the name "target" of type "user" # Note: you could also use target: "user" = None or anything else you would use in SlashOption for the type ...
- sync_commands
if you would sync the commands after the first sync, it threw an error
-
4.0.0
You now have much more control over your slash commands!
- Permissions
You can update your permissions with the
Slash.update_permissions
function- Creating commands
You can now create slash commands without the decorator in a much more eaisier way! Check out the
Slash.add_command
function- Edit commands
You can edit commands in code with the
Slash.edit_command
function- Listening components
You can add and remove listening components now with the
Components.add_listening_component
,Components.remove_listening_component
andComponents.remove_listening_components
functions- Cogs
You can now use cog decorators like
slash_command
,subslash_command
andlistening_component
- SlashCommand
Slash commands wouldn't be updated if only
default_permission
was changed- wait_for
Message.wait_for now takes
by
andcheck
as parameters andevent_name
andclient
switched place (wait_for(client, "event_name")
is nowwait_for("event_name", client)
)- listening components
You can specify listening_components now more presicely, you can add messages, users, and a check to filter
- Interaction.member
Interaction.member
is nowInteraction.author
- listening comonents
Listening component callback functions now only take one parameter, the used component
on_button_press
andon_menu_select
These events now take a sole parameter, the used component. If you want to acces to message, use
passed_component.message
- ResponseMessage
Removed ResponseMessage
-
3.3.3
- class representation
classes have now a
__repr__
function- UI(override_dpy)
You can now choose whether you want to override some of dpy objects and functions (default is True) (see the override module for more information) This also appeals to the
Components
class (Components(override_dpy)) note: if you don't want to create aUI
object, you can instead override dpy with theoverride_dpy
methodfrom discord_ui import override_dpy override_dpy()
- dpy2
discord.py v2 now auto-decompresses socket data and passes a string instead of the uncompressed data.
- override dpy message
when overriding dpy message object, the components would mix
-
3.2.7
- warnings
- When a guild_permission with an invalid guild id is passed, it will throw an exception when syncing the commands
- When the value of a guild_permission is not of type
SlashPermission
it will throw an exception
- context-commands
You can now have context commands with the same name as a normal slash command
- slashcommand description
You can use docstrings
"""docstring"""
for setting the description of a slash commmand by setting the dosctring for the callback function- auto_defer
auto_defer is now disabled by default
- slash sync
You can now disable auto_sync for slash commmands and sync them by yourself with
Slash.sync_commands(delete_unused)
- Interacion.defer
Interaction._deferred
is notInteraction.deferred
andInteraction.defer()
doesn't throw an exception anymore, it will just log the error withlogging.error()
- try
There was a try/catch in the
Interaction.respond
function that would allow the code to continue when an exception occured while responding with ninja_mode- context commands
There was an issue adding context-commands
- Command checking
Now, the libary only edits commands when changes were made
- warnings
-
3.2.6
- auto ninja_mode
If you use
.respond()
, the function will try to use ninja_mode automatically- project
Moved git-project to https://github.com/discord-py-ui/discord-ui
- ninja_mode response
responding with ninja_mode would end up in an exception
- file sending
fixed another file sending issue with slash commands
-
3.2.4
- Fixed version issues with the package
-
3.2.0
I'm really sorry for all the issues this libary got, if you still find issues, please report them in https://github.com/discord-py-ui/discord-ui/issues
- SelectOpion
There was an issue with emojis not being set in SelectOptions
- LinkButton
There was an issue with setting the url not being set
- SlashCommands
There was an issue with creating commands that don't already exist
- SelectInteraction
.values
is not.selected_values
- Interaction
Buttons and SelectMenus have a
.message
property for the message where their interaction was creted ResponseMessages have a.interaction
property for the received interaction- Events
We added a
interaction_received
event for all interactions that are received -
3.1.0
- discordpy 2 support
We added support for discord.py v2, so you can stay loyal to our libary and use it together with discord.py v2!
- Exceptions
Added own Exceptions for errors
- ParseMethod
You can change the way the extension parses interaction data. You can choose between different Methods
- Auto-defer
The libary will autodefer all interactions public. If you want to change that, take a look at the documentation for this feature
- slashcommand edit check
Slash commands will only be edited if there were some changes, so you won't get a
invalid interaction
error in discord after starting the bot If only permissions were changed, just the permissions will be edited and not the whole command like before- slash commands
I finally fixed the damn slashcommand system, it should work now
- Parsing
The resolving, fetching and pulling from the cache methods should all work
-
2.1.0
- Webhook support
You are now able to use webhooks together with message components, to send a webhook message with the components, use the
Components.send_webhook
function. The standart webhook function is also overriden with the new component function- Float type
You can now use
float
as the argument type for a slash command option- Auto empty names
Buttons, LinkButtons and SelectOptions labels are now by default
\u200b
, which is an "empty" char- Code documentation to more be more informative
-
Fixed small code issues (they were already fixed in previous versions, but I just wanna list this here)
-
Docs are now working
-
2.0.0
-
Slashcomamnd support
Slash
class for slash commandsSlash.command
,Slash.subcommand
andSlash.subcommand_groups
are available for creating slash commandsSlashedCommand
andSlashedSubCommand
are there for used slash commands
-
Message
- disable_action_row(row_numbers:
int
|range
, disable:bool
)
disables (enables) component row(s) in the message
- disable_components(disable:
bool
)
disables (enables) all componentss
- disable_action_row(row_numbers:
-
overrides
Messageable.send
returns Message instead of discord.Message and takes components parameteroverride_client
function added
-
interaction.send
, creates followup messages which can be hidden -
Component.listening_component
A listening component with a callback function that will always be executed whenever a component with the specified custom_id was used
-
Message
- All Message objects don't use the client object anymore
- Message.wait_for now needs the client as the first parameter
- Interaction
All interaction responses work now
- A lot of issues I fogorπ
-
-
1.1.0
- Major changes to request code, now using the client's request
ResponseMessage.acknowledge()
->ResponseMessage.defer()
Changed the name of the function + changed
ResponseMessage.acknowledged
->ResponseMessage.deferred
ResponseMessage.defer()
=>await ResponseMessage.defer()
defer
(acknowledge
) is now async and needs to be awaited
- hidden responses
You can now send responses only visible to the user
ResponseMessage.respond()
Now doesn't show a failed interaction
-
1.0.4
ResponseMessage.acknowledged
Whether the message was acknowledged with the
ResponseMessage.acknowledged()
function
-
ResponseMessage.respond()
=>await ResponseMessage.respond()
respond() function is now async and needs to be awaited
-
ResponseMessage.respond() -> None
=>ResponseMessage.respond() -> Message or None
respond() now returns the sent message or None if ninja_mode is true