Access data from

This module uses lastfmclient to access the API, and requires a API key (see below). Note that the history submodule does not require an API key.


API keys are available on request and existing keys can be viewed here.

Credentials should be provided to the LastfmContext by a calliope.config.Configuration instance with keys lastfm.client-id and lastfm.client-secret.

Additionally lastfm.redirect-uri should be set. Any URL should work. The first time LastfmContext.authenticate() is called, it will open a browser window to authorize with, and will return the access token by asking to paste the redirected URI:

$ cpe lastfm --user ssam top-artists

    User authentication requires interaction with your
    web browser. Once you enter your credentials and
    give authorization, you will be redirected to
    a url.  Paste that url you were directed to to
    complete the authorization.

Opened in your browser

Enter the URL you were redirected to:

The authorization code will be saved in the cache so future API access will work without a prompt, until the cached code expires.

The credentials can be provided in calliope.conf as follows:

[lastfm] client-id = <API Key> client-secret = <Shared Secret> redirect-uri = http://


The calliope.cache module is used to cache requests.


Package Contents



Context for accessing API.


prompt_for_user_token(username[, client_id, ...])

Prompt user to obtain authorization token.

annotate_tags(context, playlist)

similar_artists(context, count, artist_name)

Given an artist, return similar artists.

similar_tracks(context, count, artist_name, track_name)

Given a track artist and title, return similar tracks.

top_artists(context, count, time_range, include)

Return top artists for the given user.

class calliope.lastfm.LastfmContext(config, user=None)

Context for accessing API.

The authenticate() function must be called to obtain a lastfmclient.LastfmClient object.

  • config – Provides lastfm.user, lastfm.client-id, lastfm.client-secret and lastfm.redirect-uri

  • user – Allows overriding lastfm.user

calliope.lastfm.prompt_for_user_token(username, client_id=None, client_secret=None, redirect_uri=None)

Prompt user to obtain authorization token.

calliope.lastfm.annotate_tags(context, playlist)
calliope.lastfm.similar_artists(context, count, artist_name)

Given an artist, return similar artists.

calliope.lastfm.similar_tracks(context, count, artist_name, track_name)

Given a track artist and title, return similar tracks.

calliope.lastfm.top_artists(context, count, time_range, include)

Return top artists for the given user.