From 0e78d9344efcd0a67c65405e6d1e6e1c02466d07 Mon Sep 17 00:00:00 2001 From: Amr Hassan Date: Mon, 2 Feb 2009 15:14:39 +0000 Subject: [PATCH] now with documentation --- documentation.html | 1563 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1563 insertions(+) create mode 100644 documentation.html diff --git a/documentation.html b/documentation.html new file mode 100644 index 0000000..853613f --- /dev/null +++ b/documentation.html @@ -0,0 +1,1563 @@ + + +Python: module pylast + + + + +
 
+ 
pylast (version 0.3.0a)		index
/home/amr/Dropbox/projects/pylast/trunk/pylast.py
+

A Python interface to the Last.fm API.

+

+ + + + + +
 
+Modules
       
hashlib
+httplib
+		xml.dom.minidom
+os
+		threading
+time
+		urllib
+

+ + + + + +
 
+Classes
       
+
__builtin__.object +
+
+
LibraryItem +
SessionKeyGenerator +
TopItem +
+
+
exceptions.Exception(exceptions.BaseException) +
+
+
ServiceException +
+
+
_BaseObject(__builtin__.object) +
+
+
Album(_BaseObject, _Taggable) +
Artist(_BaseObject, _Taggable) +
Country +
Event +
Group +
Library +
Playlist +
Tag +
Track(_BaseObject, _Taggable) +
User +
+
+
AuthenticatedUser +
+
+
Venue +
XSPF +
+
+
_Search(_BaseObject) +
+
+
AlbumSearch +
ArtistSearch +
TagSearch +
TrackSearch +
VenueSearch +
+
+
_Taggable(__builtin__.object) +
+
+
Album(_BaseObject, _Taggable) +
Artist(_BaseObject, _Taggable) +
Track(_BaseObject, _Taggable) +
+
+
+

+ + + + + + + +
 
+class Album(_BaseObject, _Taggable)
   A Last.fm album.
 
 
Method resolution order:
+
Album
+
_BaseObject
+
_Taggable
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, artist, title, api_key, api_secret, session_key)
Create an album instance.
+# Parameters:
+        * artist str|Artist: An artist name or an Artist object.
+        * title str: The album title.
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
get_artist(self)
Returns the associated Artist object.
+ +
get_id(self)
Returns the Last.fm ID.
+ +
get_image_url(self, size=3)
Returns the associated image URL.
+# Parameters:
+* size int: The image size. Possible values:
+        o IMAGE_EXTRA_LARGE
+        o IMAGE_LARGE
+        o IMAGE_MEDIUM
+        o IMAGE_SMALL
+ +
get_listener_count(self)
Returns the number of liteners on Last.fm.
+ +
get_mbid(self)
Returns the MusicBrainz id of the album.
+ +
get_name(self)
Returns the album title (alias to Album.get_title).
+ +
get_playcount(self)
Returns the number of plays on Last.fm.
+ +
get_release_date(self)
Retruns the release date of the album.
+ +
get_title(self)
Returns the album title.
+ +
get_top_tags(self, limit=None)
Returns a list of the most-applied tags to this album.
+ +
get_tracks(self)
Returns the list of Tracks on this album.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the album page on Last.fm. 
+# Parameters:
+* domain_name str: Last.fm's language domain. Possible values:
+        o DOMAIN_ENGLISH
+        o DOMAIN_GERMAN
+        o DOMAIN_SPANISH
+        o DOMAIN_FRENCH
+        o DOMAIN_ITALIAN
+        o DOMAIN_POLISH
+        o DOMAIN_PORTUGUESE
+        o DOMAIN_SWEDISH
+        o DOMAIN_TURKISH
+        o DOMAIN_RUSSIAN
+        o DOMAIN_JAPANESE
+        o DOMAIN_CHINESE
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+
+Methods inherited from _Taggable:
+
add_tags(self, *tags)
Adds one or several tags.
+* *tags: Any number of tag names or Tag objects.
+ +
clear_tags(self)
Clears all the user-set tags.
+ +
get_tags(self)
Returns a list of the tags set by the user to this object.
+ +
remove_tags(self, *tags)
Removes one or several tags from this object.
+* *tags: Any number of tag names or Tag objects.
+ +
set_tags(self, *tags)
Sets this object's tags to only those tags.
+* *tags: any number of tag names.
+ +

