API Reference¶

forms.form module¶

class discord.ext.forms.form.Form(ctx: discord.ext.commands.context.Context, title, cleanup=False)[source]¶

Bases: object

The basic form object.

Methods

`add_cancelkeyword`(word)	Adds a word that will cancel the form.
`add_question`(question[, key, qtype])	Adds a question to the form.
`edit_and_delete`([choice])	Toggles the edit and delete feature.
`enable_cancelkeywords`(enabled)	Enables or disables the cancellation of the form.
`set_color`(color)	Sets the color of the form embeds.
`set_incorrect_message`(message)	Sets the message to send if input validation fails and there are no more tries left..
`set_retry_message`(message)	Sets the message to send if input validation fails.
`set_timeout`(timeout)	Sets the timeout for the form.
`set_tries`(tries)	Set the amount of tries that are allowed during input validation.
`start`([channel])	Starts the form in the current channel.

add_cancelkeyword(word: str)[source]¶

Adds a word that will cancel the form.

Parameters: word (str) – The word to listen for.

add_question(question, key: Optional[str] = None, qtype: List[Union[discord.ext.forms.form.Validator, Callable]] = []) → List[dict][source]¶

Adds a question to the form. The valid qtypes are: invite,`channel`,`user`,`member`,`role`, and category

Parameters

question (str) – The question as a string that should be added.
key (str) – What the attribute containing the answer should be called.
qtype (List[Validator, function], optional) – The input validation to be used, by default None

Returns

A list of all of the questions, stored as dictionaries.

Return type

List[dict]

Raises

InvalidFormType – Is raised when the input validation type is invalid.

edit_and_delete(choice: Optional[bool] = None) → bool[source]¶

Toggles the edit and delete feature.

Parameters: choice (bool, optional) – Whether you want the bot to edit the prompt and delete the input or not. If none, it toggles. The default for edit and delete is off. Default input is None
Returns: The state of edit and delete (after this is completed)
Return type: bool

enable_cancelkeywords(enabled: bool)[source]¶

Enables or disables the cancellation of the form.

Parameters: enabled (bool) – Whether the form is enabled or disabled.

async set_color(color: str) → None[source]¶: Sets the color of the form embeds.

set_incorrect_message(message: str)[source]¶

Sets the message to send if input validation fails and there are no more tries left..

Parameters: message (str) – The message to be set.

set_retry_message(message: str)[source]¶

Sets the message to send if input validation fails.

Parameters: message (str) – The message to be set.

set_timeout(timeout: int) → None[source]¶

Sets the timeout for the form.

Parameters: (int) (timeout) –

set_tries(tries: int) → None[source]¶

Set the amount of tries that are allowed during input validation. Defaults to 3.

Parameters: tries (int) – The number of tries to set.

async start(channel=None) → dict[source]¶

Starts the form in the current channel.

Parameters

channel (discord.TextChannel, optional) – The channel to open the form in. If none, it is gotten from the context object set during initialization.
cleanup (bool) – Whether to cleanup and delete the form after finishing or not.

Returns

An object containing all of your keys as attributes.

Return type

FormResponse

class discord.ext.forms.form.FormResponse(data: dict)[source]¶: Bases: object

exception discord.ext.forms.form.InvalidColor[source]¶: Bases: Exception

exception discord.ext.forms.form.InvalidFormType[source]¶

Bases: Exception

The exception raised when a form type is invalid.

exception discord.ext.forms.form.MissingRequiredArgument[source]¶: Bases: Exception

class discord.ext.forms.form.NaiveForm(title, channel: Union[discord.abc.PrivateChannel, discord.abc.GuildChannel], bot: discord.ext.commands.bot.Bot, author: Union[discord.member.Member, discord.user.User], cleanup=False)[source]¶

Bases: object

The basic form object with naive validation. Should be used in scenarios where there is no context, such as reactions.

Methods

`add_cancelkeyword`(word)	Adds a word that will cancel the form.
`add_question`(question[, key, qtype])	Adds a question to the form.
`edit_and_delete`([choice])	Toggles the edit and delete feature.
`enable_cancelkeywords`(enabled)	Enables or disables the cancellation of the form.
`set_color`(color)	Sets the color of the form embeds.
`set_incorrect_message`(message)	Sets the message to send if input validation fails and there are no more tries left..
`set_retry_message`(message)	Sets the message to send if input validation fails.
`set_timeout`(timeout)	Sets the timeout for the form.
`set_tries`(tries)	Set the amount of tries that are allowed during input validation.
`start`([channel])	Starts the form in the current channel.

add_cancelkeyword(word: str)[source]¶

Adds a word that will cancel the form.

Parameters: word (str) – The word to listen for.

add_question(question, key: Optional[str] = None, qtype=None) → List[dict][source]¶

Adds a question to the form. The valid qtypes are: invite,`channel`,`member`,`role`, and emoji

Parameters

question (str) – The question as a string that should be added.
key (str) – What the attribute containing the answer should be called.
qtype (str, optional) – The input validation to be used, by default None

Returns

A list of all of the questions, stored as dictionaries.

Return type

List[dict]

Raises

InvalidFormType – Is raised when the input validation type is invalid.

