Package lastfm :: Module api :: Class Api
[hide private]
[frames] | no frames]

Class Api

source code

object --+
         |
        Api

The class representing the last.fm web services API.

Instance Methods [hide private]
 
__init__(self, api_key, secret=None, session_key=None, input_encoding=None, request_headers=None, no_cache=False, debug=False)
Create an Api object to access the last.fm webservice API.
source code
 
set_session_key(self)
Set the session key for the authenticated session.
source code
 
set_cache(self, cache)
Override the default cache.
source code
 
set_urllib(self, urllib)
Override the default urllib implementation.
source code
 
set_cache_timeout(self, cache_timeout)
Override the default cache timeout.
source code
 
set_user_agent(self, user_agent)
Override the default user agent.
source code
Album
get_album(self, album=None, artist=None, mbid=None)
Get an album object.
source code
lazylist of Album
search_album(self, album, limit=None)
Search for an album by name.
source code
Artist
get_artist(self, artist=None, mbid=None)
Get an artist object.
source code
lazylist of Artist
search_artist(self, artist, limit=None)
Search for an artist by name.
source code
Event
get_event(self, event)
Get an event object.
source code
Location
get_location(self, city)
Get a location object.
source code
Country
get_country(self, name)
Get a country object.
source code
Group
get_group(self, name)
Get a group object.
source code
Playlist
get_playlist(self, url)
Get a playlist object.
source code
Tag
get_tag(self, name)
Get a tag object.
source code
list of Tag
get_global_top_tags(self)
Get the top global tags on Last.fm, sorted by popularity (number of times used).
source code
lazylist of Tag
search_tag(self, tag, limit=None)
Search for a tag by name.
source code
Tasteometer
compare_taste(self, type1, type2, value1, value2, limit=None)
Get a Tasteometer score from two inputs, along with a list of shared artists.
source code
Track
get_track(self, track, artist=None, mbid=None)
Get a track object.
source code
lazylist of Track
search_track(self, track, artist=None, limit=None)
Search for a track by name.
source code
User
get_user(self, name)
Get an user object.
source code
User
get_authenticated_user(self)
Get the currently authenticated user.
source code
Venue
get_venue(self, venue)
Get a venue object.
source code
lazylist of Venue
search_venue(self, venue, limit=None, country=None)
Search for a venue by name.
source code
 
_build_url(self, url, path_elements=None, extra_params=None) source code
 
_initialize_request_headers(self, request_headers) source code
 
_initialize_user_agent(self) source code
 
_get_opener(self, url) source code
 
_encode(self, s) source code
 
_encode_parameters(self, parameters) source code
 
_read_url_data(self, opener, url, data=None) source code
 
_fetch_url(self, url, parameters=None, no_cache=False) source code
 
_fetch_data(self, params, sign=False, session=False, no_cache=False) source code
 
_post_url(self, url, parameters) source code
 
_post_data(self, params) source code
 
_get_api_sig(self, params) source code
 
_check_xml(self, xml) source code
 
__repr__(self)
repr(x)
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  DEFAULT_CACHE_TIMEOUT = 3600
Default file cache timeout, in seconds
  API_ROOT_URL = 'http://ws.audioscrobbler.com/2.0/'
URL of the webservice API root
  FETCH_INTERVAL = 1
The minimum interval between successive HTTP request, in seconds
  SEARCH_XMLNS = 'http://a9.com/-/spec/opensearch/1.1/'
Properties [hide private]
str api_key
The last.fm API key
str secret
The last.fm API secret
str session_key
Session key for the authenticated session
str auth_token
The authenication token for the authenticated session.
str auth_url
The authenication URL for the authenticated session.

Inherited from object: __class__

Method Details [hide private]

__init__(self, api_key, secret=None, session_key=None, input_encoding=None, request_headers=None, no_cache=False, debug=False)
(Constructor)

source code 

Create an Api object to access the last.fm webservice API. Use this object as a starting point for accessing all the webservice methods.

Parameters:
  • api_key (str) - last.fm API key
  • secret (str) - last.fm API secret (optional, required only for authenticated webservice methods)
  • session_key (str) - session key for the authenticated session (optional, required only for authenticated webservice methods)
  • input_encoding (str) - encoding of the input data (optional)
  • request_headers (dict) - HTTP headers for the requests to last.fm webservices (optional)
  • no_cache (bool) - flag to switch off file cache (optional)
  • debug (bool) - flag to switch on debugging (optional)
Overrides: object.__init__

set_session_key(self)

source code 

Set the session key for the authenticated session.

Raises:

set_cache(self, cache)

source code 

Override the default cache. Set to None to prevent caching.

Parameters:

set_urllib(self, urllib)

source code 

Override the default urllib implementation.

Parameters:
  • urllib (urllib2) - an instance that supports the same API as the urllib2 module

set_cache_timeout(self, cache_timeout)

source code 

Override the default cache timeout.

Parameters:
  • cache_timeout (int) - time, in seconds, that responses should be reused

set_user_agent(self, user_agent)

source code 

Override the default user agent.

Parameters:
  • user_agent (str) - a string that should be send to the server as the User-agent

get_album(self, album=None, artist=None, mbid=None)

source code 

Get an album object.

