Embed tools

This module holds functions to work with embeds in different ways.

class dpytools.embeds.Embed(**kwargs)

This is a subclass of discord.Embed which accepts its default values plus image and thumbnail in the constructor and adds an additional method add_fields

Parameters

  • title – The title of the embed.

  • type – The type of embed. Usually “rich”. Official documentation states this is soon to be deprecated.

  • description – The description of the embed.

  • url – The URL of the embed.

  • timestamp – The timestamp of the embed content. This could be a naive or aware datetime.

  • (or color) (colour) – The colour code of the embed.

  • image – The image url. Calls the internal “set_image” method with the kwarg value as the url.

  • thumbnail – The thumbnail url. Calls the internal “set_thumbnail” method with the kwarg value as the url.

  • author – A dict containing (optional) “name”, “url”, and “icon_url” fields. Calls the internal “set_author” method, setting the author name, url, and icon_url if applicable.

  • footer – A dict containing (optional) “text” and “icon_url” fields. Calls the internal “set_footer” method, setting the footer text and icon_url if applicable.

add_fields(inline=True, **kwargs) → discord.embeds.Embed

Works in a similar way to Embed.add_field but you can add as many fields as you need by passing them as kwargs in the constructor.

Parameters

  • inline (bool) – if the fields will be inline or not

  • kwargs – key/value pairs for each field’s name and value respectively

Example:

from dpytools import Embed
embed = Embed()
embed.add_fields(inline=False, first="this is the first field's value", second="Second field value")

Note

If you need to add a sentence in the field’s name just construct a dictionary and pass it with **.

Example:

embed.add_fields(**{'first field': 'first field value'})
property is_valid

Returns a bool for whether the length of the embed is valid

class dpytools.embeds.PaginatedEmbeds(embed: dpytools.embeds.Embed, fields_dict: Dict[str, str], size: int = 25, inline: bool = True)

A class that takes dictionary containing name and value as key-value pair and paginates them according to fields.

Parameters

  • embed (Embed) – Base Embed, which acts as a template for paginated embeds. This embed will have everything initiatized except fields.

  • fields_dict (dict) – The dictionary containing name and values as key-value pair. Must not be empty.

  • size (Optional[int]) – Number of field in each embed. Must be greater then 0. Defaults to 25.

  • inline (Optional[bool]) – Bool variable if fields will be inline or not. Defaults to True.

Example

from dpytools.embeds import PaginatedEmbeds
from dpytools.menus import arrows
@bot.command(name='send-fields')
async def send_fields(ctx):
    lots_of_fields = {f'{i}': f'{i+1}' for i in range(1000)}
    pages = PaginatedEmbeds(Embed(title='Embed blueprint', color=0x00FFFF), lots_of_fields)
    await arrows(ctx, pages)

Warning

If parameter embed already has fields they will be cleared. Its suggested that the base embed has no fields before using this class. This will be issued in a coming update.

property pages

Returns the rendered list of pages

dpytools.embeds.dict_to_fields(embed: discord.embeds.Embed, fields: Dict[str, str], inline: bool = False) → None

Iterates through dict keys and appends them to the embed fields

Parameters

  • embed – Instance of discord.Embed

  • fields (class`Dict[str, str]`) – Each key, value pair will be set as an independent field. They key corresponds to field.name and value to field.value.

  • inline (bool) – Specfiy whether if the fields should be inline or not. (Defaults to True)

dpytools.embeds.paginate_to_embeds(description: str, title: Optional[str] = None, max_size: int = 2000, prefix: Optional[str] = '', suffix: Optional[str] = '', color: Optional[Union[discord.colour.Colour, int]] = None) → List[discord.embeds.Embed]

Facilitates sequential embed menus. Returned embeds share title, have description split at :max_length: and are added index/pages at footer to keep track of pages.

Parameters

  • description (str) – String to be split at :max_length: per embed.

  • title (str) – Shared by all embeds

  • max_size (int) – Maximum amount of characters per embed. Discord’s limit is 2000.

  • prefix (str) – Defaults to “” it will be appended at the start of the description of each embed. Useful for codeblocks (use triple back quotes).

  • suffix (str) – Same as :prefix: but at the end of the text.

  • color (Union[discord.Color, int, None]) – color to use for the embed. Accepts int (decimal or hex) or discord.Color/discord.Colour.

Returns

Return type

The rendered list of embeds List[Embed]