edit_and_delete(choice: Optional[bool] = None) → bool[source]¶

Toggles the edit and delete feature.

Parameters: choice (bool, optional) – Whether you want the bot to edit the prompt and delete the input or not. If none, it toggles. The default for edit and delete is off. Default input is None
Returns: The state of edit and delete (after this is completed)
Return type: bool

enable_cancelkeywords(enabled: bool)[source]¶

Enables or disables the cancellation of the form.

Parameters: enabled (bool) – Whether the form is enabled or disabled.

async set_color(color: str) → None[source]¶: Sets the color of the form embeds.

set_incorrect_message(message: str)[source]¶

Sets the message to send if input validation fails and there are no more tries left..

Parameters: message (str) – The message to be set.

set_retry_message(message: str)[source]¶

Sets the message to send if input validation fails.

Parameters: message (str) – The message to be set.

set_timeout(timeout: int) → None[source]¶

Sets the timeout for the form.

Parameters: (int) (timeout) –

set_tries(tries: int) → None[source]¶

Set the amount of tries that are allowed during input validation. Defaults to 3.

Parameters: tries (int) – The number of tries to set.

async start(channel=None) → dict[source]¶

Starts the form in the current channel.

Parameters

channel (discord.TextChannel, optional) – The channel to open the form in. If none, it is gotten from the context object set during initialization.
cleanup (bool) – Whether to cleanup and delete the form after finishing or not.

Returns

An object containing all of your keys as attributes.

Return type

FormResponse

discord.ext.forms.form.Validator(qtype: str)[source]¶

forms.reactions module¶

exception discord.ext.forms.reactions.InvalidColor[source]¶: Bases: Exception

class discord.ext.forms.reactions.NeoPaginator(limit_per_page: int, entries: List)[source]¶

Bases: object

Attributes

pages

property pages¶

class discord.ext.forms.reactions.ReactConfirm(message: discord.message.Message, bot: Union[discord.client.Client, discord.ext.commands.bot.Bot], user: Union[discord.member.Member, discord.user.User])[source]¶

Bases: discord.ext.forms.reactions.ReactionForm

Methods

`add_reaction`(reaction, result)	Adds a question to the form.
`set_timeout`(timeout)	Set the timeout for the form.
`start`()	Starts the reaction form on the given message.

class discord.ext.forms.reactions.ReactionForm(message: discord.message.Message, bot: Union[discord.client.Client, discord.ext.commands.bot.Bot], user: Optional[Union[discord.member.Member, discord.user.User]] = None)[source]¶

Bases: object

The Reaction input object.

…

Parameters

message (discord.Message) – The message of the reaction form object.
bot (typing.Union[discord.Client, discord.ext.commands.Bot]) – The bot being used for the form.
user (typing.Union[discord.Member, discord.User]) – The member or user who should be able to use the form. If none, the form will be open to anyone.

Methods

`add_reaction`(reaction, result)	Adds a question to the form.
`set_timeout`(timeout)	Set the timeout for the form.
`start`()	Starts the reaction form on the given message.

add_reaction(reaction: str, result) → dict[source]¶

Adds a question to the form.

Returns the full list of questions the form has, including the newly added one. The questions are held in dictionaries containing the question and optionally type keys. The question key contains the question as a string, and the type key contains the input validation (if any is specified)

Parameters: reaction (str) – The emoji to add.

set_timeout(timeout: int) → None[source]¶

Set the timeout for the form. Defaults to 120 seconds.

Parameters: timeout (int) – The timeout in seconds.

async start() → Any[source]¶

Starts the reaction form on the given message.

Returns: Whatever the given reaction was set to return.
Return type: Any

class discord.ext.forms.reactions.ReactionMenu(ctx: discord.ext.commands.context.Context, embeds: List[discord.embeds.Embed])[source]¶

Bases: object

Methods

`addemoji`(emoji, page)	Adds an emoji/page mapping to your menu.
`remove_reactions`([bool])	Sets whether the bot should remove reactions or not.
`set_timeout`(timeout)	Sets the timeout for the menu.
`start`([channel])	Starts the menu in the given channel.

addemoji(emoji: str, page: int) → bool[source]¶

Adds an emoji/page mapping to your menu.

Parameters

emoji (str) – The emoji to be used as a string. Custom emoji are supported.
page (int) – The page to be mapped. Uses normal indexing (e.g. 1 is the first page)

Returns

The result of the emoji being added. False means an error occurred (most likely you tried to add an emoji that was already set) and True means that everything was successful.

Return type

bool

remove_reactions(bool: bool = True)[source]¶

Sets whether the bot should remove reactions or not. Useful if the bot doesn’t have Manage Messages

Parameters: choice (bool, optional) – Whether to remove reactions or not., by default True

set_timeout(timeout: int)[source]¶

Sets the timeout for the menu.

Parameters: timeout (int) – The timeout to be set in seconds.

async start(channel=None)[source]¶

Starts the menu in the given channel.

Parameters: channel (discord.TextChannel, optional) – The channel to send the menu to. If none is specified, it uses the context’s channel object.
Returns
Return type: None
Raises: TypeError – If channel isn’t specified and ctx wasn’t set on initialization, the form cannot continue.