Utility Functions¶

Chat Formatting¶

redbot.core.utils.chat_formatting.bold(text: str) → str[source]¶

Get the given text in bold.

Parameters:	text (str) – The text to be marked up.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.bordered(text1: typing.List[str], text2: typing.List[str]) → str[source]¶

Get two blocks of text in a borders.

Note

This will only work with a monospaced font.

Parameters:	text1 (`list` of `str`) – The 1st block of text, with each string being a new line. text2 (`list` of `str`) – The 2nd block of text. Should not be longer than `text1`.
Returns:	The bordered text.
Return type:	str

redbot.core.utils.chat_formatting.box(text: str, lang: str = '') → str[source]¶

Get the given text in a code block.

Parameters:	text (str) – The text to be marked up. lang (`str`, optional) – The syntax highlighting language for the codeblock.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.error(text: str) → str[source]¶

Get text prefixed with an error emoji.

Returns:	The new message.
Return type:	str

redbot.core.utils.chat_formatting.escape(text: str, *, mass_mentions: bool = False, formatting: bool = False) → str[source]¶

Get text with all mass mentions or markdown escaped.

Parameters:	text (str) – The text to be escaped. mass_mentions (`bool`, optional) – Set to `True` to escape mass mentions in the text. formatting (`bool`, optional) – Set to `True` to escpae any markdown formatting in the text.
Returns:	The escaped text.
Return type:	str

redbot.core.utils.chat_formatting.info(text: str) → str[source]¶

Get text prefixed with an info emoji.

Returns:	The new message.
Return type:	str

redbot.core.utils.chat_formatting.inline(text: str) → str[source]¶

Get the given text as inline code.

Parameters:	text (str) – The text to be marked up.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.italics(text: str) → str[source]¶

Get the given text in italics.

Parameters:	text (str) – The text to be marked up.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.pagify(text: str, delims: typing.List[str] = ['\n'], *, priority: bool = False, escape_mass_mentions: bool = True, shorten_by: int = 8, page_length: int = 2000) → typing.Iterator[str][source]¶

Generate multiple pages from the given text.

Note

This does not respect code blocks or inline code.

Other Parameters:
Parameters:	text (str) – The content to pagify and send. delims (`list` of `str`, optional) – Characters where page breaks will occur. If no delimiters are found in a page, the page will break after `page_length` characters. By default this only contains the newline.
	priority (`bool`) – Set to `True` to choose the page break delimiter based on the order of `delims`. Otherwise, the page will always break at the last possible delimiter. escape_mass_mentions (`bool`) – If `True`, any mass mentions (here or everyone) will be silenced. shorten_by (`int`) – How much to shorten each page by. Defaults to 8. page_length (`int`) – The maximum length of each page. Defaults to 2000.
Yields:	`str` – Pages of the given text.

redbot.core.utils.chat_formatting.question(text: str) → str[source]¶

Get text prefixed with a question emoji.

Returns:	The new message.
Return type:	str

redbot.core.utils.chat_formatting.strikethrough(text: str) → str[source]¶

Get the given text with a strikethrough.

Parameters:	text (str) – The text to be marked up.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.underline(text: str) → str[source]¶

Get the given text with an underline.

Parameters:	text (str) – The text to be marked up.
Returns:	The marked up text.
Return type:	str

redbot.core.utils.chat_formatting.warning(text: str) → str[source]¶

Get text prefixed with a warning emoji.

Returns:	The new message.
Return type:	str

Mod Helpers¶

redbot.core.utils.mod.get_audit_reason(author: discord.member.Member, reason: str = None)[source]¶

Construct a reason to appear in the audit log.

Parameters:	author (discord.Member) – The author behind the audit log action. reason (str) – The reason behidn the audit log action.
Returns:	The formatted audit log reason.
Return type:	str

coroutine redbot.core.utils.mod.is_admin_or_superior(bot: redbot.core.bot.Red, obj: typing.Union[discord.message.Message, discord.member.Member, discord.role.Role])[source]¶

Same as is_mod_or_superior except for admin permissions.

If a message is passed, its author’s permissions are checked. If a role is passed, it simply checks if it is the admin role.

Parameters:	bot (redbot.core.bot.Red) – The bot object. obj (`discord.Message` or `discord.Member` or `discord.Role`) – The object to check permissions for.
Returns:	`True` if the object has admin permissions.
Return type:	bool
Raises:	`TypeError` – If the wrong type of `obj` was passed.

coroutine redbot.core.utils.mod.is_mod_or_superior(bot: redbot.core.bot.Red, obj: typing.Union[discord.message.Message, discord.member.Member, discord.role.Role])[source]¶

Check if an object has mod or superior permissions.

If a message is passed, its author’s permissions are checked. If a role is passed, it simply checks if it is one of either the admin or mod roles.

Parameters:	bot (redbot.core.bot.Red) – The bot object. obj (`discord.Message` or `discord.Member` or `discord.Role`) – The object to check permissions for.
Returns:	`True` if the object has mod permissions.
Return type:	bool
Raises:	`TypeError` – If the wrong type of `obj` was passed.

coroutine redbot.core.utils.mod.mass_purge(messages: typing.List[discord.message.Message], channel: discord.channel.TextChannel)[source]¶

Bulk delete messages from a channel.

If more than 100 messages are supplied, the bot will delete 100 messages at a time, sleeping between each action.

Note

Messages must not be older than 14 days, and the bot must not be a user account.

Parameters:	messages (`list` of `discord.Message`) – The messages to bulk delete. channel (discord.TextChannel) – The channel to delete messages from.
Raises:	`discord.Forbidden` – You do not have proper permissions to delete the messages or you’re not using a bot account. `discord.HTTPException` – Deleting the messages failed.

coroutine redbot.core.utils.mod.slow_deletion(messages: typing.Iterable[discord.message.Message])[source]¶

Delete a list of messages one at a time.

Any exceptions raised when trying to delete the message will be silenced.

Parameters:	messages (`iterable` of `discord.Message`) – The messages to delete.

redbot.core.utils.mod.strfdelta(delta: datetime.timedelta)[source]¶

Format a timedelta object to a message with time units.

Parameters:	delta (datetime.timedelta) – The duration to parse.
Returns:	A message representing the timedelta with units.
Return type:	str