Docs for TaskManager, Queue and PythonEngine

doc/python/epydoc.css

@@ -78,7 +78,8 @@ td.footer                   { font-size: 85%; }
  *   - Summary tables that contain user-defined groups mark those
  *     groups using 'group header' rows.
  */
-td.table-header             { font-weight: bold;
+td.table-header,
+th.group-header             { font-weight: bold;
                               text-align: left;
                               padding: 6px 12px;
                               border: 1px solid #BBB;
@@ -86,10 +87,6 @@ td.table-header             { font-weight: bold;
 td.table-header table       { color: #000000; }
 td.table-header table a:link      { color: #0000ff; }
 td.table-header table a:visited   { color: #204080; }
-th.group-header             { background: #c0e0f8; color: #000000;
-                              text-align: left; font-style: italic; 
-                              font-size: 115%; 
-                              border: 1px solid #608090; }
 
 /* Summary Tables (functions, variables, etc)
  *   - Each object is described by a single row of the table with

src/scripting/python/iconloader.sip

@@ -8,10 +8,10 @@ class IconLoader {
 Singleton class that loads icons from the system theme if possible, falling
 back on Clementine's builtin icons otherwise.
 
-You can access the IconLoader directly, there is no need to create an instance
+You can access the IconLoader methods directly, there is no need to create an
-of the class first.
+instance of the class first.
 
-    >>> clementine.IconLoader.Load("media-pause")
+  >>> clementine.IconLoader.Load("media-pause")
 
 Icons are identified by their name without any extension, and they follow the
 U{Freedesktop icon naming specification<http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html#names>}.

src/scripting/python/pythonengine.sip

@@ -4,8 +4,38 @@ class PythonEngine {
 #include "scripting/python/pythonengine.h"
 %End
 
+%Docstring
+Helper functions for communicating with Clementine's Python interface.
+
+This is a singleton class, you can access its methods directly through the
+C{clementine.pythonengine} object:
+
+  >>> clementine.pythonengine.AddLogLine("Everything is ok")
+%End
+
 public:
   void AddLogLine(const QString& message, bool error = false);
+%Docstring
+AddLogLine(message, error=false)
+Writes a line to the Clementine script console.
+
+Note that sys.stdout and sys.stderr are already redirected to the script
+console, so you will not normally need to call this function.  Instead you can
+use C{print} directly::
+
+  # These lines are equivalent
+  print "Everything is ok"
+  clementine.pythonengine.AddLogLine("Everything is ok")
+
+  # These lines are equivalent
+  print >>sys.stderr, "Everything is wrong"
+  clementine.pythonengine.AddLogLine("Everything is wrong", error=True)
+
+@param message: A line to write to the log.
+@type message: str
+@param error: If this is True then the message will appear in red.
+@type error: bool
+%End
 
 private:
   PythonEngine();

src/scripting/python/queue.sip

@@ -4,22 +4,124 @@ struct Queue : QAbstractProxyModel {
 #include "playlist/queue.h"
 %End
 
-public:
+%Docstring
-  Queue();
+A model containing the list of songs that are enqueued on a playlist.
 
+In Clementine each L{Playlist} has its own Queue object.  The Queue keeps an
+ordered list of items that are enqueued on that playlist.  Whenever a song
+finishes the top item is removed from the Queue and is played immediately.
+When there are no items left on the Queue playback continues again in the normal
+order.
+
+The L{Playlist} is a standard Qt item model where each row represents one item
+in the playlist.  The Queue is a Qt proxy model on top of the Playlist model,
+which means that rows in the Queue can map directly onto rows in the Playlist.
+Use C{mapToSource(index)} and C{mapFromSource(index)} to map rows in the Queue
+to or from rows in the Playlist.
+
+You can't create Queue objects directly.  Instead you have to get a Queue from
+an existing playlist.
+
+  >>> queue = clementine.playlists.current().queue()
+  >>> queue.Clear()
+%End
+
+public:
   static const char* kRowsMimetype;
 
-  // Query the queue
   bool is_empty() const;
-  int PositionOf(const QModelIndex& source_index) const;
+%Docstring
-  bool ContainsSourceRow(int source_row) const;
+is_empty() -> bool
-  int PeekNext() const;
+Checks whether the queue is empty.
+%End
+
+  int PositionOf(const QModelIndex& source_index) const;
+%Docstring
+PositionOf(source_index) -> int
+Finds the position in the Queue of a playlist item.
+
+@param source_index: The index of an item in the underlying L{Playlist} model.
+@type source_index: L{PyQt4.QtCore.QModelIndex}
+@return: The position in the queue of the playlist item, or -1 if the playlist
+  item is invalid or is not in the queue.
+%End
+
+  bool ContainsSourceRow(int source_row) const;
+%Docstring
+ContainsSourceRow(source_row) -> bool
+Checks whether a playlist row is in the queue.
+
+@param source_row: The row number of an item in the underlying L{Playlist} model.
+@type source_row: int
+%End
+
+  int PeekNext() const;
+%Docstring
+PeekNext() -> int
+Returns the row number in the L{Playlist} of the next item in the queue, leaving
+the Queue unchanged.
+%End
 
-  // Modify the queue
   int TakeNext();
+%Docstring
+TakeNext() -> int
+Like L{PeekNext()}, but removes the item from the Queue as well as returning it.
+%End
+
   void ToggleTracks(const QModelIndexList& source_indexes);
+%Docstring
+ToggleTracks(source_indexes)
+Adds or removes the Playlist indexes to/from the queue.
+
+@param source_indexes: A list of indexes from the underlying L{Playlist} model.
+@type source_indexes: list of L{PyQt4.QtCore.QModelIndex}es
+%End
+
   void Clear();
+%Docstring
+Clear()
+Removes all the items from the Queue.
+%End
+
   void Move(const QList<int>& proxy_rows, int pos);
+%Docstring
+Move(proxy_rows, pos)
+Moves a list of queued items to a different position in the queue.
+
+Example::
+
+  # Moves the second item to the front.
+  queue.Move([1], 0)
+  
+  # Moves the first three items to the end.
+  queue.Move([0, 1, 2], queue.rowCount() - 1)
+
+@param proxy_rows: A list of row numbers of items already in the queue.
+@type proxy_rows: list of ints
+@param pos: The new position in which to insert the items.
+@type pos: int
+%End
+
   void MoveUp(int row);
+%Docstring
+MoveUp(row)
+Moves the queued item up one position in the Queue.
+
+This is equivalent to::
+
+  queue.Move([row], row - 1)
+%End
+
   void MoveDown(int row);
+%Docstring
+MoveUp(row)
+Moves the queued item down one position in the Queue.
+
+This is equivalent to::
+
+  queue.Move([row], row + 2)
+%End
+
+private:
+  Queue();
 };

src/scripting/python/taskmanager.sip

@@ -4,8 +4,35 @@ class TaskManager : QObject {
 #include "core/taskmanager.h"
 %End
 
+%Docstring
+API for managing progress notifications in Clementine's status bar.
+
+When you are performing a slow operation, such as downloading data from the
+network or parsing a file, it is useful to be able to provide progress
+information to the user.  Clementine displays information about any running
+tasks with a spinner animation in the status bar.
+
+When you start a new task, the TaskManager will give you an ID which you must
+keep and use again later to update the task's progress or to mark it as
+completed.
+
+This is a singleton class, you can access its methods directly through the
+C{clementine.task_manager} object:
+
+  >>> id = clementine.task_manager.StartTask("Finding some awesome music")
+  >>> clementine.task_manager.SetTaskProgress(id, 33, 100)
+  >>> clementine.task_manager.SetTaskProgress(id, 66, 100)
+  >>> clementine.task_manager.SetTaskFinished(id)
+
+@group Signals: TasksChanged, PauseLibraryWatchers, ResumeLibraryWatchers
+%End
+
 public:
   struct Task {
+%Docstring
+Object containing information about a running task.
+%End
+
     int id;
     QString name;
     int progress;
@@ -14,17 +41,73 @@ public:
   };
 
   QList<TaskManager::Task> GetTasks();
+%Docstring
+GetTasks() -> list of L{Task}s
+Returns a list of all the tasks that are currently running.
+
+Modifying the items in this list will have no effect - you have to use the other
+methods in this class to update the status of a task.
+%End
 
   int StartTask(const QString& name);
+%Docstring
+StartTask(name) -> int
+Begins a new task.
+
+@param name: A descriptive name of the task that will be displayed in the
+  status bar.
+@type name: str
+@return: A new ID for this task.  Use this ID when calling L{SetTaskFinished}
+  later.
+@note: Do not include ellipsis (...) in the name of the task, this is added
+  for you by the status bar.
+%End
+
   void SetTaskBlocksLibraryScans(int id);
+%Docstring
+SetTaskBlocksLibraryScans(id)
+Forces any library scans to wait until this task is complete.
+
+It may be useful to set this flag on a task that modifies files in the library.
+The LibraryWatcher will wait until the task is complete before starting to
+rescan the Library.
+%End
+
   void SetTaskProgress(int id, int progress, int max = 0);
+%Docstring
+SetTaskProgress(id, progress, max=0)
+Updates the progress for this task.
+
+The status bar shows the percentage progress of this task, calculated by
+C{(progress / max * 100)}.  C{max} must be provided the first time this
+method is called for a given task, but after that it can be omitted to keep the
+old value.
+%End
+
   void SetTaskFinished(int id);
+%Docstring
+SetTaskFinished(id)
+Marks the given task as finished, removing it from the status bar.
+%End
 
 signals:
   void TasksChanged();
+%Docstring
+TasksChanged()
+Emitted when the list of tasks returned by L{GetTasks()} is changed.
+%End
 
   void PauseLibraryWatchers();
+%Docstring
+PauseLibraryWatchers()
+Emitted when L{SetTaskBlocksLibraryScans()} is called on a task.
+%End
+
   void ResumeLibraryWatchers();
+%Docstring
+ResumeLibraryWatchers()
+Emitted when all tasks that blocked library scans have finished.
+%End
 
 private:
   TaskManager();