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
 
         # 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.
     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
 
 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):
     """
     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()
         self.__name = None #TODO: should be immutable
         self.__mbid = None
         self.__aliases = set()


@@ -136,25 +143,35 @@ class Meta:
 
 
 class Album(Meta):
 
 
 class Album(Meta):

+    """Album object"""

 
     @property
     def album(self):
         return self.name
 
 class Artist(Meta):
 
     @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):
 
     @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):
         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])
 
         # 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
         """Fetch similar artists

+
+        param: artist Artist: Artist object to get similarities from

         """
         payload = self._forge_payload(artist)
         # Construct URL
         """
         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'))
 
             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
         """Fetch artist top tracks

+
+        param: artist Artist: Artist object to get top tracks from

         """
         payload = self._forge_payload(artist, top=True)
         # Construct URL
         """
         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])
 
         # 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
         """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
         """
         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))
 
         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
         """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)
         """
         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.
 class Track:
     """
     Track object.

-    Instanciate with Player replies.
+    Instantiate with Player replies.

     """
 
     def __init__(self, file=None, time=0, pos=-1, **kwargs):
     """
 
     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
         #  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.
         """
         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)
 
         """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):
 
     @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'
         temps = time.gmtime(int(self.time))
         if temps.tm_hour:
             fmt = '%H:%M:%S'


@@ -130,7 +130,7 @@ class Track:
 
     @property
     def Artist(self):
 
     @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]',
         if not self.artist:
             if not self.musicbrainz_artistid:
                 return Artist(name='[unknown]',