From bec6761572dc942c0772f955b6a84273e2754c6e Mon Sep 17 00:00:00 2001 From: kaliko Date: Wed, 11 Nov 2015 13:14:12 +0100 Subject: [PATCH] Sphinx documentation and API cleanup --- sima/lib/http.py | 6 ------ sima/lib/meta.py | 39 ++++++++++++++++++++++++++++----------- sima/lib/simaecho.py | 8 ++++++-- sima/lib/simafm.py | 10 ++++++++-- sima/lib/track.py | 12 ++++++------ 5 files changed, 48 insertions(+), 27 deletions(-) diff --git a/sima/lib/http.py b/sima/lib/http.py index 10fae9c..8c6dab1 100644 --- a/sima/lib/http.py +++ b/sima/lib/http.py @@ -190,12 +190,6 @@ class CacheController(object): # return the original handler return False - def add_headers(self, url): - resp = self.cache.get(url) - if resp and 'etag' in resp.headers: - return {'If-None-Match': resp.headers['etag']} - return {} - def cache_response(self, request, resp): """ Algorithm for caching requests. diff --git a/sima/lib/meta.py b/sima/lib/meta.py index de9f44f..ebf5026 100644 --- a/sima/lib/meta.py +++ b/sima/lib/meta.py @@ -59,11 +59,18 @@ def mbidfilter(func): class Meta: """Generic Class for Meta object - Meta(name=[, mbid=UUID4]) + + Using generic kwargs in constructor for convenience but the actual signature is: + + >>> Meta(name, mbid=None, **kwargs) + + :param string name: set name attribute + :param string mbid: set MusicBrainz ID (optional) """ use_mbid = True def __init__(self, **kwargs): + """Meta(name=[, mbid=UUID4])""" self.__name = None #TODO: should be immutable self.__mbid = None self.__aliases = set() @@ -136,25 +143,35 @@ class Meta: class Album(Meta): + """Album object""" @property def album(self): return self.name class Artist(Meta): + """Artist object deriving from :class:`Meta`. + + :param string name: Artist name, default ``None`` + :param string mbid: Musicbrainz artist ID, defautl ``None`` + :param string artist: Overrides "name" argument + :param string albumartist: Overrides "name" and "artist" argument + :param string musicbrainz_artistid: Overrides "mbid" argument + :param string musicbrainz_albumartistid: Overrides "musicbrainz_artistid" argument + + :Example: + + >>> trk = {'artist':'Art Name', + >>> 'albumartist': 'Alb Art Name', # optional + >>> 'musicbrainz_artistid': '', # optional + >>> 'musicbrainz_albumartistid': '', # optional + >>> } + >>> artobj0 = Artist(**trk) + >>> artobj1 = Artist(name='Tool') + """ @mbidfilter def __init__(self, name=None, mbid=None, **kwargs): - """Artist object built from a mapping dict containing at least an - "artist" entry: - >>> trk = {'artist':'Art Name', - >>> 'albumartist': 'Alb Art Name', # optional - >>> 'musicbrainz_artistid': '', # optional - >>> 'musicbrainz_albumartistid': '', # optional - >>> } - >>> artobj0 = Artist(**trk) - >>> artobj1 = Artist(name='Tool') - """ if kwargs.get('artist', False): name = kwargs.get('artist').split(SEPARATOR)[0] if kwargs.get('musicbrainz_artistid', False): diff --git a/sima/lib/simaecho.py b/sima/lib/simaecho.py index cfae27c..7e0bda4 100644 --- a/sima/lib/simaecho.py +++ b/sima/lib/simaecho.py @@ -94,8 +94,10 @@ class SimaEch: # return a sorted list of 2-tuple to have consistent cache return sorted(payload.items(), key=lambda param: param[0]) - def get_similar(self, artist=None): + def get_similar(self, artist): """Fetch similar artists + + param: artist Artist: Artist object to get similarities from """ payload = self._forge_payload(artist) # Construct URL @@ -106,8 +108,10 @@ class SimaEch: mbid = get_mbid(art) yield Artist(mbid=mbid, name=art.get('name')) - def get_toptrack(self, artist=None): + def get_toptrack(self, artist): """Fetch artist top tracks + + param: artist Artist: Artist object to get top tracks from """ payload = self._forge_payload(artist, top=True) # Construct URL diff --git a/sima/lib/simafm.py b/sima/lib/simafm.py index 033556e..0f32f08 100644 --- a/sima/lib/simafm.py +++ b/sima/lib/simafm.py @@ -87,8 +87,11 @@ class SimaFM: # return a sorted list of 2-tuple to have consistent cache return sorted(payload.items(), key=lambda param: param[0]) - def get_similar(self, artist=None): + def get_similar(self, artist): """Fetch similar artists + + :param Artist artist: :class:`Artist` to fetch similar artists from + :returns: generator of :class:`sima.lib.meta.Artist` """ payload = self._forge_payload(artist) # Construct URL @@ -106,8 +109,11 @@ class SimaFM: for art in ans.json().get('similarartists').get('artist'): # pylint: disable=no-member yield Artist(name=art.get('name'), mbid=art.get('mbid', None)) - def get_toptrack(self, artist=None): + def get_toptrack(self, artist): """Fetch artist top tracks + + :param Artist artist: :class:`Artist` to fetch top tracks from + :returns: generator of :class:`sima.lib.track.Track` """ payload = self._forge_payload(artist, method='top') ans = self.http(self.root_url, payload) diff --git a/sima/lib/track.py b/sima/lib/track.py index a774a4c..b5ffc15 100644 --- a/sima/lib/track.py +++ b/sima/lib/track.py @@ -28,7 +28,7 @@ from .meta import Artist, SEPARATOR class Track: """ Track object. - Instanciate with Player replies. + Instantiate with Player replies. """ def __init__(self, file=None, time=0, pos=-1, **kwargs): @@ -48,9 +48,9 @@ class Track: # have tags been collapsed? self.collapsed_tags = list() # Needed for multiple tags which returns a list instead of a string - self.collapse_tags() + self._collapse_tags() - def collapse_tags(self): + def _collapse_tags(self): """ Necessary to deal with tags defined multiple times. These entries are set as lists instead of strings. @@ -116,11 +116,11 @@ class Track: """set time property""" self._time = int(value) - time = property(get_time, set_time, doc='song duration in seconds') + time = property(get_time, set_time, doc='song duration in seconds (use :attr:`duration` for human readable time)') @property def duration(self): - """Compute fancy duration""" + """Get a fancy duration %H:%M:%S (use :attr:`time` to get duration in second only)""" temps = time.gmtime(int(self.time)) if temps.tm_hour: fmt = '%H:%M:%S' @@ -130,7 +130,7 @@ class Track: @property def Artist(self): - """Get artist object from track""" + """Get the :class:`sima.lib.meta.Artist` associated to this track""" if not self.artist: if not self.musicbrainz_artistid: return Artist(name='[unknown]', -- 2.39.2