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_secret(self, secret) Set the last.fm API secret. | source code

set_session_key(self, session_key=None) 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 authentication token for the authenticated session.
`str` | auth_url The authentication 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_secret(self, secret)

source code

Set the last.fm API secret.

Parameters:
  - `secret` (`str`) - the secret

### set_session_key(self, session_key=None)

source code

Set the session key for the authenticated session.

Parameters:
  - `session_key` (`str`) - the session key for authentication (optional). If not provided then a new one is fetched from last.fm
Raises:
  - `lastfm.AuthenticationFailedError` - Either session_key should be provided or API secret must be present.

### set_cache(self, cache)

source code

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

Parameters:
  - `cache` (FileCache) - an instance that supports the same API as the FileCache

### 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:
  - `lastfm.InvalidParametersError` - Either album and artist parameters or mbid parameter has to be provided. Otherwise exception is raised.

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:
  - `lastfm.InvalidParametersError` - either artist or mbid parameter has to be provided. Otherwise exception is raised.

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:
  - `InvalidParametersError` - Exception is raised if an invalid event id is supplied.

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

See Also: Tasteometer.compare

### 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:
  - `lastfm.InvalidParametersError` - either artist or mbid parameter has to be provided. Otherwise exception is raised.

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:
  - `InvalidParametersError` - Exception is raised if an invalid user name is supplied.

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

See Also: User.get_authenticated_user

### 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:
  - `InvalidParametersError` - Exception is raised if an non-existant venue name is supplied.

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 authentication token for the authenticated session.

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

### auth_url

The authentication URL for the authenticated session.

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