discord-py-buttons 1.1.1

A discord button handler for discord.py

discord.py button docs

https://pypi.org/project/discord-py-buttons/

Introduction

This is a discord.py button extension made by 404kuso and RedstoneZockt, which you can use until discord.py v2.0 is out

We got some features for you like send buttons, receive a press and edit messages with buttons and everything is compatible with discord.py

License

This project is under MIT License

---

Index

• Initializing
• Client Events
• Sending Butttons
• Receiving a button press
• Complete example
• Code docs
• Changelog

---

Get started

First things first, the installation for this package

py -m pip install discord_py_buttons 

Then you need a discord.ext.commands.Bot client in your code

import discord
from discord.ext import commands

client = commands.Bot(" ")

To initialize the button extension, you need to import the Buttons class

from discord_py_buttons import Buttons

client.buttons = Buttons(client)

This will add a listener to button presses and will grant you acces to the button tools

---

Events

These events can be received trought client.listen('eventName') or can be awaited with client.wait_for('eventName', filter)

on_button_press

This event will be dispatched if a user pressed a button (a new interaction was created)

The parameters passed to your function will be

• PressedButton

  The Button which was pressed

• Message

  The message on which the button was pressed

If you want to listen to it, your function should look something like this

@client.listen('on_button_press')
async def on_button(btn: PressedButton, message: ResponseMessage)
    # code goes here

If you want to await this event, use

btn, msg = await client.wait_for('on_button_press', lambda btn, msg: check here)

---

Sending

To send a button message, you need the send function from a Buttons instance

Example:

from discord_py_buttons import Button

@client.listen('on_message')
async def on_message(message: discord.Message):
    if message.content == "!btn":
        await client.buttons.send(message.channel, "here you go", buttons=[Button("myID", "Press me", emoji="😀")])

---

Receiving

If you want to receive a button press, you need to listen to the on_button_press event with client.listen('on_button_press')

There will be two parameters which will be passed to your function

• PressedButton

  The button which was pressed

• ResponseMessage

  The message on which the button was pressed

To respond to the interaction, you should use msg.respond()

Example:

@client.listen('on_button_press')
async def on_button(btn: PressedButton, msg: ResponseMsg):
    await btn.respond("You pressed " + btn.content)

---

Example

Here is an example code, which sends a button everytime a user sends a message with the content !btn and replies to every button press with the content of the button

import discord
from discord.ext import commands
from discord_py_buttons import Buttons, Button, PressedButton, ResponseMessage

client.buttons = Buttons(client)

@client.listen('on_message')
async def on_message(message: discord.Message):
    if message.content == "!btn":
        await client.buttons.send("Here ya go!", buttons=[Button("custom_id", "PRESS ME")])
    
@client.listen('on_button_press')
async def on_button(btn: PressedButton, msg: ResponseMessage):
    await msg.respond("You pressed on " + btn.content + " with the customID " + btn.custom_id)

client.run("Your secret token")

Here is another example code which uses client.wait_for It will send a question in which the message author decides if they like cats or dogs more

Example

import discord
from discord.ext import commands
from discord_py_buttons import Button, Buttons

client = commands.Bot(" ")

@client.listen('on_message')
async def on_message(message: discord.Message):
    if message.content == "!q":
        # This will send the buttons to the textchannel
        question = await client.buttons.send(message.channel, "What do you like the most?", buttons=[Button("cats", label="I like cats", emoji="🐱"), Button("dogs", label="I like dogs", emoji="🐶")])
        # This will wait for a new button press and only continue if the user who pressed the button is the message author and the messageID on which the button was pressed is the same ID as the message we sent (question)
        btn, msg = await client.wait_for("button_press", check=lambda btn, msg: btn.member.id == message.author.id and msg.id == question.id)

        if btn.custom_id == "cats":
            await msg.respond("yay, cats!")
        elif btn.custom_id == "dogs":
            await msg.respond("yay, dogs")

---

---

---

Code docs

Buttons: class

A button instance for using buttons