+ + + + + + + +
 
+class AlbumSearch(_Search)
   Search for an album by name.
 
 
Method resolution order:
+
AlbumSearch
+
_Search
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, album_name, api_key, api_secret, session_key)
+ +
get_next_page(self)
Returns the next page of results as a sequence of Album objects.
+ +
+Methods inherited from _Search:
+
get_total_result_count(self)
Returns the total count of all the results.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Artist(_BaseObject, _Taggable)
   A Last.fm artist.
 
 
Method resolution order:
+
Artist
+
_BaseObject
+
_Taggable
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, name, api_key, api_secret, session_key)
Create an artist object.
+# Parameters:
+        * name str: The artist's name.
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
get_bio_content(self)
Returns the content of the artist's biography.
+ +
get_bio_published_date(self)
Returns the date on which the artist's biography was published.
+ +
get_bio_summary(self)
Returns the summary of the artist's biography.
+ +
get_image_url(self, size=2)
Returns the associated image URL. 
+# Parameters:
+        * size int: The image size. Possible values:
+          o IMAGE_LARGE
+          o IMAGE_MEDIUM
+          o IMAGE_SMALL
+ +
get_listener_count(self)
Returns the number of liteners on Last.fm.
+ +
get_name(self)
Returns the name of the artist.
+ +
get_playcount(self)
Returns the number of plays on Last.fm.
+ +
get_similar(self, limit=None)
Returns the similar artists on Last.fm.
+ +
get_top_albums(self)
Retuns a list of the top albums.
+ +
get_top_fans(self, limit=None)
Returns a list of the Users who played this artist the most.
+# Parameters:
+        * limit int: Max elements.
+ +
get_top_tracks(self)
Returns a list of the most played Tracks by this artist.
+ +
get_upcoming_events(self)
Returns a list of the upcoming Events for this artist.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the artist page on Last.fm. 
+# Parameters:
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
is_streamable(self)
Returns True if the artist is streamable.
+ +
share(self, users, message=None)
Shares this artist (sends out recommendations). 
+# Parameters:
+        * users [User|str,]: A list that can contain usernames, emails, User objects, or all of them.
+        * message str: A message to include in the recommendation message.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+
+Methods inherited from _Taggable:
+
add_tags(self, *tags)
Adds one or several tags.
+* *tags: Any number of tag names or Tag objects.
+ +
clear_tags(self)
Clears all the user-set tags.
+ +
get_tags(self)
Returns a list of the tags set by the user to this object.
+ +
get_top_tags(self, limit=None)
Returns a list of the most frequently used Tags on this object.
+ +
remove_tags(self, *tags)
Removes one or several tags from this object.
+* *tags: Any number of tag names or Tag objects.
+ +
set_tags(self, *tags)
Sets this object's tags to only those tags.
+* *tags: any number of tag names.
+ +

+ + + + + + + +
 
+class ArtistSearch(_Search)
   Search for an artist by artist name.
 
 
Method resolution order:
+
ArtistSearch
+
_Search
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, artist_name, api_key, api_secret, session_key)
+ +
get_next_page(self)
Returns the next page of results as a sequence of Artist objects.
+ +
+Methods inherited from _Search:
+
get_total_result_count(self)
Returns the total count of all the results.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + +
 
+class AuthenticatedUser(User)
    
