Metadata-Version: 2.1
Name: SetupPanel
Version: 1.0.3
Summary: Intuitive and flexible configuration of interactive embed-based setup panels for discord.py
Home-page: https://gitlab.com/marwynnsomridhivej/setuppanel
Author: Marwynn Somridhivej
License: MIT
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
Provides-Extra: dpy
Requires-Dist: discord.py ; extra == 'dpy'
Provides-Extra: dpyv
Requires-Dist: discord.py[voice] ; extra == 'dpyv'

# 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](https://docs.python.org/3/tutorial/venv.html).

## API

### `setuppanel.SetupPanel`

#### Attributes
- **info** `Union[List[Tuple[str, bool, bool, bool]], None]`: information about
  the steps in a `SetupPanel` 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 the `SetupPanel` 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, default `False`
- **duplicate_role_embed** `Optional[discord.Embed]`: the embed to send if a
  duplicate role is received and `duplicate_roles` is `False`. Defaults to `None`
- **duplicate_emojis** `Optional[bool]`: whether or not this setup panel allows
  duplicate emojis to be specified during a looping step, default `False`
- **duplicate_emoji_embed** `Optional[discord.Embed]`: the embed to send if a
  duplicate emoji is received and `duplicate_emojis` is `False`. Defaults to `None`
- **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](#setup-operation-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 satisfies `predicate`. Defaults to `120`
  - **predicate** `Optional[Callable]`: a function that accepts the output of the
    appropriate `bot.wait_for` listener and returns a `bool`
- Returns class instance for fluuid chaining


### Add Conditional Step
- Usage: `SetupPanel.add_conditional_step(params)`
- Parameters:
  - **name** `str`: see [valid names](#setup-operation-names)
  - **embed** `discord.Embed`: the embed to display during the step
  - **condition** `Callable`: a function that accepts the output of the last step,
    returning a `bool`. Step will be executed if the result of `condition` is
    `True`, otherwise the result of this step will be `None`
  - **timeout** `Optional[int]`: the time (in seconds) to wait for a user to respond
    with an option that satisfies `predicate`. Defaults to `120`
  - **predicate** `Optional[Callable]`: a function that accepts the output of the
    appropriate `bot.wait_for` listener and returns a `bool`
- Returns class instance for fluuid chaining

### Add Looping Step
- Usage: `SetupPanel.add_until_finish(params)`
- Parameters:
  - **name** `str`: see [valid names](#setup-operation-names)
  - **embed** `discord.Embed`: the embed to display during the step
  - **break_check** `Callable`: a function that accepts the same arguments as `predicate`,
    returning a `bool`. If the result of `break_check` is `True`, 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 satisfies `predicate`. Defaults to `120`
  - **predicate** `Optional[Callable]`: a function that accepts the output of the
    appropriate `bot.wait_for` listener and returns a `bool`
- Returns class instance for fluuid chaining

### Add Grouped Looping Step
- Usage: `SetupPanel.add_group_loop(params)`
- Parameters:
  - **names** `List[str]`: see [valid names](#setup-operation-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 as `predicates` for each function, returning a `bool`. If the
    result of `break_check` for a step is `True`, 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 satisfies `predicates`
  - **predicates** `Optional[List[Callable]]`: a list of functions that accept the
    output of the appropriate `bot.wait_for` listener and returns a `bool`
- 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
```python
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))
```

