Package Api Documentation

API Reference for classes in lyricsmaster.providers

Main module.

This module defines the Api interface for the various Lyrics providers. All lyrics providers inherit from the base class LyricsProvider.

class lyricsmaster.providers.LyricsProvider(tor_controller=None)[source]

Bases: object

This is the base class for all Lyrics Providers. If you wish to subclass this class, you must implement all the methods defined in this class to be compatible with the LyricsMaster API. Requests to fetch songs are executed asynchronously for better performance. Tor anonymisation is provided if tor is installed on the system and a TorController is passed at instance creation.

Parameters:tor_controller – TorController Object.
get_albums(raw_artist_page)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string or None. Formatted lyrics.
extract_writers(lyrics_page)[source]

Must be implemented by children classes conforming to the LyricsMaster API.

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string or None. Song writers.
get_page(url)[source]

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.
get_artist_page(artist)[source]

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics_page(url)[source]

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_lyrics(artist, album=None, song=None)[source]

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

class lyricsmaster.providers.LyricWiki(tor_controller=None)[source]

Bases: lyricsmaster.providers.LyricsProvider

Class interfacing with http://lyrics.wikia.com . This class is used to retrieve lyrics from LyricWiki.

get_album_page(artist, album)[source]

Fetches the album page for the supplied artist and album.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
Returns:

string or None. Album’s raw html page. None if the album page was not found.

get_albums(raw_artist_page)[source]

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string or None. Formatted lyrics.
extract_writers(lyrics_page)[source]

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string or None. Song writers.
get_artist_page(artist)

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics(artist, album=None, song=None)

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

get_lyrics_page(url)

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_page(url)

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.
class lyricsmaster.providers.AzLyrics(tor_controller=None)[source]

Bases: lyricsmaster.providers.LyricsProvider

Class interfacing with https://azlyrics.com . This class is used to retrieve lyrics from AzLyrics.

search(artist)[source]

Searches for the artist in the supplier’s database.

Parameters:artist – Artist’s name.
Returns:url or None. Url to the artist’s page if found. None if not Found.
get_albums(raw_artist_page)[source]

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Formatted lyrics.
extract_writers(lyrics_page)[source]

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string or None. Song writers or None.
get_artist_page(artist)

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics(artist, album=None, song=None)

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

get_lyrics_page(url)

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_page(url)

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.
class lyricsmaster.providers.Genius(tor_controller=None)[source]

Bases: lyricsmaster.providers.LyricsProvider

Class interfacing with https://genius.com . This class is used to retrieve lyrics from Genius.

get_albums(raw_artist_page)[source]

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Formatted lyrics.
extract_writers(lyrics_page)[source]

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Song writers or None.
get_artist_page(artist)

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics(artist, album=None, song=None)

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

get_lyrics_page(url)

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_page(url)

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.
class lyricsmaster.providers.Lyrics007(tor_controller=None)[source]

Bases: lyricsmaster.providers.LyricsProvider

Class interfacing with https://www.lyrics007.com . This class is used to retrieve lyrics from Lyrics007.

search(artist)[source]

Searches for the artist in the supplier’s database.

Parameters:artist – string. Artist’s name.
Returns:string or None. Artist’s url page.
get_albums(raw_artist_page)[source]

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Formatted lyrics.
extract_writers(lyrics_page)[source]

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Song writers or None.
get_artist_page(artist)

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics(artist, album=None, song=None)

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

get_lyrics_page(url)

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_page(url)

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.
class lyricsmaster.providers.MusixMatch(tor_controller=None)[source]

Bases: lyricsmaster.providers.LyricsProvider

Class interfacing with https://www.musixmatch.com . This class is used to retrieve lyrics from MusixMatch.

get_albums(raw_artist_page)[source]

Fetches the albums section in the supplied html page.

Parameters:raw_artist_page – Artist’s raw html page.
Returns:list. List of BeautifulSoup objects.
get_album_infos(tag)[source]

Extracts the Album informations from the tag

Parameters:tag – BeautifulSoup object.
Returns:tuple(string, string). Album title and release date.
get_songs(album)[source]

Fetches the links to the songs of the supplied album.

