Welcome to blurple.py!¶

Blurple.py is a framework built on top of discord.py, giving you the tools you need to build discord bots with convenience.

Theme provided by discord.py

The API Reference is outlined below.

blurple.ui¶

All the styled components you’ll ever need for building user interfaces in discord.

Style¶

class blurple.ui.Style¶

A contextual class to style components.

There are 9 main styles.

PRIMARY
SECONDARY
SUCCESS
DANGER
WARNING
INFO
LIGHT
DARK
GHOST

You can also create a custom style:

Example Usage

grape_style = (0x9266CC, "\U0001f347", "Grape")

PRIMARY and SECONDARY styles use custom emoji, so are unable to be used out of the box. To work around this, I’ve provided the source .svgs in the repository for the custom emojis used throughout the project. you can add these to a server that your bot is in, then create a custom style.

Alternatively, if you want, you can support me on ko-fi, and I’ll invite your bot to my server with the original custom emojis.

Alert¶

class blurple.ui.Alert(style: blurple.ui.style.Style, title: str, description: str = None, **options)¶

A subclass of discord.Embed for stylish alert messages.

Parameters

style (Style) – The style of the alert.
title (str) – The title of the alert, will be wrapped in emoji and alert name unless specified in options.
description (str) – An optional description of the alert, use your imagination for it’s use.
**options –
Alert options to customize it’s look.

emoji

Defaults to True. Can be set to false to remove the emoji from the alert title. This will automatically be removed if a custom style specifies it as an empty string.

name

Defaults to True. Can be set to false to remove the name of the alert from the title. This will automatically be removed if a custom style specifies it as an empty string.

Toast¶

class blurple.ui.Toast(style: blurple.ui.style.Style, text: str, **options)¶

A subclass of discord.Embed for stylish toasts.

The difference between this class and Alert is these are intended to hold more deemphasized information. Some functionality is implemented with :module:`blurple.io`, such as the “dismiss” button, and automatic dismissal after the specified duration.

Parameters

style (Style) – The style of the toasts.
text (str) – The text of the toasts, will be wrapped in an emoji unless specified in options.
**options –
Toast options to customize it’s look.

emoji

Defaults to True. Can be set to false to remove the emoji from the toast.

async send(client: discord.abc.Messageable, duration: int = 5)¶

Send the toast out.

Parameters

client – The client used, usually a discord.abc.Messageable. Must have implemented send()
duration (int) – The duration the toast lasts before disappearing in seconds

blurple.io¶

Robust functions that enable you to build stable, multi-step commands with ease.

Reply¶

class blurple.io.Reply(ctx: discord.ext.commands.context.Context, *, validate: Union[str, Callable, List, None] = None, on_error: Union[str, discord.embeds.Embed] = <blurple.ui.alert.Alert object>, timeout=180, **kwargs)¶

An abstract class for getting replies, to be extended.

If you are trying to get a reply from the user directly, you may be looking for MessageReply or ReactionAddReply.

Extending this class:

In order to extend this class, there are 5 methods you can specialize.

on_reply_init() Use this method to initialize variables at the start.
on_pre_reply() Use this method to prepare anything before reply attempts.
reply_check() This is required. Evaluate whether an event call is considered a user reply attempt.
on_reply_attempt() Use this method to handle resetting the state after a reply attempt.
on_reply_complete() Use this method to handle final cleanup.

Parameters

ctx – The Context variable
validate –
An optional parameter to validate the reply.
- If left blank, no validation will be performed.
- If you pass a list / set, validation will succeed when the reply content is found inside the list/set.
- If you pass a str, validation will succeed when the reply content matches the string as a regex.
- If you pass a function or coroutine, the function will be called, and the coroutine awaited, validation will succeed when the function returns a Truthy value. The reply object will be passed as a parameter.
on_error – An optional parameter specifying the message to send when the user fails validation, defaults to a simple “Invalid Reply” Alert.
timeout – An optional parameter to change the default timeout length, defaults to 180 seconds.
**kwargs –
Any additional parameters that will be passed to on_reply_init(). This can be useful if you are extending this class and need to take extra parameters when initializing.

async result()¶: Await the result of the reply.

async classmethod result_between(replies: Container[blurple.io.reply.Reply]) → Tuple[blurple.io.reply.Reply, Any]¶

Return the first completed result between multiple reply objects.

Parameters: replies – A collection of Reply objects.
Returns: A tuple containing the Reply object and the result it returned.
How to use this

This can be an especially powerful function if used correctly. Here’s an example of an rsvp list interaction with reactions using this function.

This is completely contrived for example and not a practical use.

rsvp_react = "📝"  # Replace this with whatever you want
rsvp_list = []

# Start the reply wait
message = await ctx.send("React to RSVP!")
await message.add_reaction(rsvp_react)

add = io.ReactionAddBasic(message, validate=[rsvp_react])
remove = io.ReactionRemoveBasic(message, validate=[rsvp_react])

while True:
    obj, result = await io.Reply.result_between({add, remove})
    if obj is add:
        rsvp_list.append(result.user_id)
    elif obj is remove:
        rsvp_list.remove(result.user_id)
    else:  # obj is None (The reply timed out)
        break

# Reply wait complete
await message.clear_reactions()
await message.edit(f"Here's the list of RSVPrs:\n{'\n'.join([f'> <@{user_id}>' for user_id in rsvp_list])}")

async on_reply_init()¶