Method resolution order:
+
AuthenticatedUser
+
User
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, api_key, api_secret, session_key)
+ +
get_age(self)
Returns the user's age.
+ +
get_country(self)
Returns the name of the country of the user.
+ +
get_gender(self)
Returns the user's gender. Either USER_MALE or USER_FEMALE.
+ +
get_id(self)
Returns the user id.
+ +
get_image_url(self)
Returns the user's avatar.
+ +
get_language(self)
Returns the language code of the language used by the user.
+ +
get_name(self)
Returns the name of the authenticated user.
+ +
get_playcount(self)
Returns the user's playcount so far.
+ +
get_recommended_artists_page(self)
Retruns a paginated list of all artists a user has attended in the past.
+ 
+Example:
+--------
+ 
+while not user.is_end_of_recommended_artists():
+        print user.get_recommended_artists_page()
+ +
get_recommended_events_page(self)
Retruns a paginated list of all events a user has attended in the past.
+ 
+Example:
+--------
+ 
+while not user.is_end_of_recommended_events():
+        print user.get_recommended_events_page()
+ +
is_end_of_recommended_artists(self)
Returns True if the end of Past Artists was reached.
+ +
is_end_of_recommended_events(self)
Returns True if the end of Past Events was reached.
+ +
is_subscriber(self)
Returns whether the user is a subscriber or not. True or False.
+ +
+Methods inherited from User:
+
__eq__(self, another)
+ +
__ne__(self, another)
+ +
__repr__(self)
+ +
compare_with_user(self, user, shared_artists_limit=None)
Compare this user with another Last.fm user.
+Returns a sequence (tasteometer_score, (shared_artist1, shared_artist2, ...))
+user: A User object or a username string/unicode object.
+ +
getRecommendedEvents(self, page=None, limit=None)
Returns a paginated list of all events recommended to a user by Last.fm, based on their listening profile.
+* page: The page number of results to return.
+* limit: The limit of events to return.
+ +
get_friends(self, limit=None)
Returns a list of the user's friends.
+ +
get_library(self)
Returns the associated Library object.
+ +
get_loved_tracks(self)
Returns the last 50 tracks loved by this user.
+ +
get_neighbours(self, limit=None)
Returns a list of the user's friends.
+ +
get_now_playing(self)
Returns the currently playing track, or None if nothing is playing.
+ +
get_past_events_page(self)
Retruns a paginated list of all events a user has attended in the past.
+ 
+Example:
+--------
+ 
+while not user.is_end_of_past_events():
+        print user.get_past_events_page()
+ +
get_playlists(self)
Returns a list of Playlists that this user owns.
+ +
get_recent_tracks(self, limit=None)
Returns this user's recent listened-to tracks.
+ +
get_top_albums(self, period='overall')
Returns the top albums played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_top_artists(self, period='overall')
Returns the top artists played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_top_tags(self, limit=None)
Returns a sequence of the top tags used by this user with their counts as (Tag, tagcount). 
+* limit: The limit of how many tags to return.
+ +
get_top_tracks(self, period='overall')
Returns the top tracks played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_upcoming_events(self)
Returns all the upcoming events for this user.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the user page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_weekly_album_charts(self, from_date=None, to_date=None)
Returns the weekly album charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_artist_charts(self, from_date=None, to_date=None)
Returns the weekly artist charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_chart_dates(self)
Returns a list of From and To tuples for the available charts.
+ +
get_weekly_track_charts(self, from_date=None, to_date=None)
Returns the weekly track charts for the week starting from the from_date value to the to_date value.
+ +
is_end_of_past_events(self)
Returns True if the end of Past Events was reached.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Country(_BaseObject)
   A country at Last.fm.
 
 
Method resolution order:
+
Country
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, name, api_key, api_secret, session_key)
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
get_name(self)
Returns the country name.
+ +
get_top_artists(self)
Returns a sequence of the most played artists.
+ +
get_top_tracks(self)
Returns a sequence of the most played tracks
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the event page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Event(_BaseObject)
   A Last.fm event.
 
 
Method resolution order:
+
Event
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, event_id, api_key, api_secret, session_key)
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
attend(self, attending_status)
Sets the attending status.
+* attending_status: The attending status. Possible values:
+  o EVENT_ATTENDING
+  o EVENT_MAYBE_ATTENDING
+  o EVENT_NOT_ATTENDING
+ +
get_artists(self)
Returns a list of the participating Artists.
+ +
get_attendance_count(self)
Returns the number of attending people.
+ +
get_description(self)
Returns the description of the event.
+ +
get_headliner(self)
Returns the headliner of the event.
+ +
get_id(self)
Returns the id of the event on Last.fm.
+ +
get_image_url(self, size=2)
Returns the associated image URL. 
+* size: The image size. Possible values:
+  o IMAGE_LARGE
+  o IMAGE_MEDIUM
+  o IMAGE_SMALL
+ +
get_review_count(self)
Returns the number of available reviews for this event.
+ +
get_start_date(self)
Returns the date when the event starts.
+ +
get_title(self)
Returns the title of the event.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the event page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_venue(self)
Returns the venue where the event is held.
+ +
share(self, users, message=None)
Shares this event (sends out recommendations). 
+* users: A list that can contain usernames, emails, User objects, or all of them.
+* message: A message to include in the recommendation message.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Group(_BaseObject)
   A Last.fm group.
 
 
