Merge refactor-song-import r1994

openlp/plugins/songs/forms/songimportform.py

@@ -217,8 +217,7 @@ class SongImportForm(OpenLPWizard):
     def validateCurrentPage(self):
         """
         Validate the current page before moving on to the next page.
-
+        Provide each song format class with a chance to validate its input by
-        Provides each song format class with a chance to validate its input by
         overriding isValidSource().
         """
         if self.currentPage() == self.welcomePage:
@@ -491,12 +490,12 @@ class SongImportForm(OpenLPWizard):
 
 class SongImportSourcePage(QtGui.QWizardPage):
     """
-    Subclass QtGui.QWizardPage in order to reimplement isComplete().
+    Subclass of QtGui.QWizardPage to override isComplete() for Source Page.
     """
-
     def isComplete(self):
         """
-        Returns True if:
+        Return True if:
+
         * an available format is selected, and
         * if MultipleFiles mode, at least one file is selected
         * or if SingleFile mode, the specified file exists

openlp/plugins/songs/lib/importer.py

@@ -80,28 +80,47 @@ class SongFormat(object):
     song formats handled by the importer, the attributes of each song format,
     and a few helper functions.
 
-
     Required attributes for each song format:
-    * ``Class`` Import class, e.g. OpenLyricsImport
+
-    * ``Name`` Name of the format, e.g. u'OpenLyrics'
+    ``Class``
-    * ``Prefix`` Prefix for Qt objects. Use camelCase, e.g. u'openLyrics'
+        Import class, e.g. ``OpenLyricsImport``
-      See ``SongImportForm.addFileSelectItem()``.
+    ``Name``
+        Name of the format, e.g. ``u'OpenLyrics'``
+    ``Prefix``
+        Prefix for Qt objects. Use mixedCase, e.g. ``u'openLyrics'``
+        See ``SongImportForm.addFileSelectItem()``
 
     Optional attributes for each song format:
-    * ``CanDisable`` Whether song format importer is disablable.
-    * ``Availability`` Whether song format importer is available.
-    * ``SelectMode`` Whether format accepts single file, multiple files, or
-      single folder (as per SongFormatSelect options).
-    * ``Filter`` File extension filter for QFileDialog.
 
-    Optional/custom text Strings for SongImportForm widgets:
+    ``CanDisable``
-    * ``ComboBoxText`` Combo box selector (default value is format Name).
+        Whether song format importer is disablable.
-    * ``DisabledLabelText`` Required for disablable song formats.
+    ``Availability``
-    * ``GetFilesTitle`` Title for QFileDialog (default includes format Name).
+        Whether song format importer is available.
-    * ``InvalidSourceMsg`` Message displayed when source does not validate with
+    ``SelectMode``
-      Class.isValidSource().
+        Whether format accepts single file, multiple files, or single folder
+        (as per ``SongFormatSelect`` options).
+    ``Filter``
+        File extension filter for ``QFileDialog``.
+
+    Optional/custom text Strings for ``SongImportForm`` widgets:
+
+    ``ComboBoxText``
+        Combo box selector (default value is the format's ``Name``).
+    ``DisabledLabelText``
+        Required for disablable song formats.
+    ``GetFilesTitle``
+        Title for ``QFileDialog`` (default includes the format's ``Name``).
+    ``InvalidSourceMsg``
+        Message displayed if ``Class.isValidSource()`` returns ``False``.
     """
-    # Song Formats
+    # Enumeration of song formats and their attributes
+    # * Numerical order of song formats is significant as it determines the
+    #   order used by formatComboBox.
+    # * Attribute ints are negative so they don't clash with song format ints.
+    # * Each group of attribute values increments by 10 to facilitate addition
+    #   of more attributes in future.
+
+    # Song formats (ordered alphabetically after Generic)
     Unknown = -1
     OpenLyrics = 0
     OpenLP2 = 1
@@ -320,9 +339,9 @@ class SongFormat(object):
             Zero or more song format attributes from SongFormat.
 
         Return type depends on number of supplied attributes:
-            * 0 : Return dict containing all defined attributes for the format.
+        :0: Return dict containing all defined attributes for the format.
-            * 1 : Return the attribute value.
+        :1: Return the attribute value.
-            * >1 : Return tuple of requested attribute values.
+        :>1: Return tuple of requested attribute values.
         """
         if not attributes:
             return SongFormat._attributes.get(format)