Sphinx documentation and API cleanup

[mpd-sima.git] / sima / lib / track.py

diff --git a/sima/lib/track.py b/sima/lib/track.py
index 4a2e72001b1d44f47d9794afc03f52dda7be884c..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.


@@ -99,6 +99,8 @@ class Track:
         return hash(self) != hash(other)
 
     def __bool__(self):
         return hash(self) != hash(other)
 
     def __bool__(self):

+        if not self._file:
+            return False

         return not self._empty
 
     @property
         return not self._empty
 
     @property


@@ -114,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'


@@ -128,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]',