Parameters:
  • album (str) - the album name
  • artist (str OR Artist) - the album artist name
  • mbid (str) - MBID of the album
Returns: Album
an Album object corresponding the provided album name
Raises:

See Also: Album.get_info

search_album(self, album, limit=None)

source code 

Search for an album by name.

Parameters:
  • album (str) - the album name
  • limit (int) - maximum number of results returned (optional)
Returns: lazylist of Album
matches sorted by relevance

See Also: Album.search

get_artist(self, artist=None, mbid=None)

source code 

Get an artist object.

Parameters:
  • artist (str) - the artist name
  • mbid (str) - MBID of the artist
Returns: Artist
an Artist object corresponding the provided artist name
Raises:

See Also: Artist.get_info

search_artist(self, artist, limit=None)

source code 

Search for an artist by name.

Parameters:
  • artist (str) - the artist name
  • limit (int) - maximum number of results returned (optional)
Returns: lazylist of Artist
matches sorted by relevance

See Also: Artist.search

get_event(self, event)

source code 

Get an event object.

Parameters:
  • event (int) - the event id
Returns: Event
an event object corresponding to the event id provided
Raises:

See Also: Event.get_info

get_location(self, city)

source code 

Get a location object.

Parameters:
  • city (str) - the city name
Returns: Location
a location object corresponding to the city name provided

get_country(self, name)

source code 

Get a country object.

Parameters:
  • name (str) - the country name
Returns: Country
a country object corresponding to the country name provided

get_group(self, name)

source code 

Get a group object.

Parameters:
  • name (str) - the group name
Returns: Group
a group object corresponding to the group name provided

get_playlist(self, url)

source code 

Get a playlist object.

Parameters:
  • url (str) - lastfm url of the playlist
Returns: Playlist
a playlist object corresponding to the playlist url provided

See Also: Playlist.fetch

get_tag(self, name)

source code 

Get a tag object.

Parameters:
  • name (str) - the tag name
Returns: Tag
a tag object corresponding to the tag name provided

get_global_top_tags(self)

source code 

Get the top global tags on Last.fm, sorted by popularity (number of times used).

Returns: list of Tag
a list of top global tags

search_tag(self, tag, limit=None)

source code 

Search for a tag by name.

Parameters:
  • tag (str) - the tag name
  • limit (int) - maximum number of results returned (optional)
Returns: lazylist of Tag
matches sorted by relevance

See Also: Tag.search

compare_taste(self, type1, type2, value1, value2, limit=None)

source code 

Get a Tasteometer score from two inputs, along with a list of shared artists. If the input is a User or a Myspace URL, some additional information is returned.

Parameters:
  • type1 (str) - 'user' OR 'artists' OR 'myspace'
  • type2 (str) - 'user' OR 'artists' OR 'myspace'
  • value1 (str) - Last.fm username OR Comma-separated artist names OR MySpace profile URL
  • value2 (str) - Last.fm username OR Comma-separated artist names OR MySpace profile URL
  • limit (int) - maximum number of results returned (optional)
Returns: Tasteometer
the taste-o-meter score for the inputs

get_track(self, track, artist=None, mbid=None)

source code 

Get a track object.

Parameters:
  • track (str) - the track name
  • artist (str OR Artist) - the track artist
  • mbid (str) - MBID of the track
Returns: Track
a track object corresponding to the track name provided
Raises:

See Also: Track.get_info

search_track(self, track, artist=None, limit=None)

source code 

Search for a track by name.

Parameters:
  • track (str) - the track name
  • artist (str OR Artist) - the track artist (optional)
  • limit (int) - maximum number of results returned (optional)
Returns: lazylist of Track
matches sorted by relevance

See Also: Track.search

get_user(self, name)

source code 

Get an user object.

Parameters:
  • name (str) - the last.fm user name
Returns: User
an user object corresponding to the user name provided
Raises:

See Also: User.get_info

get_authenticated_user(self)

source code 

Get the currently authenticated user.

Returns: User
The currently authenticated user if the session is authenticated

get_venue(self, venue)

source code 

Get a venue object.

Parameters:
  • venue (str) - the venue name
Returns: Venue
a venue object corresponding to the venue name provided
Raises:

See Also: search_venue

search_venue(self, venue, limit=None, country=None)

source code 

Search for a venue by name.

Parameters:
  • venue (str) - the venue name
  • country (str) - filter the results by country. Expressed as an ISO 3166-2 code. (optional)
  • limit (int) - maximum number of results returned (optional)
Returns: lazylist of Venue
matches sorted by relevance

See Also: Venue.search

__repr__(self)
(Representation operator)

source code 

repr(x)

Overrides: object.__repr__
(inherited documentation)

Property Details [hide private]

api_key

The last.fm API key

Get Method:
unreachable.api_key(self) - The last.fm API key
Type:
str

secret

The last.fm API secret

Get Method:
unreachable.secret(self) - The last.fm API secret
Type:
str

session_key

Session key for the authenticated session

Get Method:
unreachable.session_key(self) - Session key for the authenticated session
Type:
str

auth_token

The authenication token for the authenticated session.

Get Method:
unreachable.wrapper(ob)
Type:
str

auth_url

The authenication URL for the authenticated session.

Get Method:
unreachable.wrapper(ob)
Type:
str