Commits

Damián Nohales committed 0992132

Some documentation.

Comments (0)

Files changed (7)

lib/AbstractSongList.py

 import gobject
 
 class AbstractSongList(gobject.GObject):
+    """
+    This class represents a Song list linked with a TreeView  
+    and a ListStore. also provides several facilities to manage the list.
+    """
     
     def __init__(self, view):
+        """
+        Initialize the List
+        @param view: The TreeView used in the list.
+        """
         self._view = view
         self._view.set_model(self.create_model())
         self.create_view()
     
-    # Virtual
     def create_model(self):
+        """
+        Return the model used by the list, a derived class must reimplement
+        this method.
+        """
         model = gtk.ListStore(object)
         return model
     
-    # Abstract
     def create_view(self):
+        """
+        Initialize the TreeView, a derived class must reimplement
+        this method.
+        """
         pass
     
     def get_view(self):
         return self.get_view().get_model()
     
     def append_song(self, song):
+        """
+        Append a song to the list, a derived class must reimplement
+        this method.
+        """
         self.get_model().append([song])
     
     def find_song(self, song):
+        """
+        Return a tuple containing the path and iter for the song passed
+        by parameter or None if the song is not found.
+        """
         iter = self.get_model().get_iter_first()
         while iter != None:
             if self.get_model()[iter][0].equals(song):
         return None
     
     def get_song_row(self, song):
+        """
+        Returns the model row related to the song passed by parameter.
+        """
         return self.get_model()[self.get_song_iter(song)]
         
     def get_song_path(self, song):
+        """
+        Returns the path related to the song passed by parameter.
+        """
         finded = self.find_song(song)
         
         if finded == None:
             return finded[0]
 
     def get_song_iter(self, song):
+        """
+        Returns the TreeIter related to the song passed by parameter.
+        """
         finded = self.find_song(song)
         
         if finded == None:
             return finded[1]
         
     def get_song(self, path_or_iter):
+        """
+        Returns the song related to a path or iter
+        """
         return self.get_model()[path_or_iter][0]
         
     
     # Shortcuts to handle the list
     
     def clear(self):
+        """
+        Clear the list.
+        """
         self.get_model().clear()
         
     def __len__(self):
+        """
+        Allows to do the following: len(songlist)
+        """
         return len(self.get_model())
     
     def first(self):
+        """
+        Returns the first iter of the list.
+        """
         return self.get_model().get_iter_first()
     
     def next(self, iter):
+        """
+        Returns the next iter of the iter passed by parameter
+        """
         return self.get_model().iter_next(iter)
     
     def range(self):
+        """
+        Returns a range from 0 to len-1 to ease the list walking.
+        """
         return range(len(self.get_model()))
     
     def get_selected_rows(self):

lib/DownloadList.py

 import os
     
 class DownloadList(AbstractSongList):
+    """
+    Represent the download list
+    """
+    
     def __init__(self, view):
         AbstractSongList.__init__(self, view)
     
 import glib
     
 class PlayList (AbstractSongList):
+    """
+    Represent the PlayList
+    """
+    
     def __init__(self, view):
         AbstractSongList.__init__(self, view)
         self.playing_song = None
         return self.get_view().get_selected_items()
     
     def get_playing_song(self):
+        """
+        Returns the current playing song or None if not playing nothing.
+        """
         return self.playing_song
     
     def set_playing_song(self, song):
+        """
+        Set the current playing song.
+        @param song: The song or None to indicate that there is no song playing
+        """
         if song != None:
             path = self.get_song_path(song)
             if song.get_cover_pixbuf() != None:
         return pixbuf
     
     def create_composited_image(self, pixbuf):
