Python docs for PlaylistItem

src/scripting/python/player.sip

@@ -1,4 +1,4 @@
-class PlayerInterface : QObject {
+class PlayerInterface : QObject /PyName=Player/ {
 
 %TypeHeaderCode
 #include "core/player.h"

src/scripting/python/playlistitem.sip

@@ -13,10 +13,49 @@ class PlaylistItem {
   #include "scripting/python/sharedpointermanager.h"
 %End
 
-public:
-  static PlaylistItem* NewFromType(const QString& type);
-  static PlaylistItem* NewFromSongsTable(const QString& table, const Song& song);
+%Docstring
+Represents a single row in a playlist.
 
+Playlists in Clementine are lists of PlaylistItems.  At a minimum each
+PlaylistItem contains some metadata and a URL, but items may also have special
+loading behaviour associated with them if playing the item is more complicated
+than just loading a URL (for example, Last.fm stations have to request a
+special playlist using the Last.fm API).
+
+PlaylistItem is an abstract class and instances of it cannot be created
+directly by Python code.  If you want to add items to a playlist you should use
+the C{Insert...} methods in L{Playlist}, such as
+L{Playlist.InsertSongsOrLibraryItems()}.
+
+You can get individual PlaylistItems from a L{Playlist} using
+L{Playlist.item_at()}.  Get the PlaylistItem that is currently playing (in any
+playlist) using L{Player.GetCurrentItem()}.  These functions are marked as
+returning L{PlaylistItemPtr}s, because in C++ the playlist items are held
+inside and managed by smart pointers.  This doesn't affect Python at all
+however - you can use a PlaylistItemPtr in just the same way as you would a
+PlaylistItem.
+
+  >>> item = clementine.player.GetCurrentItem()
+  ... print item.Metadata().title()
+
+The L{options()} field of a PlaylistItem is an ORed combination of flags that
+describe the item's behaviour when it is played.  Valid values are:
+
+  - C{Default} - no special behaviour, the L{Url()} is used directly when
+    playing the song.
+  - C{SpecialPlayBehaviour} - The URL returned by Url() isn't the actual URL of
+    the music - the item needs to do something special before it can get an
+    actual URL.  Causes StartLoading() to get called when the user wants to
+    play.
+  - C{ContainsMultipleTracks} - this item might be able to provide another
+    track after one finishes, for example in a radio stream.  Causes LoadNext()
+    to get called when the next URL is required.
+  - C{PauseDisabled} - disables the "pause" action.
+  - C{LastFMControls} - enables the last.fm "ban" action.
+
+%End
+
+public:
   enum Option {
     Default,
     SpecialPlayBehaviour,
@@ -27,6 +66,22 @@ public:
   typedef QFlags<PlaylistItem::Option> Options;
 
   struct SpecialLoadResult {
+%Docstring
+Returned by StartLoading() and LoadNext(), indicates what the player should do
+when it wants to load a playlist item that is marked SpecialPlayBehaviour or
+ContainsMultipleTracks.
+
+Valid values for the type_ field are:
+
+  - C{NoMoreTracks} - there wasn't a track available, and the player should
+    move on to the next playlist item.
+  - C{WillLoadAsynchronously} - there might be another track available,
+    something will call the player's HandleSpecialLoad() slot later with the
+    same original_url.
+  - C{TrackAvailable} - There was a track available.  Its url is in media_url.
+
+%End
+
     enum Type {
       NoMoreTracks,
       WillLoadAsynchronously,
@@ -44,22 +99,87 @@ public:
   };
 
   QString type() const;
+%Docstring
+type() -> str
+Returns a string describing the subclass of PlaylistItem that this item really
+is.  This string is stored in the database so the correct subclass can be
+recreated again when the playlist is loaded.  Values include:
+
+  - C{Library}
+  - C{File}
+  - C{Stream}
+  - C{Jamendo}
+  - C{Magnatune}
+  - C{Radio}
+%End
+
   Options options() const;
+%Docstring
+options() -> L{Options}
+Returns the options set on this item.
+
+@return: An ORed combination of L{Option}s.
+%End
 
   void Reload();
+%Docstring
+Reload()
+If this item is backed by a file, re-reads the metadata from the file and
+updates the row in the playlist.
+
+@warning: This method is B{blocking} and runs on the GUI thread.  It is better
+  to call L{BackgroundReload()} which runs in a separate thread.
+%End
+
   void BackgroundReload();
+%Docstring
+BackgroundReload()
+Like L{Reload()}, but runs in a background thread.
+%End
 
   Song Metadata() const;
+%Docstring
+Metadata() -> L{Song}
+Returns this item's metadata.
+%End
+
   QUrl Url() const;
+%Docstring
+Url() -> L{PyQt4.QtCore.QUrl}
+Returns the URL that contains this item's media.  This is usually derived from
+C{Metadata().filename()}.
+%End
 
   void SetTemporaryMetadata(const Song& metadata);
-  void ClearTemporaryMetadata();
-  bool HasTemporaryMetadata() const;
+%Docstring
+SetTemporaryMetadata(metadata)
+Sets some metadata on the item that will override that returned from
+L{Metadata()} while the song is playing, and until L{ClearTemporaryMetadata()}
+is called.  This is useful for radio streams where the actual metadata is not
+known until the stream is loaded.
 
-  void SetDynamicHistory(bool history);
-  bool IsDynamicHistory() const;
+@note: Some types of PlaylistItem may not allow you to override their metadata.
+@type metadata: L{Song}
+%End
+
+  void ClearTemporaryMetadata();
+%Docstring
+ClearTemporaryMetadata()
+Clears any metadata set by L{SetTemporaryMetadata()}.
+%End
+
+  bool HasTemporaryMetadata() const;
+%Docstring
+HasTemporaryMetadata() -> bool
+Returns true if L{SetTemporaryMetadata()} has been called.
+%End
 
   bool IsLocalLibraryItem() const;
+%Docstring
+IsLocalLibraryItem() -> bool
+Convenience function to check whether this item is from the local library (the
+list of songs appearing in the Library tab).
+%End
 
   ~PlaylistItem();
 %MethodCode

src/scripting/python/playlistmanager.sip

@@ -1,4 +1,4 @@
-class PlaylistManagerInterface : QObject {
+class PlaylistManagerInterface : QObject /PyName=PlaylistManager/ {
 
 %TypeHeaderCode
 #include "playlist/playlistmanager.h"