Method resolution order:
+
Group
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, group_name, api_key, api_secret, session_key)
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
get_name(self)
Returns the group name.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the group page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_weekly_album_charts(self, from_date=None, to_date=None)
Returns the weekly album charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_artist_charts(self, from_date=None, to_date=None)
Returns the weekly artist charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_chart_dates(self)
Returns a list of From and To tuples for the available charts.
+ +
get_weekly_track_charts(self, from_date=None, to_date=None)
Returns the weekly track charts for the week starting from the from_date value to the to_date value.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Library(_BaseObject)
   A user's Last.fm library.
 
 
Method resolution order:
+
Library
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, user, api_key, api_secret, session_key)
+ +
__repr__(self)
+ +
add_album(self, album)
Add an album to this library.
+ +
add_artist(self, artist)
Add an artist to this library.
+ +
add_track(self, track)
Add a track to this library.
+ +
get_albums_page(self)
Retreives the next page of albums in the Library. Returns a sequence of TopItem objects.
+Use the function extract_items like extract_items(Library.get_albums_page()) to return only a sequence of
+Album objects with no extra data.
+ 
+Example:
+-------
+library = Library("rj", API_KEY, API_SECRET, SESSION_KEY)
+ 
+while not library.is_end_of_albums():
+        print library.get_albums_page()
+ +
get_artists_page(self)
Retreives the next page of artists in the Library. Returns a sequence of TopItem objects.
+Use the function extract_items like extract_items(Library.get_artists_page()) to return only a sequence of
+Artist objects with no extra data.
+ 
+Example:
+-------
+library = Library("rj", API_KEY, API_SECRET, SESSION_KEY)
+ 
+while not library.is_end_of_artists():
+        print library.get_artists_page()
+ +
get_tracks_page(self)
Retreives the next page of tracks in the Library. Returns a sequence of TopItem objects.
+Use the function extract_items like extract_items(Library.get_tracks_page()) to return only a sequence of
+Track objects with no extra data.
+ 
+Example:
+-------
+library = Library("rj", API_KEY, API_SECRET, SESSION_KEY)
+ 
+while not library.is_end_of_tracks():
+        print library.get_tracks_page()
+ +
get_user(self)
Returns the user who owns this library.
+ +
is_end_of_albums(self)
Returns True when the last page of albums has ben retrieved.
+ +
is_end_of_artists(self)
Returns True when the last page of artists has ben retrieved.
+ +
is_end_of_tracks(self)
Returns True when the last page of tracks has ben retrieved.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class LibraryItem(__builtin__.object)
   An item in a User's Library. It could be an artist, an album or a track.
 
 Methods defined here:
+
__init__(self, item, playcount, tagcount)
+ +
__repr__(self)
+ +
get_item(self)
Returns the itme.
+ +
get_playcount(self)
Returns the item's playcount in the Library.
+ +
get_tagcount(self)
Returns the item's tagcount in the Library.
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Playlist(_BaseObject)
   A Last.fm user playlist.
 
 
Method resolution order:
+
Playlist
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, user, id, api_key, api_secret, session_key)
+ +
add_track(self, track)
Adds a Track to this Playlist.
+ +
get_creation_date(self)
Returns the creation date of this playlist.
+ +
get_description(self)
Returns the description of this playlist.
+ +
get_duration(self)
Returns the duration of this playlist in milliseconds.
+ +
get_id(self)
Returns the playlist id.
+ +
get_image_url(self, size=2)
Returns the associated image URL.
+* size: The image size. Possible values:
+  o IMAGE_LARGE
+  o IMAGE_MEDIUM
+  o IMAGE_SMALL
+ +
get_size(self)
Returns the number of tracks in this playlist.
+ +
get_title(self)
Returns the title of this playlist.
+ +
get_tracks(self)
Returns a list of the tracks on this user playlist.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the playlist on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_user(self)
Returns the owner user of this playlist.
+ +
has_track(self, track)
Checks to see if track is already in the playlist.
+* track: Any Track object.
+ +
is_streamable(self)
Returns True if the playlist is streamable.
+For a playlist to be streamable, it needs at least 45 tracks by 15 different artists.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class ServiceException(exceptions.Exception)
   Exception related to the Last.fm web service
 
 
