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 93aa350bbc4d24d612e2232e8c7a8d1de19d0a90..b5ffc15545d0092303d51bc266d67e3adeb117ee 100644 (file)
--- a/sima/lib/track.py
+++ b/sima/lib/track.py
@@ -1,53 +1,56 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2009, 2010, 2011, 2013 Jack Kaliko <efrim@azylum.org>
+# Copyright (c) 2009, 2010, 2011, 2013, 2014, 2015 Jack Kaliko <kaliko@azylum.org>
 # Copyright (c) 2009 J. Alexander Treuman (Tag collapse method)
 # Copyright (c) 2008 Rick van Hattem
 #
-#  This file is part of MPD_sima
+#  This file is part of sima
 #
-#  MPD_sima is free software: you can redistribute it and/or modify
+#  sima is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
 #  the Free Software Foundation, either version 3 of the License, or
 #  (at your option) any later version.
 #
-#  MPD_sima is distributed in the hope that it will be useful,
+#  sima is distributed in the hope that it will be useful,
 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 #  GNU General Public License for more details.
 #
 #  You should have received a copy of the GNU General Public License
-#  along with MPD_sima.  If not, see <http://www.gnu.org/licenses/>.
+#  along with sima.  If not, see <http://www.gnu.org/licenses/>.
 #
 #
 
 import time
 
+from .meta import Artist, SEPARATOR
 
-class Track(object):
+class Track:
     """
     Track object.
-    Instanciate with mpd replies.
+    Instantiate with Player replies.
     """
 
-    def __init__(self, file=None, time=0, pos=0, **kwargs):
+    def __init__(self, file=None, time=0, pos=-1, **kwargs):
         self.title = self.artist = self.album = self.albumartist = ''
-        self._pos = pos
-        self.empty = False
+        self.musicbrainz_artistid = self.musicbrainz_albumartistid = None
+        self.pos = int(pos)
         self._file = file
+        self._empty = False
+        self._time = time
         if not kwargs:
-            self.empty = True
-        self.time = time
+            self._empty = True
         self.__dict__.update(**kwargs)
-        self.tags_to_collapse = list(['artist', 'album', 'title', 'date',
-            'genre', 'albumartist'])
+        self.tags_to_collapse = ['artist', 'album', 'title', 'date',
+                                 'genre', 'albumartist',
+                                 'musicbrainz_artistid',
+                                 'musicbrainz_albumartistid']
         #  have tags been collapsed?
-        self.collapse_tags_bool = False
         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.
@@ -56,18 +59,11 @@ class Track(object):
             if tag not in self.tags_to_collapse:
                 continue
             if isinstance(value, list):
-                self.collapse_tags_bool = True
                 self.collapsed_tags.append(tag)
-                self.__dict__.update({tag: ', '.join(set(value))})
-
-    def get_filename(self):
-        """return filename"""
-        if not self.file:
-            return None
-        return self.file
+                self.__dict__.update({tag: SEPARATOR.join(set(value))})
 
     def __repr__(self):
-        return '%s(artist="%s", album="%s", title="%s", filename="%s")' % (
+        return '%s(artist="%s", album="%s", title="%s", file="%s")' % (
             self.__class__.__name__,
             self.artist,
             self.album,
@@ -103,12 +99,9 @@ class Track(object):
         return hash(self) != hash(other)
 
     def __bool__(self):
-        return not self.empty
-
-    @property
-    def pos(self):
-        """return position of track in the playlist"""
-        return int(self._pos)
+        if not self._file:
+            return False
+        return not self._empty
 
     @property
     def file(self):
@@ -123,11 +116,11 @@ class Track(object):
         """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'
@@ -135,13 +128,15 @@ class Track(object):
             fmt = '%M:%S'
         return time.strftime(fmt, temps)
 
-
-def main():
-    pass
-
-# Script starts here
-if __name__ == '__main__':
-    main()
+    @property
+    def Artist(self):
+        """Get the :class:`sima.lib.meta.Artist` associated to this track"""
+        if not self.artist:
+            if not self.musicbrainz_artistid:
+                return Artist(name='[unknown]',
+                              mbid='125ec42a-7229-4250-afc5-e057484327fe')
+            return Artist(name='[unknown]', **self.__dict__)
+        return Artist(**self.__dict__)
 
 # VIM MODLINE
 # vim: ai ts=4 sw=4 sts=4 expandtab