Use gtkdoc documentation for python docstrings, topped up with docstrings by Todd Zullinger.

git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@1366 f01d2545-417e-4e96-918e-98f8d0dbbcb6

1 files changed, 224 insertions, 15 deletions

diff --git a/bindings/python/ipod.py b/bindings/python/ipod.py
index a3ac1c0..4c0d14a 100644
--- a/bindings/python/ipod.py
+++ b/bindings/python/ipod.py
@@ -1,6 +1,8 @@
-"""Documentation for this module.
+"""Manage tracks and playlists on an iPod.
+
+You should normally just import the gpod module which will import the
+classes and methods provided here.
 
-More details.
 """
 
 import gpod
@@ -10,13 +12,41 @@ import gtkpod
 import os
 
 class DatabaseException(RuntimeError):
+    """Exception for database errors."""
     pass
 
 class TrackException(RuntimeError):
+    """Exception for track errors."""
     pass
 
 class Database:
+    """An iTunes database.
+
+    A database contains playlists and tracks.
+
+    """
+
     def __init__(self, mountpoint="/mnt/ipod", local=False, localdb=None):
+        """Create a Database object.
+
+        You can create the object from a mounted iPod or from a local
+        database file.
+
+        To use a mounted iPod:
+
+            db = gpod.Database('/mnt/ipod')
+
+        To use a local database file:
+
+            db = gpod.Database(localdb='/path/to/iTunesDB')
+
+        If you specify local=True then the default local database from
+        gtkpod will be used (~/.gtkpod/local_0.itdb):
+
+            db = gpod.Database(local=True)
+
+        """
+
         if local or localdb:
             if localdb:
                 self._itdb_file = localdb
@@ -37,7 +67,7 @@ class Database:
 
     def __str__(self):
         return self.__repr__()
-    
+
     def __repr__(self):
         return "<Database Filename:%s Playlists:%s Tracks:%s>" % (
             repr(self._itdb.filename),
@@ -45,12 +75,21 @@ class Database:
             len(self))
 
     def _load_gtkpod_extended_info(self):
+        """Read extended information from a gtkpod .ext file."""
         itdbext_file = "%s.ext" % (self._itdb_file)
 
         if os.path.exists(self._itdb_file) and os.path.exists(itdbext_file):
             gtkpod.parse(itdbext_file, self, self._itdb_file)
 
     def close(self):
+        """Save and close the database.
+
+        Note: If you are working with an iPod you should normally call
+        copy_delayed_files() prior to close() to ensure that newly
+        added or updated tracks are transferred to the iPod.
+
+        """
+
         if not gpod.itdb_write_file(self._itdb, self._itdb_file, None):
             raise DatabaseException("Unable to save iTunes database %s" % self)
         itdbext_file = "%s.ext" % (self._itdb_file)        
@@ -68,6 +107,11 @@ class Database:
         return gpod.sw_get_list_len(self._itdb.tracks)
 
     def import_file(self, filename):
+        """Import a file.
+
+        filename is added to the end of the master playlist.
+
+        """
         track = Track(filename)
         track.copy_to_ipod()
         gpod.itdb_playlist_add_track(gpod.itdb_playlist_mpl(self._itdb),
@@ -77,9 +121,26 @@ class Database:
         gpod.itdb_free(self._itdb)
 
     def add(self, track, pos=-1):
+        """Add a track to a database.
+
+        If pos is set the track will be inserted at that position.  By
+        default the track will be added at the end of the database.
+
+        """
+
         gpod.itdb_track_add(self._itdb, track._track, pos)
 
     def remove(self, item, harddisk=False, ipod=True):
+        """Remove a playlist or track from a database.
+
+        item is either a playlist or track object.
+
+        If harddisk is True the item will be removed from the the hard drive.
+
+        If ipod is True the item will be removed from the iPod.
+
+        """
+
         if isinstance(item, Playlist):
             if ipod or harddisk:
                 # remove all the tracks that were in this playlist
@@ -109,12 +170,15 @@ class Database:
             raise DatabaseException("Unable to remove a %s from database" % type(item))
 
     def get_master(self):
+        """Get the Master playlist."""
         return Playlist(self,proxied_playlist=gpod.itdb_playlist_mpl(self._itdb))
 
     def get_podcasts(self):
+        """Get the podcasts playlist."""
         return Playlist(self,proxied_playlist=gpod.itdb_playlist_podcasts(self._itdb))
 
     def get_playlists(self):
+        """Get all playlists."""
         return _Playlists(self)
 
     Master   = property(get_master)
@@ -122,12 +186,25 @@ class Database:
     Playlists= property(get_playlists) 
 
     def smart_update(self):
+        """Update all smart playlists."""
         gpod.itdb_spl_update_all(self._itdb)
 
     def new_Playlist(self,*args,**kwargs):
+        """Create a new Playlist.
+
+        See Playlist.__init__() for details.
+
+        """
+
         return Playlist(self, *args,**kwargs)
 
     def new_Track(self,**kwargs):
+        """Create a new Track.
+
+        See Track.__init__() for details.
+
+        """
+
         track = Track(**kwargs)
         self.add(track)
         if kwargs.has_key('podcast') and kwargs['podcast'] == True:
@@ -137,6 +214,19 @@ class Database:
         return track
 
     def copy_delayed_files(self,callback=False):
+        """Copy files not marked as transferred to the iPod.
+
+        callback is an optional function that will be called for each
+        track that is copied.  It will be passed the following
+        arguments:
+
+            database -> the database object
+            track    -> the track being copied
+            iterator -> the current track number being copied
+            total    -> the total tracks to be copied
+
+        """
+
         if not gpod.itdb_get_mountpoint(self._itdb):
             # we're not working with a real ipod.
             return
@@ -157,10 +247,22 @@ class Database:
             track.copy_to_ipod()
 
 class Track:
+    """A track in an iTunes database.
+
+    A track contains information like the artist, title, album, etc.
+    It also contains data like the location on the iPod, whether there
+    is artwork stored, the track has lyrics, etc.
+
+    Information from a gtkpod extended info file (if one exists for
+    the iTunesDB) is also available in Track['userdata'].
+
+    The information is stored in a dictionary.
+
+    """
+
     # Note we don't free the underlying structure, as it's still used
     # by the itdb.
-    
-    
+
     _proxied_attributes = ("title","ipod_path","album","artist","genre","filetype",
                            "comment","category","composer","grouping","description",
                            "podcasturl","podcastrss","chapterdata","subtitle","id",
@@ -179,6 +281,20 @@ class Track:
 
     def __init__(self, filename=None, from_file=None,
                  proxied_track=None, podcast=False):
+        """Create a Track object.
+
+        If from_file or filename is set, the file specified will be
+        used to create the track.
+
+        If proxied_track is set, it is expected to be an Itdb_Track
+        object.
+
+        If podcast is True then the track will be setup as a Podcast,
+        unless proxied_track is set. 
+
+        """
+
+        # XXX couldn't from_file and filename be merged? 
         if from_file:
             filename = from_file
         if filename:
@@ -218,9 +334,10 @@ class Track:
             self._track = proxied_track
         else:
             self._track = gpod.itdb_track_new()
-        self.set_podcast(podcast)
+            self.set_podcast(podcast)
 
     def copy_to_ipod(self):
+        """Copy the track to the iPod."""
         self['userdata']['md5_hash'] = gtkpod.sha1_hash(
             self['userdata']['filename_locale'])
         if not gpod.itdb_get_mountpoint(self._track.itdb):
@@ -234,21 +351,37 @@ class Track:
         return True
 
     def ipod_filename(self):
+        """Get the full path to the track on the iPod.
+
+        Note (from the libgpod documentation): This code works around
+        a problem on some systems and might return a filename with
+        different case than the original filename. Don't copy it back
+        to track unless you must.
+
+        """
+
         return gpod.itdb_filename_on_ipod(self._track)
 
     def set_podcast(self, value):
+        """Mark the track as a podcast.
+
+        If value is True flags appropriate for podcasts are set,
+        otherwise those flags are unset.
+
+        """
+
         if value:
             self['skip_when_shuffling'] = 0x01
             self['remember_playback_position'] = 0x01
-            self['flag4'] = 0x01 # Show Title/Album on the 'Now Playing' page            
+            self['flag4'] = 0x01 # Show Title/Album on the 'Now Playing' page
         else:
             self['skip_when_shuffling'] = 0x00
             self['remember_playback_position'] = 0x00
-            self['flag4'] = 0x00 # Show Title/Album/Artist on the 'New Playing' page
+            self['flag4'] = 0x00 # Show Title/Album/Artist on the 'Now Playing' page
 
     def __str__(self):
         return self.__repr__()
-    
+
     def __repr__(self):
         return "<Track Artist:%s Title:%s Album:%s>" % (
             repr(self['artist']),
@@ -284,6 +417,8 @@ class Track:
         else:
             raise KeyError('No such key: %s' % item)
 
+# XXX would this be better as a public variable so that the docs would
+# list valid sort order values?
 _playlist_sorting = {
     1:'playlist',
     2:'unknown2',
@@ -323,7 +458,7 @@ class _Playlists:
 
     def __nonzero__(self):
         return True
-    
+
     def __getitem__(self, index):
         if type(index) == types.SliceType:
             return [self[i] for i in xrange(*index.indices(len(self)))]
@@ -336,7 +471,7 @@ class _Playlists:
 
     def __repr__(self):
         return "<Playlists from %s>" % self._db
-    
+
     def __call__(self, id=None, number=None, name=None):
         if ((id and (number or name)) or (number and name)):
             raise ValueError("Only specify id, number OR name")
@@ -373,10 +508,30 @@ class _Playlists:
                                     proxied_playlist=pl)
                 else:
                     raise KeyError("Playlist with number %s not found." % repr(number))
-        
+
 class Playlist:
+    """A playlist in an iTunes database."""
+
     def __init__(self, parent_db, title="New Playlist",
                  smart=False, pos=-1, proxied_playlist=None):
+        """Create a playlist object.
+
+        parent_db is the database object to which the playlist
+        belongs.
+
+        title is a string that provides a name for the playlist.
+
+        If smart is true the playlist will be a smart playlist.
+
+        If pos is set the track will be inserted at that position.  By
+        default the playlist will be added at the end of the database.
+
+        If proxied_playlist is set it is expected to be an
+        Itdb_Playlist object (as returned by gpod.sw_get_playlist() or
+        similar functions).
+
+        """
+
         self._db = parent_db
         if proxied_playlist:
             self._pl = proxied_playlist
@@ -389,32 +544,71 @@ class Playlist:
             gpod.itdb_playlist_add(self._db._itdb, self._pl, pos)
 
     def smart_update(self):
+        """Update the content of the smart playlist."""
         gpod.itdb_spl_update(self._pl)
 
     def randomize(self):
+        """Randomizes the playlist."""
         gpod.itdb_playlist_randomize(self._pl)
 
     def get_name(self):
+        """Get the name of the playlist."""
         return self._pl.name
+
     def set_name(self, name):
+        """Set the name for the playlist."""
         self._pl.name = name
+
     def get_id(self):
+        """Get the id of the playlist."""
         return self._pl.id
+
+    # XXX would this be more aptly named is_smart?  If it was, I think
+    # the docstring could skip the explanation of the return value.
+    # (Same question for get_master and get_podcast.)
     def get_smart(self):
+        """Check if the playlist is smart or not.
+
+        Returns True for a smart playlist, False for a regular
+        playlist.
+
+        """
+
         if self._pl.is_spl == 1:
             return True
         return False
+
     def get_master(self):
+        """Check if the playlist is the master playlist (MPL).
+
+        Returns True if the playlist is the MPL, False if not.
+
+        """
+
         if gpod.itdb_playlist_is_mpl(self._pl) == 1:
             return True
         return False
+
     def get_podcast(self):
+        """Check if the playlist is the podcasts playlist.
+
+        Returns True if the playlist is the podcasts playlist, False
+        if not.
+
+        """
+
         if gpod.itdb_playlist_is_podcasts(self._pl) == 1:
             return True
         return False
+
     def get_sort(self):
+        """Get the sort order for the playlist."""
         return _playlist_sorting[self._pl.sortorder]
+
+    # XXX how does one find out what values are allowed for order without
+    # poking into this file?  (See similar question @ _playlist_order)
     def set_sort(self, order):
+        """Set the sort order for the playlist."""
         order = order.lower()
         for k, v in _playlist_sorting.items():
             if v == order:
@@ -431,7 +625,7 @@ class Playlist:
 
     def __str__(self):
         return self.__repr__()
-    
+
     def __repr__(self):
         return "<Playlist Title:%s Sort:%s Smart:%s Master:%s Podcast:%s Tracks:%d>" % (
             repr(self.name),
@@ -440,7 +634,7 @@ class Playlist:
             repr(self.master),
             repr(self.podcast),
             len(self))
-        
+
     def __getitem__(self, index):
         if type(index) == types.SliceType:
             return [self[i] for i in xrange(*index.indices(len(self)))]
@@ -461,11 +655,26 @@ class Playlist:
             return True
         else:
             return False
-    
+
     def add(self, track, pos=-1):
+        """Add a track to the playlist.
+
+        track is a track object to add.
+
+        If pos is set the track will be inserted at that position.  By
+        default the track will be added at the end of the playlist.
+
+        """
+
         gpod.itdb_playlist_add_track(self._pl, track._track, pos)
 
     def remove(self, track):
+        """Remove a track from the playlist.
+
+        track is a track object to remove.
+
+        """
+
         if self.__contains__(track):
             gpod.itdb_playlist_remove_track(self._pl, track._track)
         else: