Release v1.7

.gitignore

@@ -4,6 +4,9 @@
 *.swp
 *.wpr
 *.wpu
+*~
+\#*
+.\#*
 .coverage
 .pc
 MANIFEST
@@ -14,3 +17,4 @@ dist
 nosetests.xml
 spotify_appkey.key
 tmp/
+.DS_Store

Makefile

@@ -0,0 +1,24 @@
+.PHONY: autotest build clean default install test
+
+BUILD_DIR="build/lib/"
+
+default: build
+
+clean:
+	@rm -rf build/
+
+build: clean
+	@python setup.py build --with-mock --build-lib ${BUILD_DIR}
+
+test: build
+	@PYTHONPATH=${BUILD_DIR} nosetests
+
+autotest: build
+	@which inotifywait || (echo "inotifywait not found"; exit 1)
+	@while true; do \
+	  clear; \
+	  PYTHONPATH=${BUILD_DIR} nosetests; \
+	  inotifywait -q -e create -e modify -e delete \
+	    --exclude ".*\.(pyc|sw.)" \
+	    -r spotify/ src/ tests/; \
+	done

README.rst

@@ -14,10 +14,7 @@ apply for, and receive an API key from Spotify.
 Project resources
 =================
 
-- `Documentation for the latest release
-  <http://pyspotify.mopidy.com/docs/master/>`_
-- `Documentation for the development version
-  <http://pyspotify.mopidy.com/docs/develop/>`_
+- `Documentation <http://pyspotify.mopidy.com/>`_
 - `Source code <http://github.com/mopidy/pyspotify>`_
 - `Issue tracker <http://github.com/mopidy/pyspotify/issues>`_
 - IRC: ``#mopidy`` at `irc.freenode.net <http://freenode.net/>`_

docs/api/albumbrowse.rst

@@ -2,21 +2,24 @@ Album browsing
 **************
 .. currentmodule:: spotify
 
-Album browsers are created by :meth:`Session.browse_album` object. They are
-iterable objects.
-
-
 The :class:`AlbumBrowser` class
 ===============================
 
-.. class:: AlbumBrowser
-
-    AlbumBrowser objects.
+.. class:: AlbumBrowser(album[, callback[, userdata]])
 
     .. note:: A sequence of :class:`Track` objects.
 
+    Browse an album, calling the callback when the browser's metadata is
+    loaded.
+
+    :param album: a Spotify album (does not have to be loaded)
+    :type album: :class:`Album`
+    :param callback: a function with signature :
+        ``(AlbumBrowser browser, Object userdata)``
+    :param userdata: any object
+
     .. method:: is_loaded
 
         :rtype:     :class:`int`
-        :returns:   Wether this album browser has finished loading metadata.
+        :returns:   wether this album browser has finished loading metadata.
 

docs/api/artistbrowse.rst

@@ -2,21 +2,53 @@ Artist browsing
 ***************
 .. currentmodule:: spotify
 
-Artist browsers are created by :meth:`Session.browse_artist` object. They are
-iterable objects.
-
-
 The :class:`ArtistBrowser` class
 ================================
 
-.. class:: ArtistBrowser
-
-    ArtistBrowser objects.
+.. class:: ArtistBrowser(artist[, type[, callback[, userdata]]])
 
     .. note:: A sequence of :class:`Track` objects.
 
+    Browse an artist, calling the callback when the browser's metadata is
+    loaded.
+
+    :param artist: a Spotify artist (does not have to be loaded)
+    :type artist: :class:`Artist`
+    :param type:    this browser's type. One of:
+
+        * ``'full'`` (default):     all data will be fetched (deprecated in
+          pyspotify 1.7 / libspotify 11)
+        * ``'no_tracks'``:          no information about tracks
+        * ``'no_albums'``:          no information about albums (implies ``'no_tracks'``)
+
+        The ``'no_tracks'`` and ``'no_albums'`` browser types also include a
+        list of top tracks for this artist.
+
+    :param callback: a function with signature :
+        ``(ArtistBrowser browser, Object userdata)``
+    :param userdata: any object
+
     .. method:: is_loaded
 
         :rtype:     :class:`int`
-        :returns:   Wether this artist browser has finished loading metadata.
+        :returns:   wether this artist browser has finished loading metadata.
+
+    .. method:: albums
+
+        :rtype:     list of :class:`Album`
+        :returns:   the list of albums found while browsing
+
+    .. method:: similar_artists
+
+        :rtype:     list of :class:`Artist`
+        :returns:   the list of similar artists found while browsing
+
+    .. method:: tracks
+
+        :rtype:     list of :class:`Track`
+        :returns:   the list of tracks found while browsing
+
+    .. method:: tophit_tracks
 
+        :rtype:     list of :class:`Track`
+        :returns:   the list of top tracks for this artist found while browsing

docs/api/image.rst

@@ -8,7 +8,34 @@ The :class:`Image` class
 ========================
 .. currentmodule:: spotify
 
-.. autoclass:: Image
-    :members:
-    :undoc-members:
+.. class:: Image
 
