Blacklist¶

This module manages the blacklists used by randy.

Blacklist Module¶

The blacklist module provides an interface to the blacklists of artist, albums, songs and videos that shall not be played for a certain (configured) time.

Music Selection Blacklist¶

There are four FIFO organized blacklists: For videos, songs, albums and artists. Each blacklist holds the IDs of the last played videos, songs, albums and artists.

If a user adds music into the Song-Queue or Video-Queue, this song or video must be added manually by calling the AddSong() or AddVideo() method. This must also be done if the song or video got selected by Randy.

Once music got added to the blacklist, it remains even if the song or video got removed from the queue.

The length of those blacklist can be configured in the MusicDB Configuration:

[Randy]
songbllen=50
albumbllen=20
artistbllen=10
videobllen=10

For small music collections, the lengths should not exceed the possibility to provide individual data. For medium collections and above, the default values as shown in the example are good. When set to 0, the blacklist for the songs, albums or artists will be disabled.

The blacklists get maintained by the SongQueue and VideoQueue classes. Each instance of this class accesses the same global blacklists.

The blacklist is implemented as a dictionary with the keys "videos", "songs", "albums" and "artists". Their values are lists of dictionaries. The key of the dictionary are:

id:
holding the IDs of the songs, albums and artists.

timestamp:
storing the UNIX time stamp when the ID got on the blacklist.

Both entries can be None when not set.

Blacklist Interface Class¶

class musicdb.mdbapi.blacklist.BlacklistInterface(config, database)[source]¶

This class provides methods to manage the blacklists used by Randy.

Parameters

config – MusicDBConfig object holding the MusicDB Configuration
database – A MusicDatabase instance

Raises

TypeError – When the arguments are not of the correct type.

AddSong(song)[source]¶

This method pushes a song onto the blacklists. If the song is None nothing happens.

This method should be the only place where the blacklist gets changed. After adding a song, the lists get stored in the MusicDB State Directory to be persistent

If the length of the blacklist exceeds its limit, the oldest entry gets dropped.

Parameters: song (dict/int) – A song from the MusicDatabase or the song ID
Returns: Nothing
Raises: TypeError – When song is not of type dict or int

AddVideo(video)[source]¶

This method pushes a video onto the video blacklist. If the video is None nothing happens.

Note

The video associated album and artist get not pushed on the album or artist blacklist.

This method should be the only place where the blacklist gets changed. After adding a video, the lists get stored in the MusicDB State Directory to be persistent

If the length of the blacklist exceeds its limit, the oldest entry gets dropped.

Parameters: video (dict/int) – A video from the MusicDatabase or the video ID
Returns: Nothing
Raises: TypeError – When video is not of type dict or int

CheckAllListsForSong(song)[source]¶

This method checks if a song, its album or artist is on one of the blacklists. If it is so, the method returns True. If none are on the blacklists, False gets returned.

If the song is None nothing happens.

Parameters: song (dict/int) – A song from the MusicDatabase or the song ID
Returns: True if song, album or artist is on blacklist. False otherwise.
Raises: TypeError – When song is not of type dict or int

CheckAllListsForVideo(video)[source]¶

This method checks if a video on the blacklists. If it is so, the method returns True. If none are on the blacklists, False gets returned.

If the video is None nothing happens.

Parameters: video (dict/int) – A video from the MusicDatabase or the video ID
Returns: True if the video is on blacklist. False otherwise.
Raises: TypeError – When video is not of type dict or int

CheckSongList(song)[source]¶

This method checks if a song is on the song blacklists. If it is so, the method returns True.

If the song is None nothing happens.

Parameters: song (dict/int) – A song from the MusicDatabase or the song ID
Returns: True if song is on blacklist. False otherwise.
Raises: TypeError – When song is not of type dict or int

GetIDsFromBlacklist(blacklistname)[source]¶

This method returns a list of IDs (as Integer) from the blacklist. It checks each entry in the list if it is None. If it is None, it gets ignored.

Note

This method does not check if the IDs time stamp is in a valid range. Call ValidateBlacklist() before to make sure all entries in the blacklist are valid.

Parameters: blacklistname (str) – A valid name for the blacklist. Valid names are: "songs", "albums", "artists"
Returns: A list of valid IDs as integers.
Raises: ValueError – When blacklistname is not "videos", "songs", "albums" or "artists"

GetValidIDsFromBlacklists()[source]¶

Returns all Video, Song, Album and Artist IDs from the blacklist. The IDs are separated into three lists. This method checks the time stamp and removes all IDs that are older than configured.

This method combines the following methods for all three blacklists (songs, albums, artists):

ValidateBlacklist()

GetIDsFromBlacklist()

Returns: A tupel (VideoIDs, SongIDs, AlbumIDs, ArtistIDs) of lists of IDs that are temporal still valid.

ValidateBlacklist(blacklistname)[source]¶

This method validates a specific blacklist. It checks each entry in the list if its time stamp is still in the configured time range. If not, the entry gets set to None.

Parameters: blacklistname (str) – A valid name for the blacklist. Valid names are: "songs", "albums", "artists"
Returns: Nothing
Raises: ValueError – When blacklistname is not "videos", "songs", "albums" or "artists"