Initialization

Buttons(client: discord.ext.commands.client)

• client: discord.ext.commands.client

  The bot client

Methods

• send

  async def send(channel, content=None, *, tts=False, embed=None,
              embeds=None, file=None, files = None, delete_after = None, nonce = None,
              allowed_mentions=None, reference=None, mention_author=None, buttons=None
          ) -> Message:
  

  | coroutine |

  Parameters

  • channel: discord.TextChannel

    The textchannel where the message should be sent

  • content: str

    The text content of the message

  • tts: bool

    If the message should be text-to-speech

  • embed: discord.Embed

    The embed included in the message

  • embeds: List[discord.Embed]

    The embeds included in the message

  • file: discord.File

    A file that will be sent as an attachment to the message

  • file: List[discord.File]

    A list of files which will be sent as an attachment

  • delete_after: float

    The numbers of seconds after which the message will be deleted in the background

  • nonce: int

    The nonce to use for sending this message

  • allowed_mentions: discord.Allowed_mentions

    Mentions allowed in this message

  • reference: discord.MessageReference or discord.Message

    The message to which the message replies

  • mention_author: bool

    Whether the author should be mentioned

  • buttons: List[Button]

    A list of buttons in this message

  Returns

  • Message

    The sent message

---

Button: class

Represents a message component button

Initialization

Button(custom_id, label = None, color = None, emoji = None, new_line = False, disabled = True)

• custom_id: str

  A customID for identifying the button, max 100 characters

• label: str

  The text that appears on the button, max 80 characters

• color: str or int

  The color of the button, one of:

  [("blurple", "primary", 1), ("gray", "secondary", 2), ("green", "succes", 3), ("red", "danger", 4)]

  Things in () are the same color

• emoji: discord.Emoji or str

  A emoji appearing before the label

• new_line: bool

  Whether a new line should be added before the button

• disabled: bool

  Whether the button should be clickable (disabled = False) or not (disabled=True)

Attributes

• content: str

  The content of the button (emoji + " " + label)

• custom_id: str

  The customID of the button

• label: str

  The text that appears on the button

• color: str or int

  The color of the button

• emoji: discord.Emoji or str

  The emoji appearing before the label

• new_line: bool

  Whether a new line was added before the button

• disabled: bool

  Whether the button is disabled

• hash: str

  The unique hash for the button

Methods

• to_dict: function -> dict

  def to_dict() -> dict:
  

  Converts the button to a python dictionary

---

LinkButton: class

Represents a message component button that will open a link on click

This type of button will not trigger the on_button_press event

Initialization

LinkButton(url: str, label: str, emoji: discord.Emoji or str, new_line: bool, disabled: bool)

• url: str

  The url which will be opened when clicking the button

• label: str

  A text that appears on the button, max 80 characters

• emoji: discord.Emoji or str

  A emoji appearing before the label

• new_line: bool

  Whether a new line should be added before the button

• disabled: bool

  Whether the button should be clickable (disabled = False) or not (disabled=True)

Attributes

• content: str

  The content of the button (emoji + " " + label)

• url: str

  The link which will be opened when clicking the button

• label: str

  The text that appears on the button, max 80 characters

• color: str or int

  The color of the button

  This will always be 5 (linkButton)

• emoji: discord.Emoji or str

  The emoji appearing before the label

• new_line: bool

  Whether a new line was added before the button

• disabled: bool

  Whether the button is disabled

Methods

• to_dict: function -> dict

  def to_dict() -> dict:
  

  Converts the button to a python dictionary

---

PressedButton: class

Represents an Object of a Button which was pressed, including its interaction

Attributes

• member: discord.Member

  The member who pressed the button

• interaction: dict

  The most important stuff for the interaction which was received

  Values

  • id: str

    The interaction ID

  • token: str

    The interaction token

• content: str

  The content of the button (emoji + " " + label)

• url: str

  The link which will be opened when clicking the button

• label: str

  The text that appears on the button, max 80 characters

• color: str or int

  The color of the button

  This will always be 5 (linkButton)

