music_db module

MusicDatabaseConnection:

A class to provide an interface for managing the playlists stored in the database.

class music_db.MusicDatabaseConnection(logger_name: str)

Bases: cogs.ext.db.DatabaseConnection

A class to provide an interface to manage the playlists used by the playlist group of commands.

Parameters

logger_name (str) – The name of the logger to be used by this connection.

async insert_song(song: cogs.ext.song.Song)

Inserts a song in the database.

Parameters

song (Song) – The song to insert.

Raises

DbInsertError – Raised when an error inserting a song occurs.

async get_song_id(song_url: str) → Optional[int]

Get the database ID of a song.

Parameters

song_url (str) – The URL of the song to search for.

Returns

The ID of the song if it exists, None otherwise.

Return type

Union[int, None]

async get_song_url(song_id: int) → Optional[str]

Get the URL of a song.

Parameters

song_id (int) – The song ID to get the URL from.

Returns

The URL of the song if it exists, None otherwise.

Return type

Union[str, None]

async get_titles(song_ids: List[int]) → List[str]

Get the titles of a list of songs.

Parameters

song_ids (List[int]) – A list of song IDs to get. It SHOULD NOT be empty, and the IDs SHOULD be in songs.

Returns

A list of the corresponding song titles. Since the IDs SHOULD be in the database, no value should be empty. However, no check is done at this point.

Return type

List[str]

async get_urls(song_ids: List[int]) → List[str]

Get the URLs of a list of songs.

Parameters

song_ids (List[int]) – A list of song IDs to get. It SHOULD NOT be empty, and the IDs SHOULD be in songs.

Returns

A list of the corresponding song URLs. Since the IDs SHOULD be in the database, no value should be empty. However, no check is done at this point.

Return type

List[str]

async get_titles_in_playlist(playlist_title: str, owner_id: str) → Optional[List[str]]

Get the title of all songs in a specific playlist.

Parameters

• playlist_title (str) – The title of the playlist to get the songs from.

• owner_id (str) – The discord ID of the owner of the playlist.

Returns

A list of the titles of all the songs in the playlist, or None if the playlist doesn’t exist, or if it doesn’t have any songs.

Return type

Union[List[str], None]

async get_song_from(index: int, playlist_title: str, owner_id: str) → Optional[str]

Get a song from a playlist by its index.

Parameters

• index (int) – The index of the song in the playlist (as displayed with get_titles_in_playlist()).

• playlist_title (str) – The title of the playlist to get the song from.

• owner_id (str) – The discord ID of the owner of the playlist.

Returns

The song’s URL if it exists in the playlist, None otherwise.

Return type

Union[str, None]

async get_songs_in_playlist(playlist_title: str, owner_id: str) → Optional[List[str]]

Get the URLs of all songs in a specific playlist.

Parameters

• playlist_title (str) – The title of the playlist to get the songs from.

• owner_id (str) – The discord ID of the owner of the playlist.

Returns

A list of the URLs of all the songs in the playlist, or None if the playlist doesn’t exist, or if it doesn’t have any songs.

Return type

Union[List[str], None]

async song_exists(song: cogs.ext.song.Song) → bool

Check if a song exists in the database.

Parameters

song (Song) – The song to search for.

Returns

True if the song exists, False otherwise.

Return type

bool

async song_matches_playlist(song: cogs.ext.song.Song, playlist_title: str, owner_id: str) → bool

Check if a song is matched to a playlist in songs_in_lists.

Parameters

• song (Song) – The song to check.

• playlist_title – The title of the playlist to check.

• owner_id (str) – The owner of the playlist to check.

Returns

True if the song and the playlist are matched, False otherwise.

Return type

bool

async match_song_to_playlist(song: cogs.ext.song.Song, playlist_title: str, owner_id: str)

Match a song to a playlist, ie. create a row in songs_in_lists.

Parameters

• song (Song) – The song to match. It must already be in the database.

• playlist_title – The title of the playlist to match. It must already be in the database.

• owner_id (str) – The owner of the playlist to match. It must already be in the database.

async remove_song_from(title: str, owner_id: str, index: int)

Removes a song from a playlist.

Parameters

• title (str) – The title of the playlist.

• owner_id (str) – The owner of the playlist.

• index (int) – The index of the song in the playlist.

Raises

• NotFoundError – Raised when the song is not in the database.

• DbInsertError – Raised when an error removing the song occurs.

async create_playlist(title: str, owner_id: str)

Create a new playlist if one with that title and owner doesn’t already exist.

Parameters

• title (str) – The name of the playlist.

• owner_id (str) – The discord ID of the user using the command, who owns this playlist.

Raises

DbInsertError – Raised when an error occurs while creating the list or when the playlist already exists.

async delete_playlist(title: str, owner_id: str)

Delete a playlist if it exists.

Parameters

• title (str) – The name of the playlist.

• owner_id (str) – The discord ID of the user using the command, who owns this playlist.

Raises

DbInsertError – Raised when an error occurs while deleting the list.

async get_playlists(owner_id: str) → Optional[List[str]]

Get all playlists owned by a specific user.

Parameters

owner_id (str) – The discord ID of the user to search for.

Returns

A list of the title of each playlist the user owns if any, None otherwise.

Return type

Union[List[str], None]

async add_song_to_playlist(song: cogs.ext.song.Song, playlist_title: str, user_id: str) → Tuple[bool, bool]

Add a song to a playlist if it’s owned by the calling user. Creates the playlist if it doesn’t exist.

Parameters

• song (Song) – The song to add.

• playlist_title (str) – The title of the playlist to add the song to.

• user_id (str) – The discord ID of the calling user.

Raises

DbInsertError – When a problem creating the playlist/inserting the song/adding it to the playlist occurs.

Returns

A bool to indicate whether the song was added to the playlist, or was already in it, and a bool to indicate whether the playlist had to be created or it existed already.

Return type

Tuple[bool, bool]

async get_playlist_id(playlist_title: str, owner_id: str) → Optional[int]

Get the database ID of a playlist.

Parameters

• playlist_title (str) – The title of the playlist to search for.

• owner_id (str) – The ID of the owner of the playlist.

Returns

The ID of the playlist if it exists, None otherwise.

Return type

Union[int, None]

async playlist_exists(playlist_title: str, owner_id: str) → bool

Check if a playlist exists in the database.

Parameters

• playlist_title (str) – The title of the playlist to search for.

• owner_id (str) – The discord ID of the calling user.

Returns

True if a playlist with that title and owner exists.

Return type

bool