]> kaliko git repositories - mpd-sima.git/blob - sima/lib/player.py
Aesthetics changes
[mpd-sima.git] / sima / lib / player.py
1 # -*- coding: utf-8 -*-
2 # Copyright (c) 2009-2014 Jack Kaliko <jack@azylum.org>
3 #
4 #  This file is part of sima
5 #
6 #  sima is free software: you can redistribute it and/or modify
7 #  it under the terms of the GNU General Public License as published by
8 #  the Free Software Foundation, either version 3 of the License, or
9 #  (at your option) any later version.
10 #
11 #  sima is distributed in the hope that it will be useful,
12 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
13 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 #  GNU General Public License for more details.
15 #
16 #  You should have received a copy of the GNU General Public License
17 #  along with sima.  If not, see <http://www.gnu.org/licenses/>.
18 #
19 #
20
21 # TODO:
22 # Add decorator to filter through history?
23
24 # standard library import
25 import logging
26
27 # local import
28 #from sima.lib.track import Track
29
30
31 class Player(object):
32     """Player interface to inherit from.
33
34     When querying player music library for tracks, Player instance *must* return
35     Track objects (usually a list of them)
36
37     Player instance should expose the following immutable attributes:
38         * artists
39         * state
40         * current
41         * queue
42         * playlist
43         *
44     """
45
46     def __init__(self):
47         super().__init__()
48         self.log = logging.getLogger('sima')
49
50     def monitor(self):
51         """Monitor player for change
52         Returns :
53             * database  player media library has changed
54             * playlist  playlist modified
55             * options   player options changed: repeat mode, etc…
56             * player    player state changed: paused, stopped, skip track…
57         """
58         raise NotImplementedError
59
60     def clean(self):
61         """Any cleanup necessary"""
62         pass
63
64     def remove(self, position=0):
65         """Removes the oldest element of the playlist (index 0)
66         """
67         raise NotImplementedError
68
69     def find_track(self, artist, title=None):
70         """
71         Find tracks for a specific artist or filtering with a track title
72             >>> player.find_track('The Beatles')
73             >>> player.find_track('Nirvana', title='Smells Like Teen Spirit')
74
75         Returns a list of Track objects
76         """
77         raise NotImplementedError
78
79     def find_album(self, artist, album):
80         """
81         Find tracks by track's album name
82             >>> player.find_album('Nirvana', 'Nevermind')
83
84         Returns a list of Track objects
85         """
86         raise NotImplementedError
87
88     def find_albums(self, artist):
89         """
90         Find albums by artist's name
91             >>> player.find_alums('Nirvana')
92
93         Returns a list of string objects
94         """
95         raise NotImplementedError
96
97     def fuzzy_find_artist(self, artist):
98         """
99         Find artists based on a fuzzy search in the media library
100             >>> bea = player.fuzzy_find_artist('beatles')
101             >>> print(bea)
102             >>> ['The Beatles']
103
104         Returns a list of strings (artist names)
105         """
106         raise NotImplementedError
107
108     def disconnect(self):
109         """Closing client connection with the Player
110         """
111         raise NotImplementedError
112
113     def connect(self):
114         """Connect client to the Player
115         """
116         raise NotImplementedError
117
118 # VIM MODLINE
119 # vim: ai ts=4 sw=4 sts=4 expandtab