Submodules¶

Package Contents¶

Classes¶

`InviteTracker`	A usefull class to track invites of member whenever a user is invited to a guild.
`Song`	The requested song data
`MusicPlayer`	The class which acts a music controller/player
`Music`	The manager class to initiate and music and manage its player
`Embed`	Embed which has whoose colors are randomly generated
`ErrorEmbed`	The Embed used to depict an `Exception`
`SuccessEmbed`	The Embed used to depict any kind of success
`StarboardEmbed`	The Embed used to depict any kind of warning or starboard kind of `Embed`
`RoboPages`	Represents a UI view.
`FieldPageSource`	A page source that requires (field_name, field_value) tuple items.
`TextPageSource`	A data source for a sequence of items.
`SimplePageSource`	A data source for a sequence of items.
`SimplePages`	A simple pagination session reminiscent of the old Pages interface.
`EmbedPageSource`	A data source for a sequence of items.
`EmbedPaginator`	A simple paginator for the embeds. In entries you provides a list of embeds

Functions¶

`ytbettersearch`(query)	Formats the search string for the YouTube music search
`get_video_data`(url, search, bettersearch, loop)	It returns required video data after searching YouTube
`check_queue`(ctx, opts, music, after, on_play, loop)	It checks the music queue

Attributes¶

`has_voice`
`bug_reports_message`
`__title__`
`__version__`
`__author__`
`__license__`

class DiscordUtils.InviteTracker(bot)[source]¶

A usefull class to track invites of member whenever a user is invited to a guild.

Parameters

bot (Union[Client, AutoShardedClient, Bot, AutoSharededBot]) –

Attributes

bot: The default bot class.
_cache: dict
A dict to cache Guild instances Invite

__slots__ = ['bot', '_cache']¶

add_listeners(self)[source]¶

It adds the following listeners to the Bot instance.

Mapping

Function	Discord Function
`cache_invites()`	`on_ready()`
`update_invite_cache()`	`on_invite_create()`
`remove_invite_cache()`	`on_invite_delete()`
`add_guild_cache()`	`on_guild_join()`
`remove_guild_cache()`	`on_guild_remove()`

Return type

None

await cache_invites(self)[source]¶

It cache the guild invites automatically whenever the on_ready() event is fired

Return type: None

await update_invite_cache(self, invite)[source]¶

It updates the invite cache automatically whenever the on_invite_create() event is fired

Parameters: invite (discord.Invite) –
Return type: None

await remove_invite_cache(self, invite)[source]¶

It removes the invite cache of the deleted invite automatically whenever the on_invite_delete() event is fired

Parameters: invite (discord.Invite) –

await add_guild_cache(self, guild)[source]¶

It adds the guild to cache automatically whenever the on_guild_join() event is fired

Parameters: guild (discord.Guild) –
Return type: None

await remove_guild_cache(self, guild)[source]¶

It removes the guild from cache automatically whenever the on_guild_remove() event is fired

Parameters: guild (discord.Guild) –
Return type: None

await fetch_inviter(self, member)[source]¶

This utility function returns the Invite class which was used when the member joined the guild.

Parameters: member (discord.Member) – The member which joined the guild. (The Member recieved during on_member_join() event)
Returns: If the member was bot i.e. invited via integration then it would return None
Return type: Optional[discord.Invite]

DiscordUtils.has_voice = True¶

DiscordUtils.bug_reports_message¶

exception DiscordUtils.EmptyQueue[source]¶

Bases: Exception

Cannot skip because queue is empty

exception DiscordUtils.NotConnectedToVoice[source]¶

Bases: Exception

Cannot create the player because bot is not connected to voice

exception DiscordUtils.NotPlaying[source]¶

Bases: Exception

Cannot <do something> because nothing is being played

await DiscordUtils.ytbettersearch(query)[source]¶

Formats the search string for the YouTube music search

Return type: str

