Releasing 0.12.3

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

diff --git a/sima/lib/player.py b/sima/lib/player.py
index 9f2910d048548bd3a1544b1c6ef4a85a7242b269..ea57255f4713c6a6026c78ec11de625839ea31c1 100644 (file)
--- a/sima/lib/player.py
+++ b/sima/lib/player.py
@@ -1,23 +1,48 @@
 # -*- coding: utf-8 -*-
+# Copyright (c) 2009-2014 Jack Kaliko <jack@azylum.org>
+#
+#  This file is part of sima
+#
+#  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.
+#
+#  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 sima.  If not, see <http://www.gnu.org/licenses/>.
+#
+#
 
 # TODO:
 # Add decorator to filter through history?
 
-# local import
-#from sima.lib.track import Track
+# standard library import
+import logging
 
 
 class Player(object):
-
     """Player interface to inherit from.
 
     When querying player music library for tracks, Player instance *must* return
     Track objects (usually a list of them)
+
+    Player instance should expose the following immutable attributes:
+        * artists
+        * state
+        * current
+        * queue
+        * playlist
+        *
     """
 
     def __init__(self):
-        self.state = {}
-        self.current = {}
+        super().__init__()
+        self.log = logging.getLogger('sima')
 
     def monitor(self):
         """Monitor player for change
@@ -29,6 +54,10 @@ class Player(object):
         """
         raise NotImplementedError
 
+    def clean(self):
+        """Any cleanup necessary"""
+        pass
+
     def remove(self, position=0):
         """Removes the oldest element of the playlist (index 0)
         """
@@ -47,10 +76,31 @@ class Player(object):
     def find_album(self, artist, album):
         """
         Find tracks by track's album name
-            >>> player.find_track('Nirvana', 'Nevermind')
+            >>> player.find_album('Nirvana', 'Nevermind')
 
         Returns a list of Track objects
         """
+        raise NotImplementedError
+
+    def find_albums(self, artist):
+        """
+        Find albums by artist's name
+            >>> player.find_alums('Nirvana')
+
+        Returns a list of string objects
+        """
+        raise NotImplementedError
+
+    def fuzzy_find_artist(self, artist):
+        """
+        Find artists based on a fuzzy search in the media library
+            >>> bea = player.fuzzy_find_artist('beatles')
+            >>> print(bea)
+            >>> ['The Beatles']
+
+        Returns a list of strings (artist names)
+        """
+        raise NotImplementedError
 
     def disconnect(self):
         """Closing client connection with the Player
@@ -64,4 +114,3 @@ class Player(object):
 
 # VIM MODLINE
 # vim: ai ts=4 sw=4 sts=4 expandtab
-