Utils¶

Some utility functions for Discord and Python.

ezcord.utils.create_json_file(dictionary, filename='data.json', *, indent=2, description=None, spoiler=False, **kwargs)[source]¶

Create a discord.File object from a dictionary.

Parameters:

dictionary (dict) – The dictionary to convert to a JSON file.
filename (str) – The filename to use for the JSON file.
indent (int) – The indent to use for the JSON file.
description (str | None) – The description to use for the discord file.
spoiler (bool) – Whether the Discord file should be a spoiler.
**kwargs – Additional keyword arguments for json.dumps().

Return type:

discord.File

ezcord.utils.create_text_file(text, filename='data.txt', **kwargs)[source]¶

Create a discord.File object from a string.

Parameters:

text (str) – The string to convert to a text file.
filename (str) – The filename to use for the text file.
**kwargs – Keyword arguments for discord.File.

Return type:

discord.File

ezcord.utils.create_html_file(html, filename='data.html', **kwargs)[source]¶

Create a discord.File object from an HTML string.

Parameters:

html (str) – The HTML string to convert to an HTML file.
filename (str) – The filename to use for the HTML file.
**kwargs – Keyword arguments for discord.File.

Return type:

discord.File

ezcord.utils.create_yaml_file(data, filename='data.yaml', *, indent=2, description=None, spoiler=False, **kwargs)[source]¶

Create a discord.File object from a YAML string.

Parameters:

data (dict | list) – The data to convert to a YAML file.
filename (str) – The filename to use for the YAML file.
indent (int) – The indent to use for the YAML file.
description (str | None) – The description to use for the discord file.
spoiler (bool) – Whether the Discord file should be a spoiler.
**kwargs – Keyword arguments for yaml.dump().

Return type:

discord.File

ezcord.utils.avatar(user_id)[source]¶

Returns a permanent URL of a user’s avatar.

Parameters:: user_id (int) – The ID of the user.
Return type:: str

ezcord.utils.random_avatar()[source]¶

Returns the URL of a random default avatar.

Return type:: str

ezcord.utils.codeblock(content, *, lang='yaml', unit='', interaction=None)[source]¶

Returns a codeblock with the given content.

Parameters:

content (int | str) – The content of the codeblock. If the content is an integer, it will be formatted with commas (or dots if the language is German).
lang (str) – The language of the codeblock. Defaults to yaml.
unit (str) – The text to display after the given content. This is only used if the content is an integer.
interaction (Interaction | None) – The interaction to get the language from. Defaults to None. If not provided, the language will be set to the default language. The language will determine how large numbers are formatted.

Return type:

str

ezcord.utils.ez_autocomplete(values)[source]¶

A similar function as basic_autocomplete(), but instead of returning options starting with the user’s value, it returns options containing the user’s value.

Parameters:: values (Iterable[str]) – Accepts an iterable of str, a callable (sync or async) that takes a single argument of AutocompleteContext, or a coroutine. Must resolve to an iterable of str.

ezcord.utils.count_lines(directory=None, *, count_empty_lines=True, include_hidden=False, ignored_dirs=None, ignored_files=None)[source]¶

Counts the total amount of lines in all Python files in the given directory.

Parameters:

directory (str | None) – The directory to count the lines in. Defaults to the current working directory.
count_empty_lines (bool) – Whether to count empty lines. Defaults to True.
include_hidden (bool) – Whether to include directories starting with a dot. Defaults to False.
ignored_dirs (list[str] | None) – A list of directories to ignore. By default, venv folders and folders starting with a dot are ignored.
ignored_files (list[str] | None) – A list of file patterns to ignore.

Return type:

int

async ezcord.utils.load_message(obj, message_url, error=False)[source]¶

Get a message from a message URL.

Parameters:

obj (Guild | Bot) – The object to use to fetch the message.
message_url (str) – The URL of the message.
error (bool) – Whether to raise an error if the message couldn’t be found. If this is False, the function will return None if the message couldn’t be found. Defaults to False.

Raises:

InvalidFormat – The message URL is invalid.
MissingPermission – The bot does not have permissions to access the channel.
ChannelNotFound – The channel was not found.
MessageNotFound – The message couldn’t be found in the given channel, perhaps it was deleted.
GuildMismatch – The message does not belong to the given guild.

Return type:

Message | None

ezcord.utils.format_number(number, *, decimal_places=1, trailing_zero=False)[source]¶

Format a big number to short and readable format.

Parameters:

number (int) – The number to format.
decimal_places (int) – The amount of decimal places to display. Defaults to 1.
trailing_zero (bool) – Whether to show trailing zeros. Defaults to False.

Returns:

The formatted number.

Return type:

str

Example

>>> format_number(1_000_000)
'1M'
>>> format_number(1_550, decimal_places=2)
'1.55K'
>>> format_number(1_000, trailing_zero=True)
'1.0K'

ezcord.utils.convert_color(color, strict_hex=True, hex_hash=False)[source]¶

Convert a color string to a discord.Color.

Parameters:

color (str) – The color to convert. This can be a hex code, a color name, or an RGB value.
strict_hex (bool) – Whether hex codes must have a length of 6. Defaults to True.
hex_hash (bool) – Whether a hex code must start with a hash. Defaults to False.

Returns:

The converted color.

Return type:

discord.Color

Raises:

commands.BadColourArgument – The color could not be converted.

ezcord.utils.warn_deprecated(name, instead=None, since=None, removed=None, reference=None, stacklevel=3)[source]¶

Warn about a deprecated function, with the ability to specify details about the deprecation. Emits a DeprecationWarning.

Parameters:

name (str) – The name of the deprecated function.
instead (str | None) – A recommended alternative to the function.
since (str | None) – The version in which the function was deprecated.
removed (str | None) – The version in which the function is planned to be removed.
reference (str | None) – A reference that explains the deprecation, typically a URL to a page such as a changelog entry or a GitHub issue/PR.
stacklevel (int) – The stacklevel kwarg passed to warnings.warn(). Defaults to 3.

Return type:

None