class DiscordUtils.Song(source, url, title, description, views, duration, thumbnail, channel, channel_url, loop)[source]¶

The requested song data

Parameters

source (str) –
url (str) –
title (str) –
description (str) –
views (int) –
duration (Union[str, int]) –
thumbnail (str) –
channel (str) –
channel_url (str) –
loop (bool) –

__slots__ = ['source', 'url', 'title', 'description', 'views', 'duration', 'thumbnail', 'channel',...¶

await DiscordUtils.get_video_data(url, search, bettersearch, loop)[source]¶

It returns required video data after searching YouTube

Raises

RuntimeError – Is raised when the package is install without the .[voice] parameters

Returns

The song data in a formatted way

Return type

Song

Parameters

search (bool) –
bettersearch (bool) –
loop (Optional[asyncio.AbstractEventLoop]) –

DiscordUtils.check_queue(ctx, opts, music, after, on_play, loop)[source]¶

It checks the music queue

Parameters

ctx (commands.Context) – The commands context
opts (dict) – A set options for ffmpeg
music (Music) – The master class where the all the players data is stored
after (Callable) – The check_queue() which would be called afterwards
on_play (MusicPlayer.on_play) – MusicPlayer.on_play() function
loop (Optional[asyncio.AbstractEventLoop]) – The event loop in which the Bot is running

Raises

RuntimeError – Is raised when the package is install without the .[voice] parameters

Return type

None

class DiscordUtils.MusicPlayer(ctx, music, **kwargs)[source]¶

The class which acts a music controller/player

Raises

RuntimeError – Is raised when the package is install without the .[voice] parameters
NotPlaying – See skip(), stop(), resume(), pause(), toggle_song_loop(), change_volume(), remove_from_queue()
EmptyQueue – See skip(), current_queue()

Parameters

ctx (discord.ext.commands.Context) –
music (Music) –

__slots__ = ['ctx', 'voice', 'loop', 'music', 'after_func', 'on_play_func', 'on_queue_func', 'on_skip_func',...¶

disable(self)[source]¶: It disables the Music Player

on_queue(self, func)[source]¶

The event when the song is queued

Parameters: func (Callable) –
Return type: None

on_play(self, func)[source]¶

The event when the song is played

Parameters: func (Callable) –
Return type: None

on_skip(self, func)[source]¶

The event when the song is skipped

Parameters: func (Callable) –
Return type: None

on_stop(self, func)[source]¶

The event when the player is stopped

Parameters: func (Callable) –
Return type: None

on_pause(self, func)[source]¶

The event when the song is paused

Parameters: func (Callable) –
Return type: None

on_resume(self, func)[source]¶

The event when the song is resumed

Parameters: func (Callable) –
Return type: None

on_loop_toggle(self, func)[source]¶

The event when the looping is enabled

Parameters: func (Callable) –
Return type: None

on_volume_change(self, func)[source]¶

The event when the volume is changed

Parameters: func (Callable) –
Return type: None

on_remove_from_queue(self, func)[source]¶

The event when the song is removed from the queue

Parameters: func (Callable) –
Return type: None

await queue(self, url, search=False, bettersearch=False)[source]¶

The song to queue

Parameters

url (str) – The url of the song provider
search (bool, optional) – Song Name, defaults to False
bettersearch (bool, optional) – Search betterly or not, defaults to False

Returns

The song with the minimum required data

Return type

Song

await play(self)[source]¶

Determines which song to play from the queue

Returns: See above
Return type: Song

await skip(self, force=False)[source]¶

Skips the current song which is being played

Parameters

force (bool, optional) – Force skip or not, defaults to False

Raises

NotPlaying – When there is no song played then this error is raised
EmptyQueue – When the queue is empty

Returns

It returns (old song, new song) or just (song) depending on the situtation

Return type

Union[Tuple[Song, Song], Song]

await stop(self)[source]¶

Stops the player

Raises: NotPlaying – When nothing is played
Return type: None

await pause(self)[source]¶

Pauses the player

Raises: NotPlaying – When nothing is played
Returns: The song on which the pause was initiated
Return type: Song

await resume(self)[source]¶

Resumes the player

Raises: NotPlaying – When nothing was played by the player previously
Returns: The song which will be played
Return type: Song

current_queue(self)[source]¶

Gives the current queue of songs which is there in the player

Raises: EmptyQueue – When the song queue is empty
Returns: _description_
Return type: Union[Iterable, Song]

now_playing(self)[source]¶

Returns the Song which is currently being played

Returns: See above
Return type: Optional[Union[Iterable, Song]]

await toggle_song_loop(self)[source]¶

It toggles on/off the looping

Raises: NotPlaying – When no song is being played
Returns: The currently playing song or the looped queue
Return type: Optional[Union[Iterable, Song]]

await change_volume(self, vol)[source]¶

Change the song volume of the currently played song

Parameters: vol (int) – The amount by the volume needs to increased or decreased
Raises: NotPlaying – When no song is played
Returns: (The song which is being played, volume no by which the song’s volume was increased or decreased)
Return type: Tuple[Song, int]

await remove_from_queue(self, index)[source]¶

The utility function to remove Song from the queue

Parameters: index (int) – The index at which the Song is located
Raises: NotPlaying – When nothing is player by the player
Returns: The song to be removed from the player
Return type: Song

delete(self)[source]¶

Removes the song from the queue

Return type: None

class DiscordUtils.Music[source]¶

The manager class to initiate and music and manage its player

Raises

RuntimeError – Is raised when the package is install without the .[voice] parameters
NotConnectedToVoice – See create_player()

__slots__ = ['queue', 'players']¶

create_player(self, ctx, **kwargs)[source]¶

It create a music player, using which the music will be played in the voice channels

Parameters: ctx (commands.Context) – The commands context
Raises: NotConnectedToVoice – When the client is not connect to any of the voice channel
Returns: The music player using the user will have the control over its requested songs
Return type: MusicPlayer

get_player(self, **kwargs)[source]¶

Its gets the MusicPlayer of the specified guild or voice channel

Returns: See above
Return type: Optional[MusicPlayer]

class DiscordUtils.Embed(**kwargs)[source]¶

Bases: discord.embeds.Embed

Embed which has whoose colors are randomly generated The random color are generated using discord.Color.random()

class DiscordUtils.ErrorEmbed(**kwargs)[source]¶

Bases: discord.embeds.Embed

The Embed used to depict an Exception The red color are generated using discord.Color.red()

class DiscordUtils.SuccessEmbed(**kwargs)[source]¶

Bases: discord.embeds.Embed

The Embed used to depict any kind of success The green color are generated using discord.Color.green()

class DiscordUtils.StarboardEmbed(**kwargs)[source]¶

Bases: discord.embeds.Embed

The Embed used to depict any kind of warning or starboard kind of Embed The green color are generated using discord.Color.green()

class DiscordUtils.RoboPages(source, *, ctx, check_embeds=True, compact=False)[source]¶

Bases: discord.ui.View

Represents a UI view.

This object must be inherited to create a UI within Discord.

New in version 2.0.

Parameters

timeout (Optional[float]) – Timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.
source (discord.ext.menus.PageSource) –
ctx (discord.ext.commands.Context) –
check_embeds (bool) –
compact (bool) –

fill_items(self)[source]¶

Return type: None

await _get_kwargs_from_page(self, page)[source]¶

Parameters: page (int) –
Return type: Dict[str, Any]

await show_page(self, interaction, page_number)[source]¶

Parameters

interaction (discord.Interaction) –
page_number (int) –

Return type

None

_update_labels(self, page_number)[source]¶

Parameters: page_number (int) –
Return type: None

await show_checked_page(self, interaction, page_number)[source]¶

Parameters

interaction (discord.Interaction) –
page_number (int) –

Return type

None

await interaction_check(self, interaction)[source]¶

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters: interaction (Interaction) – The interaction that occurred.
Returns: Whether the view children’s callbacks should be called.
Return type: bool

await on_timeout(self)[source]¶

This function is a coroutine.

A callback that is called when a view’s timeout elapses without being explicitly stopped.

Return type: None

staticmethod await on_error(error, item, interaction)[source]¶

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation logs to the library logger.

Parameters

interaction (Interaction) – The interaction that led to the failure.
error (Exception) – The exception that was raised.
item (Item) – The item that failed the dispatch.

Return type

None

await start(self)[source]¶

Return type: None

await go_to_first_page(self, button, interaction)[source]¶

Go to the first page

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await go_to_previous_page(self, button, interaction)[source]¶

Go to the previous page

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await go_to_current_page(self, button, interaction)[source]¶

As the name suggests, goes to the current page

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await go_to_next_page(self, button, interaction)[source]¶

Go to the next page

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await go_to_last_page(self, button, interaction)[source]¶

Go to the last page

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await numbered_page(self, button, interaction)[source]¶

lets you type a page number to go to

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

await stop_pages(self, button, interaction)[source]¶

stops the pagination session.

Parameters

button (discord.ui.Button) –
interaction (discord.Interaction) –

class DiscordUtils.FieldPageSource(entries, *, per_page=12)[source]¶

Bases: discord.ext.menus.ListPageSource

A page source that requires (field_name, field_value) tuple items.

await format_page(self, menu, entries)[source]¶

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both discord.Message.edit() and discord.abc.Messageable.send(). The two of interest are embed and content.

Parameters

menu (Menu) – The menu that wants to format this page.
page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.TextPageSource(text, *, prefix='```', suffix='```', max_size=2000)[source]¶

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries¶

The sequence of items to paginate.

Type: Sequence[Any]

per_page¶

How many elements are in a page.

Type: int

await format_page(self, menu, content)[source]¶

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

Parameters

menu (Menu) – The menu that wants to format this page.
page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

staticmethod is_paginating()[source]¶

This forces the buttons to appear even in the front page

Return type: bool

class DiscordUtils.SimplePageSource(entries, *, per_page)[source]¶

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries¶

The sequence of items to paginate.

Type: Sequence[Any]

per_page¶

How many elements are in a page.

Type: int

await format_page(self, menu, entries)[source]¶

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

Parameters

menu (Menu) – The menu that wants to format this page.
page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.SimplePages(entries, *, ctx, per_page=12)[source]¶

Bases: RoboPages

A simple pagination session reminiscent of the old Pages interface. Basically an embed with some normal formatting.

Parameters

ctx (discord.ext.commands.Context) –
per_page (int) –

class DiscordUtils.EmbedPageSource(entries, *, per_page)[source]¶

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries¶

The sequence of items to paginate.

Type: Sequence[Any]

per_page¶

How many elements are in a page.

Type: int

staticmethod await format_page(menu, entries)[source]¶

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

Parameters

menu (Menu) – The menu that wants to format this page.
page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.EmbedPaginator(entries, *, ctx)[source]¶

Bases: RoboPages

A simple paginator for the embeds. In entries you provides a list of embeds

Parameters: ctx (discord.ext.commands.Context) –

staticmethod is_paginating()[source]¶

The pagination is in the paginating state or not. This forces the buttons to appear even in the front page

Returns: bool
Return type: bool

DiscordUtils.__title__ = DiscordUtils¶

DiscordUtils.__version__ = 1.3.5¶

DiscordUtils.__author__ = Dhruvacube¶

DiscordUtils.__license__ = MIT¶

Submodules¶

Package Contents¶

Classes¶

Functions¶

Attributes¶

Settings

Font

Use a serif font:

Theme

Automatic

Light

Dark