Method resolution order:
+
ServiceException
+
exceptions.Exception
+
exceptions.BaseException
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, lastfm_status, details)
+ +
__str__(self)
+ +
get_id(self)
Returns the exception ID, from one of the following:
+STATUS_INVALID_SERVICE = 2
+STATUS_INVALID_METHOD = 3
+STATUS_AUTH_FAILED = 4
+STATUS_INVALID_FORMAT = 5
+STATUS_INVALID_PARAMS = 6
+STATUS_INVALID_RESOURCE = 7
+STATUS_TOKEN_ERROR = 8
+STATUS_INVALID_SK = 9
+STATUS_INVALID_API_KEY = 10
+STATUS_OFFLINE = 11
+STATUS_SUBSCRIBERS_ONLY = 12
+STATUS_TOKEN_UNAUTHORIZED = 14
+STATUS_TOKEN_EXPIRED = 15
+ +
+Data descriptors defined here:
+
__weakref__
+
list of weak references to the object (if defined)
+
+
+Data and other attributes inherited from exceptions.Exception:
+
__new__ = <built-in method __new__ of type object at 0x8145ea0>
T.__new__(S, ...) -> a new object with type S, a subtype of T
+ +
+Methods inherited from exceptions.BaseException:
+
__delattr__(...)
x.__delattr__('name') <==> del x.name
+ +
__getattribute__(...)
x.__getattribute__('name') <==> x.name
+ +
__getitem__(...)
x.__getitem__(y) <==> x[y]
+ +
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
+ 
+Use of negative indices is not supported.
+ +
__reduce__(...)
+ +
__repr__(...)
x.__repr__() <==> repr(x)
+ +
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
+ +
__setstate__(...)
+ +
+Data descriptors inherited from exceptions.BaseException:
+
__dict__
+
+
args
+
+
message
+
exception message
+
+

+ + + + + + + +
 
+class SessionKeyGenerator(__builtin__.object)
   Methods of generating a session key:
+1) Web Authentication:
+        a. sg = SessionKeyGenerator(API_KEY, API_SECRET)
+        b. url = sg.get_web_auth_url()
+        c. Ask the user to open the url and authorize you, and wait for it.
+        d. session_key = sg.get_web_auth_session_key(url)
+2) Username and Password Authentication:
+        a. username = raw_input("Please enter your username: ")
+        b. md5_password = pylast.md5(raw_input("Please enter your password: ")
+        c. session_key = SessionKeyGenerator(API_KEY, API_SECRET).get_session_key(username, md5_password)
+ 
+A session key's lifetime is infinie, unless the user provokes the rights of the given API Key.
 
 Methods defined here:
+
__init__(self, api_key, api_secret)
+ +
get_session_key(self, username, md5_password)
Retrieve a session key with a username and a md5 hash of the user's password.
+ +
get_web_auth_session_key(self, url)
Retrieves the session key of a web authorization process by its url.
+ +
get_web_auth_url(self)
The user must open this page, and you first, then call get_web_auth_session_key(url) after that.
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Tag(_BaseObject)
   A Last.fm object tag.
 
 
Method resolution order:
+
Tag
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self)
+ +
__init__(self, name, api_key, api_secret, session_key)
+ +
__ne__(self)
+ +
__repr__(self)
+ +
get_name(self)
Returns the name of the tag.
+ +
get_similar(self)
Returns the tags similar to this one, ordered by similarity.
+ +
get_top_albums(self)
Retuns a list of the top albums.
+ +
get_top_artists(self)
Returns a sequence of the most played artists.
+ +
get_top_tracks(self)
Returns a list of the most played Tracks by this artist.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the tag page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_weekly_artist_charts(self, from_date=None, to_date=None)
Returns the weekly artist charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_chart_dates(self)
Returns a list of From and To tuples for the available charts.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class TagSearch(_Search)
   Search for a tag by tag name.
 
 
Method resolution order:
+
TagSearch
+
_Search
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, tag_name, api_key, api_secret, session_key)
+ +
get_next_page(self)
Returns the next page of results as a sequence of Tag objects.
+ +
+Methods inherited from _Search:
+
get_total_result_count(self)
Returns the total count of all the results.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class TopItem(__builtin__.object)
   A top item in a list that has a weight. Returned from functions like get_top_tracks() and get_top_artists().
 
 Methods defined here:
+
__init__(self, item, weight)
+ +
__repr__(self)
+ +
get_item(self)
Returns the item.
+ +
get_weight(self)
Returns the weight of the itme in the list.
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Track(_BaseObject, _Taggable)
   A Last.fm track.
 
 
Method resolution order:
+
Track
+
_BaseObject
+
_Taggable
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, artist, title, api_key, api_secret, session_key)
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
ban(self)
Ban this track from ever playing on the radio.
+ +
get_album(self)
Returns the album object of this track.
+ +
get_artist(self)
Returns the associated Artist object.
+ +
get_duration(self)
Returns the track duration.
+ +
get_id(self)
Returns the track id on Last.fm.
+ +
get_listener_count(self)
Returns the listener count.
+ +
get_mbid(self)
Returns the MusicBrainz ID of this track.
+ +
get_name(self)
Returns the track title (alias to Track.get_title).
+ +
get_playcount(self)
Returns the play count.
+ +
get_similar(self)
Returns similar tracks for this track on Last.fm, based on listening data.
+ +
get_title(self)
Returns the track title.
+ +
get_top_fans(self, limit=None)
Returns a list of the Users who played this track.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the track page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_wiki_content(self)
Returns the content of the wiki.
+ +
get_wiki_published_date(self)
Returns the date of publishing this version of the wiki.
+ +
get_wiki_summary(self)
Returns the summary of the wiki.
+ +
is_fulltrack_available(self)
Returns True if the fulltrack is available for streaming.
+ +
is_streamable(self)
Returns True if the track is available at Last.fm.
+ +
love(self)
Adds the track to the user's loved tracks.
+ +
share(self, users, message=None)
Shares this track (sends out recommendations). 
+* users: A list that can contain usernames, emails, User objects, or all of them.
+* message: A message to include in the recommendation message.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+
+Methods inherited from _Taggable:
+
add_tags(self, *tags)
Adds one or several tags.
+* *tags: Any number of tag names or Tag objects.
+ +
clear_tags(self)
Clears all the user-set tags.
+ +
get_tags(self)
Returns a list of the tags set by the user to this object.
+ +
get_top_tags(self, limit=None)
Returns a list of the most frequently used Tags on this object.
+ +
remove_tags(self, *tags)
Removes one or several tags from this object.
+* *tags: Any number of tag names or Tag objects.
+ +
set_tags(self, *tags)
Sets this object's tags to only those tags.
+* *tags: any number of tag names.
+ +

+ + + + + + + +
 
+class TrackSearch(_Search)
   Search for a track by track title. If you don't wanna narrow the results down
+by specifying the artist name, set it to empty string.
 
 
Method resolution order:
+
TrackSearch
+
_Search
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, artist_name, track_title, api_key, api_secret, session_key)
+ +
get_next_page(self)
Returns the next page of results as a sequence of Track objects.
+ +
+Methods inherited from _Search:
+
get_total_result_count(self)
Returns the total count of all the results.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class User(_BaseObject)
   A Last.fm user.
 
 