+  Image objects
+
+  .. method:: add_load_callback()
+
+     Add a load callback
+
+  .. method:: data()
+
+     Get image data
+
+  .. method:: error()
+
+     Check if image retrieval returned an error code
+
+  .. method:: format()
+
+     Get image format (currently only JPEG)
+
+  .. method:: image_id()
+
+     Get image ID
+
+  .. method:: is_loaded()
+
+     True if this Image has been loaded by the client
+
+  .. method:: remove_load_callback()
+
+     Remove a load callback

docs/api/link.rst

@@ -17,71 +17,100 @@ The :class:`Link` class
 
     .. data:: LINK_TRACK
 
-
     .. data:: LINK_ALBUM
 
-
     .. data:: LINK_ARTIST
 
-
     .. data:: LINK_SEARCH
 
-
     .. data:: LINK_PLAYLIST
 
+    .. method:: __str__()
+
+        Return the link as a string in the Spotify format.
+
+        Example: ``spotify:track:5st5644IlBmKiiRE73UsoZ``
+
+    .. method:: type()
+
+        Return the type of the link as an :class:`int`. Check value
+        against the :data:`LINK_*` types.
 
     .. method:: as_album()
 
-        Return this link as an :class:`Album` object.
+        :return: the link as an :class:`Album` object.
+        :rtype: :class:`Album`
 
     .. method:: as_artist()
 
-        Return this link as an :class:`Artist` object.
+        :return: the link as an :class:`Artist` object.
+        :rtype: :class:`Artist`
 
     .. method:: as_track()
 
-        Return this link as a :class:`Track` object.
+        :return: the link as a :class:`Track` object.
+        :rtype: :class:`Track`
 
     .. staticmethod:: from_album(album)
 
+        :param album: an album
+        :type album: :class:`Album`
+        :return: link to the album
+        :rtype: :class:`Link`
         :raises: :exc:`SpotifyError`
 
         Create a new :class:`Link` object from an :class:`Album` object.
 
     .. staticmethod:: from_artist(artist)
 
-       :raises: :exc:`SpotifyError`
+        :param artist: an artist
+        :type artist: :class:`Artist`
+        :return: link to the artist
+        :rtype: :class:`Link`
+        :raises: :exc:`SpotifyError`
 
-       Create a new :class:`Link` object from an :class:`Artist` object.
+        Create a new :class:`Link` object from an :class:`Artist` object.
 
     .. staticmethod:: from_playlist(playlist)
 
-       :raises: :exc:`SpotifyError`
+        :param playlist: a playlist
+        :type playlist: :class:`Playlist`
+        :return: link to the playlist
+        :rtype: :class:`Link`
+        :raises: :exc:`SpotifyError`
 
-       Create a new :class:`Link` object from a :class:`Playlist` object.
+        Create a new :class:`Link` object from a :class:`Playlist` object.
 
     .. staticmethod:: from_search(results)
 
-       :raises: :exc:`SpotifyError`
+        :param results: a result set
+        :type results: :class:`Results`
+        :return: link to the result set
+        :rtype: :class:`Link`
+        :raises: :exc:`SpotifyError`
 
-       Create a new :class:`Link` object from a :class:`Results` object.
+        Create a new :class:`Link` object from a :class:`Results` object.
 
     .. staticmethod:: from_string(s)
 
+        :param s: a Spotify URI
+        :type s: :class:`string`
+        :return: link to the same resource as the URI string
+        :rtype: :class:`Link`
         :raises: :exc:`SpotifyError`
 
         Create a new :class:`Link` object from a string.
         Raises an exception if the string is not a valid Spotify URI.
 
-    .. staticmethod:: from_track()
+    .. staticmethod:: from_track(track[, offset])
 
+        :param track: a track
+        :type track: :class:`Track`
+        :param offset: offset in milliseconds from the start of the track
+        :type offset: :class:`int`
+        :return: link to the result set
+        :rtype: :class:`Link`
         :raises: :exc:`SpotifyError`
 
-        Create a new :class:`Link` object from a :class:`Track` object.
-
-    .. method:: type()
-
-        Return the type of the link as an :class:`int`. Check value
-        against the :data:`LINK_*` types.
-
-
+        Create a new :class:`Link` object from a :class:`Track` object, and
+        optionally a time offset in milliseconds from the start of the track.

docs/api/playlist.rst

@@ -150,6 +150,11 @@ objects.
         :rtype:     :class:`int`
         :returns:   The number of subscribers of this playlist
 
+    .. method:: owner
+
+        :rtype:     :class:`spotify.User`
+        :returns:   the owner of the playlist
+
     .. method:: rename(name)
 
         :param name:    the new name

docs/api/search.rst

@@ -39,6 +39,24 @@ The :class:`Results` class
         :rtype:     string
         :returns:   the query expression that generated these results.
 
+    .. method:: total_albums
+
+        :rtype:     :class:`int`
+        :returns:   the total number of albums available for this search query.
+
+        .. note:: If this value is larger than the interval specified at
+            creation of the search object, more search results are available.
+            To fetch these, create a new search object with a new interval.
+
+    .. method:: total_artists
+
+        :rtype:     :class:`int`
+        :returns:   the total number of artists available for this search query.
+
+        .. note:: If this value is larger than the interval specified at
+            creation of the search object, more search results are available.
+            To fetch these, create a new search object with a new interval.
+
     .. method:: total_tracks
 
         :rtype:     :class:`int`