andpp/mopidy
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve backend API docs

Browse Source
This commit is contained in:
Stein Magnus Jodal 2010-05-03 22:54:34 +02:00
parent 39959a6edf
commit 8cedca11d3
2 changed files with 92 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/api/backends.rst
View File

@ -16,6 +16,9 @@ The backend and its controllers
Backend API
===========
.. automodule:: mopidy.backends
:synopsis: Backend interface.
.. note::
Currently this only documents the API that is available for use by
@ -26,8 +29,54 @@ Backend API
generally just implement or override a few of these methods yourself to
create a new backend with a complete feature set.
.. automodule:: mopidy.backends
:synopsis: Backend interface.
.. autoclass:: mopidy.backends.BaseBackend
:members:
:undoc-members:
Playback controller
-------------------
Manages playback, with actions like play, pause, stop, next, previous, and
seek.
.. autoclass:: mopidy.backends.BasePlaybackController
:members:
:undoc-members:
Mixer controller
----------------
Manages volume. See :class:`mopidy.mixers.BaseMixer`.
Current playlist controller
---------------------------
Manages everything related to the currently loaded playlist.
.. autoclass:: mopidy.backends.BaseCurrentPlaylistController
:members:
:undoc-members:
Stored playlists controller
---------------------------
Manages stored playlist.
.. autoclass:: mopidy.backends.BaseStoredPlaylistsController
:members:
:undoc-members:
Library controller
------------------
Manages the music library, e.g. searching for tracks to be added to a playlist.
.. autoclass:: mopidy.backends.BaseLibraryController
:members:
:undoc-members:

62
mopidy/backends/__init__.py
View File

@ -14,6 +14,15 @@ __all__ = ['BaseBackend', 'BasePlaybackController',
'BaseLibraryController']
class BaseBackend(object):
"""
:param core_queue: a queue for sending messages to
:class:`mopidy.process.CoreProcess`
:type core_queue: :class:`multiprocessing.Queue`
:param mixer: either a mixer instance, or :class:`None` to use the mixer
defined in settings
:type mixer: :class:`mopidy.mixers.BaseMixer` or :class:`None`
"""
def __init__(self, core_queue=None, mixer=None):
self.core_queue = core_queue
if mixer is not None:
@ -22,7 +31,8 @@ class BaseBackend(object):
self.mixer = get_class(settings.MIXER)()
#: A :class:`multiprocessing.Queue` which can be used by e.g. library
#: callbacks to send messages to the core.
#: callbacks executing in other threads to send messages to the core
#: thread, so that action may be taken in the correct thread.
core_queue = None
#: The current playlist controller. An instance of
@ -73,14 +83,17 @@ class BaseCurrentPlaylistController(object):
"""
#: The current playlist version. Integer which is increased every time the
#: current playlist is changed. Is not reset before the MPD server is
#: restarted.
#: current playlist is changed. Is not reset before Mopidy is restarted.
version = 0
def __init__(self, backend):
self.backend = backend
self._playlist = Playlist()
def destroy(self):
"""Cleanup after component."""
pass
@property
def playlist(self):
"""The currently loaded :class:`mopidy.models.Playlist`."""
@ -229,7 +242,7 @@ class BaseCurrentPlaylistController(object):
self.playlist = self.playlist.with_(tracks=before+shuffled+after)
def destroy(self):
"""Cleanup after component"""
"""Cleanup after component."""
pass
@ -242,6 +255,10 @@ class BaseLibraryController(object):
def __init__(self, backend):
self.backend = backend
def destroy(self):
"""Cleanup after component."""
pass
def find_exact(self, field, query):
"""
Find tracks in the library where ``field`` matches ``query`` exactly.
@ -285,10 +302,6 @@ class BaseLibraryController(object):
"""
raise NotImplementedError
def destroy(self):
"""Cleanup after component"""
pass
class BasePlaybackController(object):
"""
@ -321,9 +334,10 @@ class BasePlaybackController(object):
random = False
#: :class:`True`
#: The current track is played repeatedly.
#: The current playlist is played repeatedly. To repeat a single track,
#: select both :attr:`repeat` and :attr:`single`.
#: :class:`False`
#: The current track is played once.
#: The current playlist is played once.
repeat = False
#: :class:`True`
@ -340,6 +354,10 @@ class BasePlaybackController(object):
self._play_time_accumulated = 0
self._play_time_started = None
def destroy(self):
"""Cleanup after component."""
pass
@property
def current_playlist_position(self):
"""The position of the current track in the current playlist."""
@ -392,8 +410,9 @@ class BasePlaybackController(object):
"""
The previous :class:`mopidy.models.Track` in the playlist.
For normal playback this is the previous track in the playlist. If random
and/or consume is enabled it should return the current track instead.
For normal playback this is the previous track in the playlist. If
random and/or consume is enabled it should return the current track
instead.
"""
if self.repeat or self.consume or self.random:
return self.current_track
@ -478,7 +497,12 @@ class BasePlaybackController(object):
self.current_track = None
def new_playlist_loaded_callback(self):
"""Tell the playback controller that a new playlist has been loaded."""
"""
Tell the playback controller that a new playlist has been loaded.
Typically called by :class:`mopidy.process.CoreProcess` after a message
from a library thread is received.
"""
self.current_track = None
self._first_shuffle = True
self._shuffled = []
@ -601,10 +625,6 @@ class BasePlaybackController(object):
def _stop(self):
raise NotImplementedError
def destroy(self):
"""Cleanup after component"""
pass
class BaseStoredPlaylistsController(object):
"""
@ -616,6 +636,10 @@ class BaseStoredPlaylistsController(object):
self.backend = backend
self._playlists = []
def destroy(self):
"""Cleanup after component."""
pass
@property
def playlists(self):
"""List of :class:`mopidy.models.Playlist`."""
@ -716,7 +740,3 @@ class BaseStoredPlaylistsController(object):
:rtype: list of :class:`mopidy.models.Playlist`
"""
return filter(lambda p: query in p.name, self._playlists)
def destroy(self):
"""Cleanup after component"""
pass