Intuitive and flexible configuration of interactive embed-based setup panels for discord.py
Project description
SetupPanel
Intuitive and flexible configuration of interactive embed-based setup panels
for discord.py
. This library provides convenient abstraction of "normal" setup
panel code into a powerful, yet simple API.
Requirements
- Python 3.6+
discord.py
Getting Started
If you would like to install discord.py
along with this library, in your
terminal, run:
pip install -U setuppanel[dpy]
To install discord.py
with voice capabilities, run:
pip install -U setuppanel[dpyv]
Or to install just this library, run:
pip install -U setuppanel
You're all set! However, it is recommended to install to a Virtual Environment to avoid polluting your global package installation. For more information, read here.
API
setuppanel.SetupPanel
Attributes
- info
Union[List[Tuple[str, bool, bool, bool]], None]
: information about the steps in aSetupPanel
instance. If steps have been added, returns a list of tuples of the name, conditional flag, loop flag, and group_loop flag of each step. Otherwise,None
- is_used
bool
: if theSetupPanel
instance has already been run len(SetupPanel)
int
: the number of steps this setup panel will run
Parameters
- bot
Union[Bot, AutoShardedBot]
: the instance of a discord bot - ctx
Context
: the command's invocation context - title
str
: the title of this setup panel - duplicate_roles
Optional[bool]
: whether or not this setup panel allows duplicate roles to be specified during a looping step, defaultFalse
- duplicate_role_embed
Optional[discord.Embed]
: the embed to send if a duplicate role is received andduplicate_roles
isFalse
. Defaults toNone
- duplicate_emojis
Optional[bool]
: whether or not this setup panel allows duplicate emojis to be specified during a looping step, defaultFalse
- duplicate_emoji_embed
Optional[discord.Embed]
: the embed to send if a duplicate emoji is received andduplicate_emojis
isFalse
. Defaults toNone
- error_color
Optional[Union[discord.Color, int]]
: the color of the embed that will be sent for the timeout and canceled message
Setup Operation Names
Below are all the various setup names that can be passed into the name
and names
parameters of the API functions.
Please note that the typing information merely describes the return type of a step with a given name, not that the name should be of that type. Provide the name as stated below, for example, content would be provided as
name="content"
- content
str
- message
str
(alias for content) - channel
discord.TextChannel
- role
discord.Role
- emoji
str
- reaction
str
(alias for emoji) - member
discord.Member
- integer
int
- float
float
- title
Union[str, EmptyEmbed]
- description
Union[str, EmptyEmbed]
- color
discord.Color
- author
Union[str, None]
- footer
Union[str, None]
- url
Union[str, None]
Add Step
- Usage:
SetupPanel.add_step(params)
- Parameters:
- name
str
: see valid names - embed
discord.Embed
: the embed to display during the step - timeout
Optional[int]
: the time (in seconds) to wait for a user to respond with an option that satisfiespredicate
. Defaults to120
- predicate
Optional[Callable]
: a function that accepts the output of the appropriatebot.wait_for
listener and returns abool
- name
- Returns class instance for fluuid chaining
Add Conditional Step
- Usage:
SetupPanel.add_conditional_step(params)
- Parameters:
- name
str
: see valid names - embed
discord.Embed
: the embed to display during the step - condition
Callable
: a function that accepts the output of the last step, returning abool
. Step will be executed if the result ofcondition
isTrue
, otherwise the result of this step will beNone
- timeout
Optional[int]
: the time (in seconds) to wait for a user to respond with an option that satisfiespredicate
. Defaults to120
- predicate
Optional[Callable]
: a function that accepts the output of the appropriatebot.wait_for
listener and returns abool
- name
- Returns class instance for fluuid chaining
Add Looping Step
- Usage:
SetupPanel.add_until_finish(params)
- Parameters:
- name
str
: see valid names - embed
discord.Embed
: the embed to display during the step - break_check
Callable
: a function that accepts the same arguments aspredicate
, returning abool
. If the result ofbreak_check
isTrue
, it will break out of the loop, proceeding to the next step. The result of this step is an aggregate list of individual results of each loop - timeout
Optional[int]
: the time (in seconds) to wait for a user to respond with an option that satisfiespredicate
. Defaults to120
- predicate
Optional[Callable]
: a function that accepts the output of the appropriatebot.wait_for
listener and returns abool
- name
- Returns class instance for fluuid chaining
Add Grouped Looping Step
- Usage:
SetupPanel.add_group_loop(params)
- Parameters:
- names
List[str]
: see valid names - embeds
List[discord.Embed]
: the embed to display during the step - break_checks
List[Callable]
: a list of functions that accept the same arguments aspredicates
for each function, returning abool
. If the result ofbreak_check
for a step isTrue
, it will break out of the loop, proceeding to the next step. The result of this step is an aggregate list of the tuple of individual results of each loop - timeouts
List[int]
: list of the time (in seconds) to wait for a user to respond with an option that satisfiespredicates
- predicates
Optional[List[Callable]]
: a list of functions that accept the output of the appropriatebot.wait_for
listener and returns abool
- names
- Returns class instance for fluuid chaining
Note: The length of each of the list parameters must be the same
Start Setup
- Usage:
await SetupPanel.start()
- Returns the aggregate list of the results of all setup steps in order. If
setup is canceled or times out, returns
None
Examples
import discord
from discord.ext import commands
from discord.ext.commands import AutoShardedBot, Context
from setuppanel import SetupPanel
class ExampleCog(commands.Cog):
def __init__(self, bot: AutoShardedBot) -> None:
self.bot = bot
@commands.command()
async def setuptest(self, ctx: Context):
sp = SetupPanel(
bot=self.bot,
ctx=ctx,
title="Test Setup Panel",
).add_step(
name="content",
embed=discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, message content please",
color=discord.Color.blue(),
),
timeout=300,
)
for name in ["channel", "role", "member"]:
sp.add_step(
name=name,
embed=discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, mention a {name}",
color=discord.Color.blue(),
),
timeout=300,
)
sp.add_until_finish(
name="content",
embed=discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, message content please",
color=discord.Color.blue(),
),
timeout=300,
break_check=lambda m: m.content == "finish" and m.author == ctx.author and m.channel == ctx.channel,
).add_conditional_step(
name="integer",
embed=discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, please specify an integer value",
color=discord.Color.blue(),
),
timeout=300,
condition=lambda lv: bool(lv)
).add_group_loop(
names=["content", "integer"],
embeds=[
discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, say something",
color=discord.Color.blue().
),
discord.Embed(
title="Test Setup",
description=f"{ctx.author.mention}, say a number",
color=discord.Color.blue().
)
],
timeouts=[300, 300],
break_checks=[
lambda m: m.content == "stop looping",
None,
],
)
res = await sp.start()
await ctx.channel.send(content=res)
def setup(bot: AutoShardedBot) -> None:
bot.add_cog(Testing(bot))
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for SetupPanel-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ea01fa553227ffa31c5ab71614c01eb08ab8a892fe07474292dad7738cb4d4c8 |
|
MD5 | 4fa46d4187bc508bc75b2a00ed127863 |
|
BLAKE2b-256 | fea3193445ccfd5fd8564e94a13d785e2a499b07260c0c0885a4200240a64b6c |