Parameters:album – BeautifulSoup object.
Returns:List of BeautifulSoup Link objects.
create_song(link, artist, album_title)[source]

Creates a Song object.

Parameters:
  • link – BeautifulSoup Link object.
  • artist – string.
  • album_title – string.
Returns:

models.Song object or None.

extract_lyrics(lyrics_page)[source]

Extracts the lyrics from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Formatted lyrics.
extract_writers(lyrics_page)[source]

Extracts the writers from the lyrics page of the supplied song.

Parameters:lyrics_page – BeautifulSoup Object. BeautifulSoup lyrics page.
Returns:string. Song writers or None.
get_artist_page(artist)

Fetches the web page for the supplied artist.

Parameters:artist – string. Artist name.
Returns:string or None. Artist’s raw html page. None if the artist page was not found.
get_lyrics(artist, album=None, song=None)

This is the main method of this class. Connects to the Lyrics Provider and downloads lyrics for all the albums of the supplied artist and songs. Returns a Discography Object or None if the artist was not found on the Lyrics Provider.

Parameters:
  • artist – string. Artist name.
  • album – string. Album title.
  • song – string. Song title.
Returns:

models.Discography object or None.

get_lyrics_page(url)

Fetches the web page containing the lyrics at the supplied url.

Parameters:url – string. Lyrics url.
Returns:string or None. Lyrics’s raw html page. None if the lyrics page was not found.
get_page(url)

Fetches the supplied url and returns a request object.

Parameters:url – string.
Returns:urllib3.response.HTTPResponse Object or None.

API Reference for classes in lyricsmaster.models

Models the domain objects.

Defines classes for Song, Album and Discography.

class lyricsmaster.models.Song(title, album, artist, lyrics=None, writers=None)[source]

Song class.

Parameters:
  • title – string. Song title.
  • album – string. Album title.
  • artist – string. Author name.
  • lyrics – string. Lyrics of the song.
  • writers – string. List of the song’s writers.
save(folder=None)[source]

Saves the lyrics of the song in the supplied folder. If no folder is supplied, ‘folder’ is set to {user}/Documents/lyricsmaster/ The lyrics of a song are saved in the folder /artist/album/song_title.txt

Parameters:folder – string. path to save folder.
class lyricsmaster.models.Album(title, artist, songs, release_date='Unknown')[source]

Album Class. The Album class follows the Iterable protocol and can be iterated over the songs.

Parameters:
  • title – string. Album title.
  • artist – string. Artist name.
  • release_date – string. Release date.
  • songs – list. List of Songs objects.
save(folder=None)[source]

Saves the album in the supplied folder.

Parameters:folder – string. path to save folder.
class lyricsmaster.models.Discography(artist, albums)[source]

Discography Class. The Discography class follows the Iterable protocol and can be iterated over the albums.

Parameters:
  • artist – string. Artist name.
  • albums – list. List of Album objects.
save(folder=None)[source]

Saves Discography in the supplied folder.

Parameters:folder – string. Path to save folder.

API Reference for classes in lyricsmaster.utils

class lyricsmaster.utils.TorController(ip='127.0.0.1', socksport=9050, controlport=None, password='')[source]

Controller class for Tor client.

Allows the Api to make requests over the Tor network. If ‘controlport’ is None, the library will use the default timing to renew the Tor circuit. If ‘controlport’ is passed as an argument, the library will create a new Tor circuit for each new album downloaded. See https://www.torproject.org/docs/tor-manual.html.en for more information on how Tor works.

Parameters:
  • ip – string. The IP adress of the Tor proxy.
  • socksport – integer. The SOCKSPORT port number for Tor.
  • controlport – integer or string. The CONTROLPORT port number for Tor or the unix path to the CONTROLPATH.
  • password – string. The password or control_auth_cookie to authenticate on the Tor CONTROLPORT.
get_tor_session()[source]

Configures and create the session to use a Tor Socks proxy.

Returns:urllib3.SOCKSProxyManager object.
renew_tor_circuit()[source]

Renews the Tor circuit. Sends a NEWNYM message to the Tor network to create a new circuit.

Returns:bool. Whether a new tor ciruit was created.