Types¶

Package-defined types.

Currently, the types defined here are only returned by Genius.search_album(), Genius.search_artist() and Genius.search_song().

All of the attributes listed in the types are guaranteed to be present in the returned object. To access other values that are in the response body, use to_dict().

Base¶

Base classes.

Classes¶

`Stats`	Stats of an item.
`Track`	docstring for Track

class lyricsgenius.types.Stats(json_dict)¶

Stats of an item.

Note

The values passed to this class are inconsistent, and therefore need to be set dynamically. Use the built-in dir() function to see the available attributes. You could also access the stats by the dictionary annotation. For example:

values = song.to_dict()
print(values['stats'])

class lyricsgenius.types.Track(client, json_dict, lyrics)¶

docstring for Track

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
overwrite (bool, optional) – Overwrites preexisting file if True. Otherwise prompts user for input.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Album¶

An album from Genius that has the album’s songs and their lyrics.

Attributes¶

Attribute	Type
_type	`str`
api_path	`str`
artist	`Artist`
cover_art_thumbnail_url	`str`
cover_art_url	`str`
full_title	`str`
id	`int`
name	`str`
name_with_artist	`str`
release_date_components	`datetime`
tracks	`list` of `Track`
url	`str`

Methods¶

`Album.to_dict`	Converts the object to a dictionary.
`Album.to_json`	Converts the object to a json string.
`Album.to_text`	Converts song(s) lyrics to a single string.
`Album.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Album(client, json_dict, tracks)¶

An album from the Genius.com database.

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
overwrite (bool, optional) – Overwrites preexisting file if True. Otherwise prompts user for input.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Artist¶

The Artist object which holds the details of the artist and the Song objects of that artist.

Attributes¶

Attribute	Type
api_path	`str`
header_image_url	`str`
id	`int`
image_url	`str`
is_meme_verified	`bool`
is_verified	`bool`
name	`str`
songs	`list`
url	`str`

Methods¶

`Artist.song`	Gets the artist’s song.
`Artist.add_song`	Adds a song to the Artist.
`Artist.to_dict`	Converts the object to a dictionary.
`Artist.to_json`	Converts the object to a json string.
`Artist.to_text`	Converts song(s) lyrics to a single string.
`Artist.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Artist(client, json_dict)¶

An artist with songs from the Genius.com database.

add_song(new_song, verbose=True, include_features=False)¶

Adds a song to the Artist.

This method adds a new song to the artist object. It checks if the song is already in artist’s songs and whether the song’s artist is the same as the Artist object.

Parameters

new_song (Song) – Song to be added.
verbose (bool, optional) – prints operation result.
include_features (bool, optional) – If True, includes tracks featuring the artist.

Returns

0 for success and 1 for failure.

Return type

int

Examples

genius = Genius(token)
artist = genius.search_artist('Andy Shauf', max_songs=3)

# Way 1
song = genius.search_song('To You', artist.name)
artist.add_song(song)

# Way 2
artist.add_song('To You')

song(song_name)¶

Gets the artist’s song.

If the song is in the artist’s songs, returns the song. Otherwise searches Genius for the song and then returns the song.

Parameters: song_name (str) – name of the song. the result is returned as a string.
Returns: If it can’t find the song, returns None.
Return type: Song |‌ None

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
overwrite (bool, optional) – Overwrites preexisting file if True. Otherwise prompts user for input.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Song¶

This is the Song object which holds the details of the song.

Attributes¶

Attribute	Type
annotation_count	`int`
api_path	`str`
artist	`str`
full_title	`str`
header_image_thumbnail_url	`str`
header_image_url	`str`
id	`int`
lyrics	`str`
lyrics_owner_id	`int`
lyrics_state	`str`
path	`str`
primary_artist	`Artist`
pyongs_count	`int`
song_art_image_thumbnail_url	`str`
song_art_image_url	`str`
stats	`Stats`
title	`str`
title_with_featured	`str`
url	`str`

Methods¶

`Song.to_dict`	Converts the object to a dictionary.
`Song.to_json`	Converts the object to a json string.
`Song.to_text`	Converts song(s) lyrics to a single string.
`Song.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Song(client, json_dict, lyrics='')¶

A song from the Genius.com database.

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
overwrite (bool, optional) – Overwrites preexisting file if True. Otherwise prompts user for input.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.