+        """
+        Composite play.png with the pixbuf
+        """
         pixbuf = pixbuf.copy()
         play = gtk.gdk.pixbuf_new_from_file('%s/data/play.png' % env().BASEPATH)
         play.composite(pixbuf, 0, 0, pixbuf.props.width, pixbuf.props.height,

lib/SearchResultList.py

 import gtk
     
 class SearchResultList(AbstractSongList):
+    """
+    Represent the list of search results
+    """
+    
     def __init__(self, view):
         AbstractSongList.__init__(self, view)
     
 
 class Song(gobject.GObject):
     """
-    This encasuplates a handle song information.
+    This class encasuplates a handle song information.
     """
     
     """
     last_song_local_id = 0
     
     def __init__(self, data):
+        """
+        @param data: The array data given by GrooveShark. This array also can has a
+        key called 'filename', it is used to initialize the Song with a filename,
+        used mainly by the app when load the downqueue file to know on wich file should
+        download the song.
+        """
         self.__gobject_init__()
         Song.last_song_local_id += 1
         
         
         if self.get_cover_filename() == "":
             self.set_cover_missed_pixbuf()
-        
+    
     def __getitem__(self, key):
+        """
+        Allows to use the song as a dictionary (not recommended, use
+        methods instead)
+        """
         return self.data[key]
     
     def clone(self):
         return newsong
     
     def equals(self, othersong):
+        """
+        Compare a song with another
+        @param othersong: the song to compare
+        """
         if othersong == None:
             return False
         
         return self.data['CoverArtFilename']
     
     def get_cover_pixbuf(self):
+        """
+        Get the pixbuf for the song album cover.
+        If returns None, means that we need to download the cover
+        using download_cover
+        """
         return self.cover_pixbuf
         
     def set_cover_pixbuf(self, pixbuf):
+        """
+        Set the pixbuf for the song album cover.
+        Used by SongCoverThread and clone.
+        """
         self.cover_pixbuf = pixbuf
         
     def set_cover_missed_pixbuf(self):
         self.cover_pixbuf = gtk.gdk.pixbuf_new_from_file("%s/data/sdefault.png" % env().BASEPATH)
         
     def download_cover(self):
+        """
+        Download the album cover, the object will emit the 'cover-downloaded'
+        signal when the download finish.
+        """
         thread = SongCoverThread(self)
         thread.start()
         
     def download_file(self, restart = False, speed = None):
+        """
+        Starts the song download, the object will emit various signals to
+        handle the download progress.
+        @param restart: If is False means that we should try to continue with the
+        download if file exists.
+        @param speed: The speed limit for the download, the default is the confi-
+        gured in the app.
+        """
         if speed == None:
             speed = int(config()["speed_limit"])
         
         self.download_thread.start()
         
     def is_downloading(self):
+        """
+        Returns true if the download is running
+        """
         return self.download_thread.is_alive()
     
     def is_paused(self):
+        """
+        Returns true if the download was stopped by pausing it
+        """
         return self.is_downloading() == False and self.download_thread.is_canceled == False
         
     def pause_download(self):
+        """
+        Pause the current download
+        """
         if self.is_downloading():
             self.download_thread.pause()
         
     def cancel_download(self):
+        """
+        Cancel the current download
+        """
         if self.is_downloading():
             self.download_thread.cancel()
         
     def pause_download_sync(self):
+        """
+        Pause the current download and wait until it stops altogether.
+        """
         if self.is_downloading():
             self.download_thread.pause()
             self.download_thread.join();
             
     def get_download_progress(self):
+        """
+        Returns the current download progress in bytes or None if
+        the download is not initialized.
+        """
         return self.download_progress
 
     def set_download_progress(self, value):
         self.download_progress = value
 
     def get_file_size(self):
+        """
+        Returns the current file size in bytes or None if
+        the download is not initialized.
+        """
         return self.file_size
 
     def set_file_size(self, value):
         self.filename = value
         
     def get_default_filename(self):
-        #filename = "%s - %s.mp3" % (song["ArtistName"].strip("<>:\"/\|?*"),
-        #                        song["SongName"].strip("<>:\"/\|?*"))
         pattern = config()['file_pattern'] + ".mp3"
         filename = pattern.format(artist = self.get_artist().strip("<>:\"/\|?&*"),
                                   song = self.get_title().strip("<>:\"/\|?&*"),
         return filename
 
 gobject.type_register(Song)
+"""
+Signals of the Song type
+"""
 # Emitted when the cover download was finished
 gobject.signal_new("cover-downloaded", Song, gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE, ())
 # Emitted when download starts or resumes
 
 
 class SongCoverThread(threading.Thread):
+    """
+    This class download a song cover album and notify
+    it when download ends. Should not be used directly, use Song instead.
+    """
+    
     def __init__(self, song):
         threading.Thread.__init__(self)
         self.song = song
         
 
 class DownloadThread(threading.Thread):
-
+    """
+    This class download the song file and notify the progress.
+    Should not be used directly, use Song instead.
+    """
+    
     def __init__(self, song):
-        """
-        _window: The main window object
-        _song: The song to download
-        _filename: The full path file name to download the song
-        """
         threading.Thread.__init__(self)
 
         self.song = song

lib/enviroment.py

 from configobj import ConfigObj
 
 class Enviroment:
+    """
+    This class represent the execution enviroment and configuration
+    of the app. Is a singleton class an the instance should be accessed
+    using the env() function.
+    """
+    
     def __init__(self):
         # Application name
         self.APP = 'gsharkdown'
         self._config = config
         
     def get_config_filename(self):
+        """
+        Returns the filename for the configuration file
+        """
         return "%s/.gsharkdown/gsharkdown.ini" % os.environ.get("HOME")
         
     def get_default_down_path(self):
+        """
+        Returns the default download path.
+        """
         music_dir = glib.get_user_special_dir(glib.USER_DIRECTORY_MUSIC) or os.path.join(os.environ.get("HOME"), "Music")
         return os.path.join(music_dir, "Grooveshark")
     
         }
     
     def initialize(self):
+        """
+        Initialize the enviroment
+        """
         # Initialize i18n variables
         if os.path.exists("locale"):
             self.LOCALE_DIR = "%s/locale" % self.BASEPATH

lib/guihelpers.py

 
 class LyricsDialog:
     """
-    Lyrics Dialog to be shown in a Thread. requieres the
-    .ui file, the name of the artist and song, and the
-    lyrics itself.
+    Lyrics Dialog to be shown in a Thread.
     """
 
     def __init__(self, song, lyrics):
         """
         Accepted parameters in the Lyrics dialog
-        @param _uifile : the path to the .ui file for the dialog
-        @param _artist : The Artist string to search for
-        @param _song : The Song title string to search for
-        @param _lyrics : The lyrics as string to be shown in the dialog
+        @param song : The song
+        @param lyrics : The lyrics as string to be shown in the dialog
         """
         self.builder = gtk.Builder()
         self.builder.add_from_file("%s/data/lyrics_dialog.ui" % env().BASEPATH)
     """
     Show a dialog for configure the preferences
     """
+    
     def __init__(self, app):
         self.app = app
         
         self.prefs.destroy()
         
 class AboutDialog:
+    """
+    Show the about dialog.
+    """
+    
     def __init__(self, app):
         builder = gtk.Builder()
         builder.set_translation_domain(env().APP)
 
 class GsharkIndicator:
     """
-    AppIndicator for gSharkDown
+    AppIndicator/StatusIcon for gSharkDown
     """
 
     def __init__(self, instance):