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

core: Update tracklist docstrings

Browse Source
This commit is contained in:
Stein Magnus Jodal 2012-11-16 11:40:09 +01:00
parent fff70c46a6
commit cbc08f398c
1 changed files with 21 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
mopidy/core/tracklist.py
View File

@ -33,7 +33,7 @@ class TracklistController(object):
@property @property
def tracks(self): def tracks(self):
""" """
List of :class:`mopidy.models.Track` in the current playlist. List of :class:`mopidy.models.Track` in the tracklist.
Read-only. Read-only.
""" """
@ -42,15 +42,15 @@ class TracklistController(object):
@property @property
def length(self): def length(self):
""" """
Length of the current playlist. Length of the tracklist.
""" """
return len(self._tl_tracks) return len(self._tl_tracks)
@property @property
def version(self): def version(self):
""" """
The current playlist version. Integer which is increased every time the The tracklist version. Integer which is increased every time the
current playlist is changed. Is not reset before Mopidy is restarted. tracklist is changed. Is not reset before Mopidy is restarted.
""" """
return self._version return self._version
@ -62,20 +62,19 @@ class TracklistController(object):
def add(self, track, at_position=None, increase_version=True): def add(self, track, at_position=None, increase_version=True):
""" """
Add the track to the end of, or at the given position in the current Add the track to the end of, or at the given position in the tracklist.
playlist.
:param track: track to add :param track: track to add
:type track: :class:`mopidy.models.Track` :type track: :class:`mopidy.models.Track`
:param at_position: position in current playlist to add track :param at_position: position in tracklist to add track
:type at_position: int or :class:`None` :type at_position: int or :class:`None`
:param increase_version: if the playlist version should be increased :param increase_version: if the tracklist version should be increased
:type increase_version: :class:`True` or :class:`False` :type increase_version: :class:`True` or :class:`False`
:rtype: two-tuple of (TLID integer, :class:`mopidy.models.Track`) that :rtype: two-tuple of (TLID integer, :class:`mopidy.models.Track`) that
was added to the current playlist playlist was added to the tracklist
""" """
assert at_position <= len(self._tl_tracks), \ assert at_position <= len(self._tl_tracks), \
'at_position can not be greater than playlist length' 'at_position can not be greater than tracklist length'
tl_track = TlTrack(self.tlid, track) tl_track = TlTrack(self.tlid, track)
if at_position is not None: if at_position is not None:
self._tl_tracks.insert(at_position, tl_track) self._tl_tracks.insert(at_position, tl_track)
@ -88,7 +87,7 @@ class TracklistController(object):
def append(self, tracks): def append(self, tracks):
""" """
Append the given tracks to the current playlist. Append the given tracks to the tracklist.
:param tracks: tracks to append :param tracks: tracks to append
:type tracks: list of :class:`mopidy.models.Track` :type tracks: list of :class:`mopidy.models.Track`
@ -104,20 +103,19 @@ class TracklistController(object):
return tl_tracks return tl_tracks
def clear(self): def clear(self):
"""Clear the current playlist.""" """Clear the tracklist."""
self._tl_tracks = [] self._tl_tracks = []
self.version += 1 self.version += 1
def get(self, **criteria): def get(self, **criteria):
""" """
Get track by given criterias from current playlist. Get track by given criterias from tracklist.
Raises :exc:`LookupError` if a unique match is not found. Raises :exc:`LookupError` if a unique match is not found.
Examples:: Examples::
get(tlid=7) # Returns track with TLID 7 get(tlid=7) # Returns track with TLID 7 (tracklist ID)
# (current playlist ID)
get(id=1) # Returns track with ID 1 get(id=1) # Returns track with ID 1
get(uri='xyz') # Returns track with URI 'xyz' get(uri='xyz') # Returns track with URI 'xyz'
get(id=1, uri='xyz') # Returns track with ID 1 and URI 'xyz' get(id=1, uri='xyz') # Returns track with ID 1 and URI 'xyz'
@ -145,7 +143,7 @@ class TracklistController(object):
def index(self, tl_track): def index(self, tl_track):
""" """
Get index of the given (TLID integer, :class:`mopidy.models.Track`) Get index of the given (TLID integer, :class:`mopidy.models.Track`)
two-tuple in the current playlist. two-tuple in the tracklist.
Raises :exc:`ValueError` if not found. Raises :exc:`ValueError` if not found.
@ -174,10 +172,10 @@ class TracklistController(object):
assert start < end, 'start must be smaller than end' assert start < end, 'start must be smaller than end'
assert start >= 0, 'start must be at least zero' assert start >= 0, 'start must be at least zero'
assert end <= len(tl_tracks), \ assert end <= len(tl_tracks), \
'end can not be larger than playlist length' 'end can not be larger than tracklist length'
assert to_position >= 0, 'to_position must be at least zero' assert to_position >= 0, 'to_position must be at least zero'
assert to_position <= len(tl_tracks), \ assert to_position <= len(tl_tracks), \
'to_position can not be larger than playlist length' 'to_position can not be larger than tracklist length'
new_tl_tracks = tl_tracks[:start] + tl_tracks[end:] new_tl_tracks = tl_tracks[:start] + tl_tracks[end:]
for tl_track in tl_tracks[start:end]: for tl_track in tl_tracks[start:end]:
@ -188,7 +186,7 @@ class TracklistController(object):
def remove(self, **criteria): def remove(self, **criteria):
""" """
Remove the track from the current playlist. Remove the track from the tracklist.
Uses :meth:`get()` to lookup the track to remove. Uses :meth:`get()` to lookup the track to remove.
@ -202,7 +200,7 @@ class TracklistController(object):
def shuffle(self, start=None, end=None): def shuffle(self, start=None, end=None):
""" """
Shuffles the entire playlist. If ``start`` and ``end`` is given only Shuffles the entire tracklist. If ``start`` and ``end`` is given only
shuffles the slice ``[start:end]``. shuffles the slice ``[start:end]``.
:param start: position of first track to shuffle :param start: position of first track to shuffle
@ -220,7 +218,7 @@ class TracklistController(object):
if end is not None: if end is not None:
assert end <= len(tl_tracks), 'end can not be larger than ' + \ assert end <= len(tl_tracks), 'end can not be larger than ' + \
'playlist length' 'tracklist length'
before = tl_tracks[:start or 0] before = tl_tracks[:start or 0]
shuffled = tl_tracks[start:end] shuffled = tl_tracks[start:end]
@ -231,8 +229,8 @@ class TracklistController(object):
def slice(self, start, end): def slice(self, start, end):
""" """
Returns a slice of the current playlist, limited by the given Returns a slice of the tracklist, limited by the given start and end
start and end positions. positions.
:param start: position of first track to include in slice :param start: position of first track to include in slice
:type start: int :type start: int