diff --git a/docs/api/listeners.rst b/docs/api/listeners.rst new file mode 100644 index 00000000..609dc3c7 --- /dev/null +++ b/docs/api/listeners.rst @@ -0,0 +1,7 @@ +************ +Listener API +************ + +.. automodule:: mopidy.listeners + :synopsis: Listener API + :members: diff --git a/docs/changes.rst b/docs/changes.rst index 2e5b6659..2347ddb0 100644 --- a/docs/changes.rst +++ b/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) diff --git a/mopidy/listeners.py b/mopidy/listeners.py new file mode 100644 index 00000000..f6d1c67e --- /dev/null +++ b/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 diff --git a/tests/listeners_test.py b/tests/listeners_test.py new file mode 100644 index 00000000..761aff4f --- /dev/null +++ b/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)