Method resolution order:
+
User
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, another)
+ +
__init__(self, user_name, api_key, api_secret, session_key)
+ +
__ne__(self, another)
+ +
__repr__(self)
+ +
compare_with_user(self, user, shared_artists_limit=None)
Compare this user with another Last.fm user.
+Returns a sequence (tasteometer_score, (shared_artist1, shared_artist2, ...))
+user: A User object or a username string/unicode object.
+ +
getRecommendedEvents(self, page=None, limit=None)
Returns a paginated list of all events recommended to a user by Last.fm, based on their listening profile.
+* page: The page number of results to return.
+* limit: The limit of events to return.
+ +
get_friends(self, limit=None)
Returns a list of the user's friends.
+ +
get_library(self)
Returns the associated Library object.
+ +
get_loved_tracks(self)
Returns the last 50 tracks loved by this user.
+ +
get_name(self)
Returns the nuser name.
+ +
get_neighbours(self, limit=None)
Returns a list of the user's friends.
+ +
get_now_playing(self)
Returns the currently playing track, or None if nothing is playing.
+ +
get_past_events_page(self)
Retruns a paginated list of all events a user has attended in the past.
+ 
+Example:
+--------
+ 
+while not user.is_end_of_past_events():
+        print user.get_past_events_page()
+ +
get_playlists(self)
Returns a list of Playlists that this user owns.
+ +
get_recent_tracks(self, limit=None)
Returns this user's recent listened-to tracks.
+ +
get_top_albums(self, period='overall')
Returns the top albums played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_top_artists(self, period='overall')
Returns the top artists played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_top_tags(self, limit=None)
Returns a sequence of the top tags used by this user with their counts as (Tag, tagcount). 
+* limit: The limit of how many tags to return.
+ +
get_top_tracks(self, period='overall')
Returns the top tracks played by a user. 
+* period: The period of time. Possible values:
+  o PERIOD_OVERALL
+  o PERIOD_3MONTHS
+  o PERIOD_6MONTHS
+  o PERIOD_12MONTHS
+ +
get_upcoming_events(self)
Returns all the upcoming events for this user.
+ +
get_url(self, domain_name='www.last.fm')
Returns the url of the user page on Last.fm. 
+* domain_name: Last.fm's language domain. Possible values:
+  o DOMAIN_ENGLISH
+  o DOMAIN_GERMAN
+  o DOMAIN_SPANISH
+  o DOMAIN_FRENCH
+  o DOMAIN_ITALIAN
+  o DOMAIN_POLISH
+  o DOMAIN_PORTUGUESE
+  o DOMAIN_SWEDISH
+  o DOMAIN_TURKISH
+  o DOMAIN_RUSSIAN
+  o DOMAIN_JAPANESE
+  o DOMAIN_CHINESE
+ +
get_weekly_album_charts(self, from_date=None, to_date=None)
Returns the weekly album charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_artist_charts(self, from_date=None, to_date=None)
Returns the weekly artist charts for the week starting from the from_date value to the to_date value.
+ +
get_weekly_chart_dates(self)
Returns a list of From and To tuples for the available charts.
+ +
get_weekly_track_charts(self, from_date=None, to_date=None)
Returns the weekly track charts for the week starting from the from_date value to the to_date value.
+ +
is_end_of_past_events(self)
Returns True if the end of Past Events was reached.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Venue(_BaseObject)
   A venue where events are held.
 
 
Method resolution order:
+
Venue
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, id, api_key, api_secret, session_key)
+ +
__repr__(self)
+ +
get_id(self)
Returns the id of the venue.
+ +
get_past_events(self)
Returns the past events held in this venue.
+ +
get_upcoming_events(self)
Returns the upcoming events in this venue.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class VenueSearch(_Search)
   Search for a venue by its name. If you don't wanna narrow the results down
+by specifying a country, set it to empty string.
 
 
Method resolution order:
+
VenueSearch
+
_Search
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, venue_name, country_name, api_key, api_secret, session_key)
+ +
get_next_page(self)
Returns the next page of results as a sequence of Track objects.
+ +
+Methods inherited from _Search:
+
get_total_result_count(self)
Returns the total count of all the results.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class XSPF(_BaseObject)
   A Last.fm XSPF playlist.
 
 
Method resolution order:
+
XSPF
+
_BaseObject
+
__builtin__.object
+
+
+Methods defined here:
+
__eq__(self, other)
+ +
__init__(self, uri, api_key, api_secret, session_key)
+ +
__ne__(self, other)
+ +
__repr__(self)
+ +
get_tracks(self)
Returns the tracks on this playlist.
+ +
get_uri(self)
Returns the Last.fm playlist URI.
+ +
+Data descriptors inherited from _BaseObject:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + +
 
+Functions
       
