Add BackendListener interface to be impl by any who wants events from the backend

docs/api/listeners.rst

@@ -0,0 +1,7 @@
+************
+Listener API
+************
+
+.. automodule:: mopidy.listeners
+    :synopsis: Listener API
+    :members:

docs/changes.rst

@@ -13,6 +13,9 @@ v0.6.0 (in development)
 - Replace :attr:`mopidy.backends.base.Backend.uri_handlers` with
   :attr:`mopidy.backends.base.Backend.uri_schemes`, which just takes the part
   up to the colon of an URI, and not any prefix.
+- Add Listener API, :mod:`mopidy.listeners`, to be implemented by actors
+  wanting to receive events from the backend. This is a formalization of the
+  ad hoc events the Last.fm scrobbler has already been using for some time.
 
 
 v0.5.0 (2011-06-15)

mopidy/listeners.py

@@ -0,0 +1,34 @@
+class BackendListener(object):
+    """
+    Marker interface for recipients of events sent by the backend.
+
+    Any Pykka actor that mixes in this class will receive calls to the methods
+    defined here when the corresponding events happen in the backend. This
+    interface is used both for looking up what actors to notify of the events,
+    and for providing default implementations for those listeners that are not
+    interested in all events.
+    """
+
+    def started_playing(self, track):
+        """
+        Called whenever a new track starts playing.
+
+        *MAY* be implemented by actor.
+
+        :param track: the track that just started playing
+        :type track: :class:`mopidy.models.Track`
+        """
+        pass
+
+    def stopped_playing(self, track, stop_position):
+        """
+        Called whenever playback is stopped.
+
+        *MAY* be implemented by actor.
+
+        :param track: the track that was played before playback stopped
+        :type track: :class:`mopidy.models.Track`
+        :param stop_position: the time position when stopped in milliseconds
+        :type stop_position: int
+        """
+        pass

tests/listeners_test.py

@@ -0,0 +1,14 @@
+import unittest
+
+from mopidy.listeners import BackendListener
+from mopidy.models import Track
+
+class BackendListenerTest(unittest.TestCase):
+    def setUp(self):
+        self.listener = BackendListener()
+
+    def test_listener_has_default_impl_for_the_started_playing_event(self):
+        self.listener.started_playing(Track())
+
+    def test_listener_has_default_impl_for_the_stopped_playing_event(self):
+        self.listener.stopped_playing(Track(), 0)