• emoji: discord.Emoji or str

  The emoji appearing before the label

• new_line: bool

  Whether a new line was added before the button

• disabled: bool

  Whether the button is disabled

  Always True

• hash: str

  The unique hash for the button

---

Message: class

Extends the discord.Message object

Attributes

• buttons: List[Button or LinkButton]

  A list of buttons included in the message

Methods

• edit*: function

  * Modified original function

  Edits the message

  async def edit(*, content = None, embed = None, embeds = None, attachments = None, suppress = None, delete_after = None, allowed_mentions = None, buttons = None):
  

  | coroutine |

  Parameters

  • content: str

    The new text content of the message

  • embed: discord.Embed

    The new embed included in the message

  • embeds: List[discord.Embed]

    The new embeds included in the message

  • attachments: discord.Attachments

    A list of discord attachments included in the message

  • supress: bool

    Whether the embeds in the message should be shown (False) or not (True)

  • delete_after: float

    The numbers of seconds after which the message will be deleted in the background

  • allowed_mentions: discord.Allowed_mentions

    Mentions allowed in this message

  • buttons: List[Button]

    A list of buttons in this message

Super

discord.Message properties

ResponseMessage: class

A class for responding to a (interaction) message

Extends the Message object

Attributes

• pressedButton: Button

  The button which was pressed

• deferred: bool

  Whether the message was deferred

Methods

• defer: function

  defers the interaction

  async def defer(hidden = False):
  

  | coroutine |

  Parameters

  • hidden

    Whether the loading thing will be shown only to the user

  This function should be used if your client needs more than 15 seconds to responod

• respond: function

  Responds to the interaction

  async def respond(content=None, *, tts=False,
          embed = None, embeds=None, file=None, files=None, nonce=None,
          allowed_mentions=None, mention_author=None, buttons=None, hidden=False,
      ninjaMode = False) -> Message or None:
  

  | coroutine |

  Parameters

  • content: str

    The text content of the message

  • tts: bool

    If the message should be text-to-speech

  • embed: discord.Embed

    The embed included in the message

  • embeds: List[discord.Embed]

    The embeds included in the message

  • file: discord.File

    A file which will be sent as an attachment to the message

  • files: List[discord.File]

    A list of files that will be sent as attachment to the message

  • nonce: int

    The nonce to use for sending this message

  • allowed_mentions: discord.Allowed_mentions

    Mentions allowed in this message

  • mention_author: bool

    Whether the author should be mentioned

  • buttons: List[Button]

    A list of buttons in this message

  • hidden: bool

    Whether the message should be only visible to the user

  • ninjaMode: bool

    Whether the client should respond silent like a ninja to the interaction

    (User will see nothing)

  Returns

  • Message or None

    The sent message if ninjaMode and hidden are both set to false

Super

Message properties

---

Events

Added events for client.wait_for and client.listen

• on_button_press

  async def on_button(btn: PressedButton, msg: ResponseMessage):
  

  def check(btn: PressedButton, msg: ResponseMessage):
  

  This event will be dispatched whenever a button was pressed

  Two parameters are passed to the listening function

  PressedButton

  The button which was pressed

  ResponseMessage

  The message with the interaction on which the button was pressed

Changelog

• 1.1.1

  Added

  • Message.edit()

    You can now edit messages with button support

• 1.1.0

  Changed

  • 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

  Added

  • hidden responses

    You can now send responses only visible to the user

  Fixed

  • ResponseMessage.respond()

    Now doesn't show a failed interaction

• 1.0.5

  Fixed

  • ResponseMessage.respond()

    responding now doesn't fail after sending the message, it will now defer the interaction by it self if not already deferred and then send the message

• 1.0.4

  Added

  • ResponseMessage.acknowledged

    Whether the message was acknowledged with the ResponseMessage.acknowledged() function

  Changed

  • 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 ninjaMode is true

• 1.0.3

  Added

  • Button.hash

    Buttons have now a custom hash property, generated by the discord api