async_call(sender, call, callback=None, call_args=None, callback_args=None)
This is the function for setting up an asynchronous operation.
+* call: The function to call asynchronously.
+* callback: The function to call after the operation is complete, Its prototype has to be like:
+        callback(sender, output[, param1, param3, ... ])
+* call_args: A sequence of args to be passed to call.
+* callback_args: A sequence of args to be passed to callback.
+
create_new_playlist(title, description, api_key, api_secret, session_key)
Creates a playlist for the authenticated user and returns it.
+* title: The title of the new playlist.
+* description: The description of the new playlist.
+
disable_caching()
Disables all caching features.
+
disable_proxy()
Disable using the web proxy.
+
enable_caching(cache_dir=None)
Enables caching request-wide for all cachable calls.
+* cache_dir: A directory path to use to store the caching data. Set to None to use a temporary directory.
+
enable_proxy(host, port)
Enable a default web proxy.
+
extract_items(topitems_or_libraryitems)
Extracts a sequence of items from a sequence of TopItem or LibraryItem objects.
+
get_album_by_mbid(mbid, api_key, api_secret, session_key)
Looks up an album by its MusicBrainz ID.
+
get_artist_by_mbid(mbid, api_key, api_secret, session_key)
Loooks up an artist by its MusicBrainz ID.
+
get_authenticated_user(api_key, api_secret, session_key)
Returns the authenticated user.
+
get_top_tags(api_key, api_secret, session_key)
Returns a sequence of the most used Last.fm tags as a sequence of TopItem objects.
+
get_track_by_mbid(mbid, api_key, api_secret, session_key)
Looks up a track by its MusicBrainz ID.
+
is_caching_enabled()
Returns True if caching is enabled.
+
is_proxy_enabled()
Returns True if a web proxy is enabled.
+
md5(text)
Returns the md5 hash of a string.
+
search_for_album(album_name, api_key, api_secret, session_key)
Searches for an album by its name. Returns a AlbumSearch object.
+Use get_next_page() to retreive sequences of results.
+
search_for_artist(artist_name, api_key, api_secret, session_key)
Searches of an artist by its name. Returns a ArtistSearch object.
+Use get_next_page() to retreive sequences of results.
+
search_for_tag(tag_name, api_key, api_secret, session_key)
Searches of a tag by its name. Returns a TagSearch object.
+Use get_next_page() to retreive sequences of results.
+
search_for_track(artist_name, track_name, api_key, api_secret, session_key)
Searches of a track by its name and its artist. Set artist to an empty string if not available.
+Returns a TrackSearch object.
+Use get_next_page() to retreive sequences of results.
+
search_for_venue(venue_name, country_name, api_key, api_secret, session_key)
Searches of a venue by its name and its country. Set country_name to an empty string if not available.
+Returns a VenueSearch object.
+Use get_next_page() to retreive sequences of results.
+

+ + + + + +
 
+Data
       DOMAIN_CHINESE = 'cn.last.fm'
+DOMAIN_ENGLISH = 'www.last.fm'
+DOMAIN_FRENCH = 'www.lastfm.fr'
+DOMAIN_GERMAN = 'www.lastfm.de'
+DOMAIN_ITALIAN = 'www.lastfm.it'
+DOMAIN_JAPANESE = 'www.lastfm.jp'
+DOMAIN_POLISH = 'www.lastfm.pl'
+DOMAIN_PORTUGUESE = 'www.lastfm.com.br'
+DOMAIN_RUSSIAN = 'www.lastfm.ru'
+DOMAIN_SPANISH = 'www.lastfm.es'
+DOMAIN_SWEDISH = 'www.lastfm.se'
+DOMAIN_TURKISH = 'www.lastfm.com.tr'
+EVENT_ATTENDING = '0'
+EVENT_MAYBE_ATTENDING = '1'
+EVENT_NOT_ATTENDING = '2'
+IMAGE_EXTRA_LARGE = 3
+IMAGE_LARGE = 2
+IMAGE_MEDIUM = 1
+IMAGE_SMALL = 0
+PERIOD_12MONTHS = '12month'
+PERIOD_3MONTHS = '3month'
+PERIOD_6MONTHS = '6month'
+PERIOD_OVERALL = 'overall'
+STATUS_AUTH_FAILED = 4
+STATUS_INVALID_API_KEY = 10
+STATUS_INVALID_FORMAT = 5
+STATUS_INVALID_METHOD = 3
+STATUS_INVALID_PARAMS = 6
+STATUS_INVALID_RESOURCE = 7
+STATUS_INVALID_SERVICE = 2
+STATUS_INVALID_SIGNATURE = 13
+STATUS_INVALID_SK = 9
+STATUS_OFFLINE = 11
+STATUS_SUBSCRIBERS_ONLY = 12
+STATUS_TOKEN_ERROR = 8
+STATUS_TOKEN_EXPIRED = 15
+STATUS_TOKEN_UNAUTHORIZED = 14
+USER_FEMALE = 'Female'
+USER_MALE = 'Male'
+__author__ = 'Amr Hassan'
+__email__ = 'amr.hassan@gmail.com'
+__version__ = '0.3.0a'

+ + + + + +
 
+Author
       Amr Hassan
+ \ No newline at end of file