Sphinx documentation and API cleanup

diff --git a/sima/lib/http.py b/sima/lib/http.py
index 10fae9c475204852b73eabe039447d4d5d4497e4..8c6dab1bde94a1d9cea5d7fd74eaa13a133deb9d 100644 (file)
--- 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 de9f44fb7bd6afad2a25b0eede0e8534ee081946..ebf5026a7fa95dfce5eb0adc4472a1f33cb7e5ab 100644 (file)
--- 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=<str>[, 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=<str>[, 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': '<UUID4>',       # optional
+    >>>        'musicbrainz_albumartistid': '<UUID4>',  # 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': '<UUID4>',       # optional
-            >>>        'musicbrainz_albumartistid': '<UUID4>',  # 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 cfae27c675530b086a322c61b08fe85cbae7b945..7e0bda4f0fd48c5a5a430232b9607eeb5a6a1ea1 100644 (file)
--- 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 033556ef24728d2587b23dbeab840d9cab75260a..0f32f08b6bcbeb8c4190220b1df3be770c51d78e 100644 (file)
--- 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 a774a4ceafdceeb7ec7c0c5c57d819c20a35d378..b5ffc15545d0092303d51bc266d67e3adeb117ee 100644 (file)
--- 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]',