From ca436f371ca79d8d782f1147b24a796bb12cccaa Mon Sep 17 00:00:00 2001 From: Abhinav Sarkar Date: Thu, 5 Mar 2009 04:37:02 +0000 Subject: [PATCH] added more documentation --- docs/class-tree.html | 2 +- docs/help.html | 2 +- docs/identifier-index.html | 2 +- docs/lastfm-module.html | 2 +- docs/lastfm-pysrc.html | 2 +- docs/lastfm.album-module.html | 2 +- docs/lastfm.album-pysrc.html | 494 ++++--- docs/lastfm.album.Album-class.html | 79 +- docs/lastfm.api-module.html | 2 +- docs/lastfm.api-pysrc.html | 1263 +++++++++-------- docs/lastfm.api.Api-class.html | 124 +- docs/lastfm.artist-module.html | 2 +- docs/lastfm.artist-pysrc.html | 2 +- docs/lastfm.artist.Artist-class.html | 2 +- docs/lastfm.base-module.html | 2 +- docs/lastfm.base-pysrc.html | 2 +- docs/lastfm.base.LastfmBase-class.html | 2 +- docs/lastfm.error-module.html | 2 +- docs/lastfm.error-pysrc.html | 2 +- ...error.AuthenticationFailedError-class.html | 2 +- ...lastfm.error.InvalidApiKeyError-class.html | 2 +- ...lastfm.error.InvalidFormatError-class.html | 2 +- ...lastfm.error.InvalidMethodError-class.html | 2 +- ...ror.InvalidMethodSignatureError-class.html | 2 +- ...fm.error.InvalidParametersError-class.html | 2 +- ...stfm.error.InvalidResourceError-class.html | 2 +- ...astfm.error.InvalidServiceError-class.html | 2 +- ...fm.error.InvalidSessionKeyError-class.html | 2 +- docs/lastfm.error.LastfmError-class.html | 2 +- ...stfm.error.OperationFailedError-class.html | 2 +- ...astfm.error.ServiceOfflineError-class.html | 2 +- ...stfm.error.SubscribersOnlyError-class.html | 2 +- .../lastfm.error.TokenExpiredError-class.html | 2 +- ...m.error.TokenNotAuthorizedError-class.html | 2 +- docs/lastfm.event-module.html | 2 +- docs/lastfm.event-pysrc.html | 2 +- docs/lastfm.event.Event-class.html | 2 +- docs/lastfm.filecache-module.html | 2 +- docs/lastfm.filecache-pysrc.html | 2 +- docs/lastfm.filecache.FileCache-class.html | 2 +- ...astfm.filecache._FileCacheError-class.html | 2 +- docs/lastfm.geo-module.html | 2 +- docs/lastfm.geo-pysrc.html | 2 +- docs/lastfm.geo.Country-class.html | 2 +- docs/lastfm.geo.Geo-class.html | 2 +- docs/lastfm.geo.Location-class.html | 2 +- docs/lastfm.group-module.html | 2 +- docs/lastfm.group-pysrc.html | 2 +- docs/lastfm.group.Group-class.html | 2 +- docs/lastfm.lazylist-module.html | 2 +- docs/lastfm.lazylist-pysrc.html | 2 +- docs/lastfm.lazylist.LazyList-class.html | 2 +- ...stfm.lazylist.RecursiveLazyList-class.html | 2 +- ...zylist.RecursiveLazyListFactory-class.html | 2 +- docs/lastfm.mixins-module.html | 2 +- docs/lastfm.mixins-pysrc.html | 2 +- docs/lastfm.mixins.cacheable-module.html | 2 +- docs/lastfm.mixins.cacheable-pysrc.html | 2 +- ...stfm.mixins.cacheable.Cacheable-class.html | 2 +- docs/lastfm.mixins.searchable-module.html | 2 +- docs/lastfm.mixins.searchable-pysrc.html | 2 +- ...fm.mixins.searchable.Searchable-class.html | 2 +- docs/lastfm.mixins.sharable-module.html | 2 +- docs/lastfm.mixins.sharable-pysrc.html | 2 +- ...lastfm.mixins.sharable.Sharable-class.html | 2 +- docs/lastfm.mixins.shoutable-module.html | 2 +- docs/lastfm.mixins.shoutable-pysrc.html | 2 +- ...stfm.mixins.shoutable.Shoutable-class.html | 2 +- docs/lastfm.mixins.taggable-module.html | 2 +- docs/lastfm.mixins.taggable-pysrc.html | 2 +- ...lastfm.mixins.taggable.Taggable-class.html | 2 +- docs/lastfm.objectcache-module.html | 2 +- docs/lastfm.objectcache-pysrc.html | 2 +- .../lastfm.objectcache.ObjectCache-class.html | 2 +- docs/lastfm.playlist-module.html | 2 +- docs/lastfm.playlist-pysrc.html | 2 +- docs/lastfm.playlist.Playlist-class.html | 2 +- docs/lastfm.safelist-module.html | 2 +- docs/lastfm.safelist-pysrc.html | 2 +- docs/lastfm.safelist.SafeList-class.html | 2 +- docs/lastfm.shout-module.html | 2 +- docs/lastfm.shout-pysrc.html | 2 +- docs/lastfm.shout.Shout-class.html | 2 +- docs/lastfm.stats-module.html | 2 +- docs/lastfm.stats-pysrc.html | 2 +- docs/lastfm.stats.Stats-class.html | 2 +- docs/lastfm.tag-module.html | 2 +- docs/lastfm.tag-pysrc.html | 2 +- docs/lastfm.tag.Tag-class.html | 2 +- docs/lastfm.tasteometer-module.html | 2 +- docs/lastfm.tasteometer-pysrc.html | 2 +- .../lastfm.tasteometer.Tasteometer-class.html | 2 +- docs/lastfm.track-module.html | 2 +- docs/lastfm.track-pysrc.html | 2 +- docs/lastfm.track.Track-class.html | 2 +- docs/lastfm.user-module.html | 2 +- docs/lastfm.user-pysrc.html | 2 +- docs/lastfm.user.User-class.html | 2 +- docs/lastfm.user.User.Library-class.html | 2 +- docs/lastfm.user.User.Playlist-class.html | 2 +- docs/lastfm.venue-module.html | 2 +- docs/lastfm.venue-pysrc.html | 2 +- docs/lastfm.venue.Venue-class.html | 2 +- docs/lastfm.weeklychart-module.html | 2 +- docs/lastfm.weeklychart-pysrc.html | 2 +- ...fm.weeklychart.WeeklyAlbumChart-class.html | 2 +- ...m.weeklychart.WeeklyArtistChart-class.html | 2 +- .../lastfm.weeklychart.WeeklyChart-class.html | 2 +- ...stfm.weeklychart.WeeklyTagChart-class.html | 2 +- ...fm.weeklychart.WeeklyTrackChart-class.html | 2 +- docs/lastfm.wiki-module.html | 2 +- docs/lastfm.wiki-pysrc.html | 2 +- docs/lastfm.wiki.Wiki-class.html | 2 +- docs/module-tree.html | 2 +- lastfm/album.py | 82 +- lastfm/api.py | 113 +- 116 files changed, 1259 insertions(+), 1116 deletions(-) diff --git a/docs/class-tree.html b/docs/class-tree.html index bd71e31..4012e41 100644 --- a/docs/class-tree.html +++ b/docs/class-tree.html @@ -360,7 +360,7 @@
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:21 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:24 2009
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:21 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:24 2009
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:21 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:24 2009
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:21 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:24 2009
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:24 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:28 2009
- Generated by Epydoc 3.0.1 on Thu Mar 05 01:36:21 2009 + Generated by Epydoc 3.0.1 on Thu Mar 05 10:03:24 2009 28 @param api: an instance of L{Api} 29 @type api: L{Api} 30 @param name: the album name - 31 @type name: str + 31 @type name: L{str} 32 @param artist: the album artist name 33 @type artist: L{Artist} 34 @param id: the album ID - 35 @type id: str + 35 @type id: L{str} 36 @param mbid: MBID of the album - 37 @type mbid: str + 37 @type mbid: L{str} 38 @param url: URL of the album on last.fm - 39 @type url: str + 39 @type url: L{str} 40 @param release_date: release date of the album - 41 @type release_date: datetime.datetime + 41 @type release_date: C{datetime.datetime} 42 @param image: the cover images of the album in various sizes - 43 @type image: dict + 43 @type image: L{dict} 44 @param stats: the album statistics 45 @type stats: L{Stats} 46 @param top_tags: top tags of the album - 47 @type top_tags: list of L{Tag} + 47 @type top_tags: L{list} of L{Tag} 48 @param streamable: flag indicating if the album is streamable - 49 @type streamable: bool + 49 @type streamable: L{bool} 50 51 @raise InvalidParametersError: If an instance of L{Api} is not provided as the first 52 parameter then an Exception is raised. @@ -226,78 +226,108 @@ lastfm.track.Track.streamable" class="py-name" href="#" onclick="return doclink( 74 75 @property
76 - def name(self): -
77 """name of the album""" - 78 return self._name -
79 - 80 @property -
81 - def artist(self): -
82 """artist of the album""" - 83 return self._artist -
84 - 85 @property -
86 - def id(self): -
87 """id of the album""" - 88 if self._id is None: - 89 self.
77 """ + 78 name of the album + 79 @rtype: L{str} + 80 """ + 81 return self._name +
82 + 83 @property +
84 - def artist(self): +
85 """ + 86 artist of the album + 87 @rtype: L{Artist} + 88 """ + 89 return self._artist +
90 + 91 @property +
92 - def id(self): +
93 """ + 94 id of the album + 95 @rtype: L{int} + 96 """ + 97 if self._id is None: + 98 self._fill_info() - 90 return self._id -
91 - 92 @property -
93 - def mbid(self): -
94 """mbid of the album""" - 95 if self._mbid is None: - 96 self. 99 return self._id +
100 +101 @property +
102 - def mbid(self): +
103 """ +104 mbid of the album +105 @rtype: L{str} +106 """ +107 if self._mbid is None: +108 self._fill_info() - 97 return self._mbid -
98 - 99 @property -
100 - def url(self): -
101 """url of the album's page""" -102 if self._url is None: -103 self.109 return self._mbid +
110 +111 @property +
112 - def url(self): +
113 """ +114 url of the album's page +115 @rtype: L{str} +116 """ +117 if self._url is None: +118 self._fill_info() -104 return self._url -
105 -106 @property -
107 - def release_date(self): -
108 """release date of the album""" -109 if self._release_date is None: -110 self.119 return self._url +
120 +121 @property +
122 - def release_date(self): +
123 """ +124 release date of the album +125 @rtype: C{datetime.datetime} +126 """ +127 if self._release_date is None: +128 self._fill_info() -111 return self._release_date -
112 -113 @property -
114 - def image(self): -
115 """cover images of the album""" -116 if self._image is None: -117 self.129 return self._release_date +
130 +131 @property +
132 - def image(self): +
133 """ +134 cover images of the album +135 @rtype: L{dict} +136 """ +137 if self._image is None: +138 self._fill_info() -118 return self._image -
119 -120 @property -
121 - def stats(self): -
122 """stats related to the album""" -123 if self._stats is None: -124 self.139 return self._image +
140 +141 @property +
142 - def stats(self): +
143 """ +144 stats related to the album +145 @rtype: L{Stats} +146 """ +147 if self._stats is None: +148 self._fill_info() -125 return self._stats -
126 -127 @property -
128 - def streamable(self): -
129 """is the album streamable""" -130 return self._streamable -
131 -132 @LastfmBase.cached_property -
133 - def top_tags(self): -
134 """top tags for the album""" -135 params = {'method': 'album.getInfo'} -136 if self.149 return self._stats +
150 +151 @property +
152 - def streamable(self): +
153 """ +154 is the album streamable +155 @rtype: L{bool} +156 """ +157 return self._streamable +
158 +159 @LastfmBase.cached_property +
160 - def top_tags(self): +
161 """ +162 top tags for the album +163 @rtype: L{list} of L{Tag} +164 """ +165 params = {'method': 'album.getInfo'} +166 if self.artist and self.name: -137 params.update({'artist': self.167 params.update({'artist': self.artist.name}) -138 elif self.168 elif self.mbid: -139 params.update({'mbid': self.169 params.update({'mbid': self.mbid}) -140 data = self._api.170 data = self._api._fetch_data(params).find('album') -141 return [ -142 Tag( -143 self._api, -144 171 return [ +172 Tag( +173 self._api, +174 subject = self, -145 175 name = t.findtext('name'), -146 176 url = t.findtext('url') -147 ) -148 for t in data.findall('toptags/tag') -149 ] -
150 -151 @LastfmBase.top_property("top_tags") -
152 - def top_tag(self): -
153 """top tag for the album""" -154 pass -
155 -156 @LastfmBase.cached_property -
157 - def playlist(self): -
158 """playlist for the album""" -159 return 177 ) +178 for t in data.findall('toptags/tag') +179 ] +
180 +181 @LastfmBase.top_property("top_tags") +
182 - def top_tag(self): +
183 """ +184 top tag for the album +185 @rtype: L{Tag} +186 """ +187 pass +
188 +189 @LastfmBase.cached_property +
190 - def playlist(self): +
191 """ +192 playlist for the album +193 @rtype: L{Playlist} +194 """ +195 return Playlist.fetch(self._api, "lastfm://playlist/album/%s" % self.id) -
160 -161 @staticmethod -
162 - def get_info(api, -163 artist = None, -164 album = None, -165 mbid = None): -
166 """ -167 Get the data for the album. -168 -169 @param api: an instance of L{Api} -170 @type api: L{Api} -171 @param artist: the album artist name -172 @type artist: str OR L{Artist} -173 @param album: the album name -174 @type album: str -175 @param mbid: MBID of the album -176 @type mbid: str -177 -178 @return: an Album object corresponding the provided album name -179 @rtype: L{Album} -180 -181 @raise lastfm.InvalidParametersError: Either album and artist parameters or -182 mbid parameter has to be provided. -183 Otherwise exception is raised. -184 -185 @note: Use the L{Api.get_album} method instead of using this method directly. -186 """ -187 data = Album.196 +197 @staticmethod +
198 - def get_info(api, +199 artist = None, +200 album = None, +201 mbid = None): +
202 """ +203 Get the data for the album. +204 +205 @param api: an instance of L{Api} +206 @type api: L{Api} +207 @param artist: the album artist name +208 @type artist: L{str} OR L{Artist} +209 @param album: the album name +210 @type album: L{str} +211 @param mbid: MBID of the album +212 @type mbid: L{str} +213 +214 @return: an Album object corresponding the provided album name +215 @rtype: L{Album} +216 +217 @raise lastfm.InvalidParametersError: Either album and artist parameters or +218 mbid parameter has to be provided. +219 Otherwise exception is raised. +220 +221 @note: Use the L{Api.get_album} method instead of using this method directly. +222 """ +223 data = Album._fetch_data(api, album, mbid) -188 a = Album( -189 api, -190 224 a = Album( +225 api, +226 name = data.findtext('name'), -191 227 artist = Artist( -192 api, -193 228 api, +229 name = data.findtext('artist'), -194 ), -195 ) -196 a.230 ), +231 ) +232 a._fill_info() -197 return a -
198 -
199 - def _default_params(self, extra_params = {}): -
200 if not (self.233 return a +
234 +
235 - def _default_params(self, extra_params = {}): +
236 if not (self.artist and self.name): -201 raise InvalidParametersError("artist and album have to be provided.") -202 params = {'artist': self.237 raise InvalidParametersError("artist and album have to be provided.") +238 params = {'artist': self.artist.name} -203 params.update(extra_params) -204 return params -
205 -206 @staticmethod -
207 - def _fetch_data(api, -208 artist = None, -209 album = None, -210 mbid = None): -
211 params = {'method': 'album.getInfo'} -212 if not ((239 params.update(extra_params) +240 return params +
241 +242 @staticmethod +
243 - def _fetch_data(api, +244 artist = None, +245 album = None, +246 mbid = None): +
247 params = {'method': 'album.getInfo'} +248 if not ((artist and album) or mbid): -213 raise InvalidParametersError("either (artist and album) or mbid has to be given as argument.") -214 if 249 raise InvalidParametersError("either (artist and album) or mbid has to be given as argument.") +250 if artist and album: -215 params.update({'artist': 251 params.update({'artist': artist, 'album': album}) -216 elif 252 elif mbid: -217 params.update({'mbid': 253 params.update({'mbid': mbid}) -218 return api.254 return api._fetch_data(params).find('album') -
219 -
220 - def _fill_info(self): -
221 data = Album.255 +
256 - def _fill_info(self): +
257 data = Album._fetch_data(self._api, self.name) -222 self._id = int(data.findtext('id')) -223 self._mbid = data.findtext('mbid') -224 self._url = data.findtext('url') -225 self._release_date = data.findtext('releasedate') and data.findtext('releasedate').strip() and \ -226 datetime(*(time.strptime(data.findtext('releasedate').strip(), '%d %b %Y, 00:00')[0:6])) -227 self._image = dict([(i.get('size'), i.text) for i in data.findall('image')]) -228 if not self._stats: -229 self._stats = Stats( -230 258 self._id = int(data.findtext('id')) +259 self._mbid = data.findtext('mbid') +260 self._url = data.findtext('url') +261 self._release_date = data.findtext('releasedate') and data.findtext('releasedate').strip() and \ +262 datetime(*(time.strptime(data.findtext('releasedate').strip(), '%d %b %Y, 00:00')[0:6])) +263 self._image = dict([(i.get('size'), i.text) for i in data.findall('image')]) +264 if not self._stats: +265 self._stats = Stats( +266 subject = self, -231 listeners = int(data.findtext('listeners')), -232 playcount = int(data.findtext('playcount')), -233 ) -234 self._top_tags = [ -235 Tag( -236 self._api, -237 267 listeners = int(data.findtext('listeners')), +268 playcount = int(data.findtext('playcount')), +269 ) +270 self._top_tags = [ +271 Tag( +272 self._api, +273 subject = self, -238 274 name = t.findtext('name'), -239 275 url = t.findtext('url') -240 ) -241 for t in data.findall('toptags/tag') -242 ] -
243 -244 @staticmethod -
245 - def _search_yield_func(api, album): -
246 return Album( -247 api, -248 276 ) +277 for t in data.findall('toptags/tag') +278 ] +
279 +280 @staticmethod +
281 - def _search_yield_func(api, album): +
282 return Album( +283 api, +284 name = album.findtext('name'), -249 285 artist = Artist( -250 api, -251 286 api, +287 name = album.findtext('artist') -252 ), -253 288 ), +289 id = int(album.findtext('id')), -254 290 url = album.findtext('url'), -255 291 image = dict([(i.get('size'), i.text) for i in album.findall('image')]), -256 292 streamable = (album.findtext('streamable') == '1'), -257 ) -
258 -259 @staticmethod -
260 - def _hash_func(*args, **kwds): -
261 try: -262 return hash("%s%s" % (kwds['name'], hash(kwds['artist']))) -263 except KeyError: -264 raise InvalidParametersError("name and artist have to be provided for hashing") -
265 -
266 - def __hash__(self): -
267 return self.__class__.293 ) +
294 +295 @staticmethod +
296 - def _hash_func(*args, **kwds): +
297 try: +298 return hash("%s%s" % (kwds['name'], hash(kwds['artist']))) +299 except KeyError: +300 raise InvalidParametersError("name and artist have to be provided for hashing") +
301 +
302 - def __hash__(self): +
303 return self.__class__.artist = self.artist) -
268 -
269 - def __eq__(self, other): -
270 if self.304 +
305 - def __eq__(self, other): +
306 if self.id: -271 return self.307 return self.id -272 if self.308 if self.mbid and other.mbid: -273 return self.309 return self.mbid == other.mbid -274 if self.310 if self.url: -275 return self.311 return self.url -276 if (self.312 if (self.name and other.artist): -277 return (self.313 return (self.artist == other.artist) -278 return super(Album, self).314 return super(Album, self).__eq__(other) -
279 -
280 - def __lt__(self, other): -
281 return self.315 +
316 - def __lt__(self, other): +
317 return self.name -
282 -
283 - def __repr__(self): -
284 return "<lastfm.Album: '%s' by %s>" % (self.318 +
319 - def __repr__(self): +
320 return "<lastfm.Album: '%s' by %s>" % (self.name) -
285 -286 -287 from datetime import datetime -288 import time -289 -290 from lastfm.api import Api -291 from lastfm.321 +322 +323 from datetime import datetime +324 import time +325 +326 from lastfm.api import Api +327 from lastfm.artist import Artist -292 from lastfm.error import InvalidParametersError -293 from lastfm.328 from lastfm.error import InvalidParametersError +329 from lastfm.playlist import Playlist -294 from lastfm.330 from lastfm.stats import Stats -295 from lastfm.331 from lastfm.tag import Tag -296