rspotify 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 143c29a98dc6fd1ddcea30f3652f0f90b76b20cf
-  data.tar.gz: 37b43846b4ef02d85492c9c28a37e9508d927124
+  metadata.gz: 3821a59eda0417ad48c54dfedcb48f81e7b9a20d
+  data.tar.gz: c00df9a3e146bec3f253d6837295e7b2b1ee8291
 SHA512:
-  metadata.gz: f2e541262d61bc8b5337a29c4a37cf2f19c204ace211767d19579ae936d4107e79ea6a6c7d80d70c6e75356d984388a339a7dfcd9611fedd5b65353363cb2db2
-  data.tar.gz: 8e3fb4b604c933c1b86d3c0a20960350b766110cf81bc8a3b9b18b8959ed044b62356d29bd4e57594c5d12c90b9792a45f573982070ba80ec781141829b44416
+  metadata.gz: 639c192ff705248d9567659cbec7acfb799ed97c185810efb73fe380e64d5302894111bb0a79cc8a6567f0e22e87177663db1a5816dcd233eb70c388bba14771
+  data.tar.gz: 3331bbe544c3ca3ad49cdeb3802effc5c223c16d9345e354a161d165b8b77b16f66057a81b47247a89ad0424083ad922611afcad620702af16176208830a8771

data/README.md

@@ -97,7 +97,7 @@ RSpotify focuses on objects behaviour so you can forget the API and worry about
 
 It is possible to write things like `playlist.tracks.sort_by(&:popularity).last.album` without having to think what API calls must be done. RSpotify fills the gaps for you.
 
-Full documentation can be found [here](http://rdoc.info/github/guilhermesad/rspotify/master/frames). (Will be complete in the next few days)
+Full documentation can be found [here](http://rdoc.info/github/guilhermesad/rspotify/master/frames).
 
 ## Notes
 

data/lib/rspotify/album.rb

@@ -1,11 +1,51 @@
 module RSpotify
 
+  # @attr [String]        album_type             The type of the album (album, single, compilation)
+  # @attr [Array<Artist>] artists                The artists of the album
+  # @attr [Array<String>] available_markets      The markets in which the album is available: {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
+  # @attr [Hash]          external_ids           Known external IDs for the album
+  # @attr [Array<String>] genres                 A list of the genres used to classify the album (If not yet classified, the array is empty)
+  # @attr [Array<Hash>]   images                 The cover art for the album in various sizes, widest first
+  # @attr [String]        name                   The name of the album
+  # @attr [Integer]       popularity             The popularity of the album - The value will be between 0 and 100, with 100 being the most popular
+  # @attr [String]        release_date           The date the album was first released, for example "1981-12-15" - Depending on the precision, it might be shown as "1981" or "1981-12"
+  # @attr [String]        release_date_precision The precision with which release_date value is known: "year", "month", or "day"
+  # @attr [Array<Track>]  tracks                 The tracks of the album.
   class Album < Base
 
+    # Returns Album object(s) with id(s) provided
+    #
+    # @param ids [String, Array]
+    # @return [Album, Array<Album>]
+    #
+    # @example
+    #           album = RSpotify::Album.find('41vPD50kQ7JeamkxQW7Vuy')
+    #           album.class #=> RSpotify::Album
+    #           album.name  #=> "AM"
+    #           
+    #           ids = %w(41vPD50kQ7JeamkxQW7Vuy 4jKGRliQXa5VwxKOsiCbfL)
+    #           albums = RSpotify::Album.find(ids)
+    #           albums.class       #=> Array
+    #           albums.first.class #=> RSpotify::Album
     def self.find(ids)
       super(ids, 'album')
     end
 
+    # Returns array of Album objects matching the query, ordered by popularity
+    #
+    # @param query [String]
+    # @param limit [Integer]
+    # @param offset [Integer]
+    # @return [Array<Album>]
+    #
+    # @example
+    #           albums = RSpotify::Album.search('AM')
+    #           albums.size        #=> 20
+    #           albums.first.class #=> RSpotify::Album
+    #           albums.first.name  #=> "AM"
+    #
+    #           albums = RSpotify::Base.search('AM', 10)
+    #           albums.size #=> 10
     def self.search(query, limit = 20, offset = 0)
       super(query, 'album', limit, offset)
     end

data/lib/rspotify/artist.rb

@@ -1,11 +1,44 @@
 module RSpotify
 
+  # @attr [Array<String>] genres     A list of the genres used to classify the album (If not yet classified, the array is empty)
+  # @attr [Array<Hash>]   images     The cover art for the album in various sizes, widest first
+  # @attr [String]        name       The name of the album
+  # @attr [Integer]       popularity The popularity of the album - The value will be between 0 and 100, with 100 being the most popular
   class Artist < Base
 
+    # Returns Artist object(s) with id(s) provided
+    #
+    # @param ids [String, Array]
+    # @return [Artist, Array<Artist>]
+    #
+    # @example
+    #           artist = RSpotify::Artist.find('7Ln80lUS6He07XvHI8qqHH')
+    #           artist.class #=> RSpotify::Artist
+    #           artist.name  #=> "Arctic Monkeys"
+    #           
+    #           ids = %w(7Ln80lUS6He07XvHI8qqHH 3dRfiJ2650SZu6GbydcHNb)
+    #           artists = RSpotify::Artist.find(ids)
+    #           artists.class       #=> Array
+    #           artists.first.class #=> RSpotify::Artist
     def self.find(ids)
       super(ids, 'artist')
     end
 
+    # Returns array of Artist objects matching the query, ordered by popularity
+    #
+    # @param query [String]
+    # @param limit [Integer]
+    # @param offset [Integer]
+    # @return [Array<Artist>]
+    #
+    # @example
+    #           artists = RSpotify::Artist.search('Arctic')
+    #           artists.size        #=> 20
+    #           artists.first.class #=> RSpotify::Artist
+    #           artists.first.name  #=> "Arctic Monkeys"
+    #
+    #           artists = RSpotify::Artist.search('Arctic', 10)
+    #           artists.size #=> 10
     def self.search(query, limit = 20, offset = 0)
       super(query, 'artist', limit, offset)
     end
@@ -20,12 +53,31 @@ module RSpotify
       super(options)
     end
 
+    # Returns all albums from artist
+    #
+    # @return [Array<Album>]
+    #
+    # @example
+    #           albums = artist.albums
+    #           albums.class       #=> Array
+    #           albums.first.class #=> RSpotify::Album
+    #           albums.first.name  #=> "AM"
     def albums
       return @albums unless @albums.nil?
       json = RSpotify.get("artists/#{@id}/albums")
       @albums = json['items'].map { |a| Album.new a }
     end
 
+    # Returns artist's 10 top tracks by country.
+    #
+    # @param country [Symbol] an {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}
+    # @return [Array<Track>]
+    #
+    # @example
+    #           top_tracks = artist.top_tracks(:US)
+    #           top_tracks.class       #=> Array
+    #           top_tracks.size        #=> 10
+    #           top_tracks.first.class #=> RSpotify::Track
     def top_tracks(country)
       return @top_tracks[country] unless @top_tracks[country].nil?
       json = RSpotify.get("artists/#{@id}/top-tracks?country=#{country}")

data/lib/rspotify/base.rb

@@ -1,28 +1,80 @@
 module RSpotify
 
+  # @attr [Hash]   external_urls Known external URLs for object
+  # @attr [String] href          A link to the Web API endpoint
+  # @attr [String] id            The {https://developer.spotify.com/web-api/user-guide/#spotify-uris-and-ids Spotify ID} for the object
+  # @attr [String] type          The object type (artist, album, etc.)
+  # @attr [String] uri           The {https://developer.spotify.com/web-api/user-guide/#spotify-uris-and-ids Spotify URI} for the object
   class Base
 
+    # Returns RSpotify object(s) with id(s) and type provided
+    #
+    # @param ids [String, Array]
+    # @param type [String]
+    # @return [Album, Artist, Track, User, Array<Album>, Array<Artist>, Array<Track>]
+    #
+    # @example
+    #           user = RSpotify::Base.find('wizzler', 'user')
+    #           user.class #=> RSpotify::User
+    #           user.id    #=> "wizzler"
+    #           
+    #           ids = %w(2UzMpPKPhbcC8RbsmuURAZ 7Jzsc04YpkRwB1zeyM39wE)
+    #           tracks = RSpotify::Base.find(ids, 'track')
+    #           tracks.class       #=> Array
+    #           tracks.first.class #=> RSpotify::Track
     def self.find(ids, type)
-      pluralized_type = "#{type}s"
-      path = pluralized_type.dup
-      type_class = eval type.capitalize
-
       case ids.class.to_s
       when 'Array'
-        path << "?ids=#{ids.join ','}"
-        json = RSpotify.get path
-        json[pluralized_type].map { |t| type_class.new t }
+        if type == 'user'
+          warn 'Spotify API does not support finding several users simultaneously'
+          return false
+        end
+        find_many(ids, type)
       when 'String'
         id = ids
-        path << "/#{id}"
-        json = RSpotify.get path
-        type_class.new json
+        find_one(id, type)
       end
     end
 
+    def self.find_many(ids, type)
+      pluralized_type = "#{type}s"
+      type_class = RSpotify.const_get(type.capitalize)
+
+      path = "#{pluralized_type}?ids=#{ids.join ','}"
+      json = RSpotify.get path
+      json[pluralized_type].map { |t| type_class.new t }
+    end
+    private_class_method :find_many
+
+    def self.find_one(id, type)
+      pluralized_type = "#{type}s"
+      type_class = RSpotify.const_get(type.capitalize)
+
+      path = "#{pluralized_type}/#{id}"
+      json = RSpotify.get path
+      type_class.new json
+    end
+    private_class_method :find_one
+
+    # Returns array of RSpotify objects matching the query, ordered by popularity
+    #
+    # @param query [String]
+    # @param type [String]
+    # @param limit [Integer]
+    # @param offset [Integer]
+    # @return [Array<Album>, Array<Artist>, Array<Track>]
+    #
+    # @example
+    #           artists = RSpotify::Base.search('Arctic', 'artist')
+    #           artists.size        #=> 20
+    #           artists.first.class #=> RSpotify::Artist
+    #           artists.first.name  #=> "Arctic Monkeys"
+    #
+    #           albums = RSpotify::Base.search('AM', 'album', 10)
+    #           albums.size #=> 10
     def self.search(query, type, limit = 20, offset = 0)
       pluralized_type = "#{type}s"
-      type_class = eval type.capitalize
+      type_class = RSpotify.const_get(type.capitalize)
 
       json = RSpotify.get 'search',
         params: {
@@ -44,14 +96,34 @@ module RSpotify
       @uri           = options['uri']
     end
 
+    # When an object is obtained undirectly, Spotify usually returns a simplified version of it.
+    # This method updates it into a full object, with all attributes filled.
+    # 
+    # @note It is seldom necessary to use this method explicitly, since RSpotify takes care of it automatically when needed (see {#method_missing})
+    #
+    # @example
+    #           track = artist.tracks.first
+    #           track.instance_variable_get("@popularity") #=> nil
+    #           track.complete!
+    #           track.instance_variable_get("@popularity") #=> 62
     def complete!
-      pluralized_type = "#{type}s"
+      pluralized_type = "#{@type}s"
       initialize RSpotify.get("#{pluralized_type}/#{@id}")
     end
 
+    # Used internally to retrieve an object's instance variable. If instance
+    # variable equals nil, calls {#complete!} on object and retrieve it again.
+    #
+    # @example
+    #           user.id #=> "wizzler"
+    #
+    #           track = artist.tracks.first
+    #           track.instance_variable_get("@popularity") #=> nil
+    #           track.popularity #=> 62
+    #           track.instance_variable_get("@popularity") #=> 62
     def method_missing(method_name, *args)
-      attr = "@#{method_name}".to_sym
-      super unless instance_variables.include? attr 
+      attr = "@#{method_name}"
+      super unless instance_variable_defined? attr 
 
       attr_value = instance_variable_get attr 
       return attr_value unless attr_value.nil?
@@ -60,9 +132,10 @@ module RSpotify
       instance_variable_get attr 
     end
 
-    def respond_to?(method_name)
-      attr = "@#{method_name}".to_sym
-      return true if instance_variables.include? attr
+    # Overrides Object#respond_to? to also consider methods dynamically generated by {#method_missing}
+    def respond_to?(method_name, include_private_methods = false)
+      attr = "@#{method_name}"
+      return true if instance_variable_defined? attr
       super
     end
   end

data/lib/rspotify/playlist.rb

@@ -1,14 +1,34 @@
 module RSpotify
 
+  # @attr [Boolean]      collaborative true if the owner allows other users to modify the playlist
+  # @attr [String]       description   The playlist description
+  # @attr [Hash]         followers     Information about the followers of the playlist
+  # @attr [Array<Hash>]  images        The playlist images
+  # @attr [String]       name          The name of the playlist
+  # @attr [User]         owner         The user who owns the playlist
+  # @attr [Boolean]      public        true if the playlist is not marked as secret
+  # @attr [Array<Track>] tracks        The tracks of the playlist
   class Playlist < Base
 
+    # Returns Playlist object with user_id and id provided
+    #
+    # @param user_id [String]
+    # @param id [String]
+    # @return [Playlist]
+    #
+    # @example
+    #           playlist = RSpotify::Playlist.find('wizzler', '00wHcTN0zQiun4xri9pmvX')
+    #           playlist.class #=> RSpotify::Playlist
+    #           playlist.name  #=> "Movie Soundtrack Masterpieces"
     def self.find(user_id, id)
       json = RSpotify.auth_get("users/#{user_id}/playlists/#{id}")
       Playlist.new json
     end
 
-    def self.search
-      #TODO
+    # Spotify does not support search for playlists. Prints warning and returns false
+    def self.search(*args)
+      warn 'Spotify API does not support search for playlists'
+      false
     end
 
     def initialize(options = {})
@@ -30,6 +50,16 @@ module RSpotify
       super(options)
     end
 
+    # When an object is obtained undirectly, Spotify usually returns a simplified version of it.
+    # This method updates it into a full object, with all attributes filled.
+    # 
+    # @note It is seldom necessary to use this method explicitly, since RSpotify takes care of it automatically when needed (see {Base#method_missing})
+    #
+    # @example
+    #           playlist = user.playlists.first
+    #           playlist.instance_variable_get("@description") #=> nil
+    #           playlist.complete!
+    #           playlist.instance_variable_get("@description") #=> "Iconic soundtracks..."
     def complete!
       initialize RSpotify.auth_get("users/#{@owner.id}/playlists/#{@id}")
     end

data/lib/rspotify/track.rb

@@ -1,11 +1,51 @@
 module RSpotify
 
+  # @attr [Album]         album             The album on which the track appears
+  # @attr [Array<Artist>] artists           The artists who performed the track
+  # @attr [Array<String>] available_markets The markets in which the track can be played: {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
+  # @attr [Integer]       disc_number       The disc number (usually 1 unless the album consists of more than one disc)
+  # @attr [Integer]       duration_ms       The track length in milliseconds
+  # @attr [Boolean]       explicit          Whether or not the track has explicit lyrics (true = yes it does; false = no it does not OR unknown)
+  # @attr [Hash]          external_ids      Known external IDs for the track
+  # @attr [String]        name              The name of the track
+  # @attr [Integer]       popularity        The popularity of the track - The value will be between 0 and 100, with 100 being the most popular
+  # @attr [String]        preview_url       A link to a 30 second preview (MP3 format) of the track
+  # @attr [Integer]       track_number      The number of the track - If an album has several discs, the track number is the number on the specified disc
   class Track < Base
 
+    # Returns Track object(s) with id(s) provided
+    #
+    # @param ids [String, Array]
+    # @return [Track, Array<Track>]
+    #
+    # @example
+    #           track = RSpotify::Track.find('2UzMpPKPhbcC8RbsmuURAZ')
+    #           track.class #=> RSpotify::Track
+    #           track.name  #=> "Do I Wanna Know?"
+    #           
+    #           ids = %w(2UzMpPKPhbcC8RbsmuURAZ 7Jzsc04YpkRwB1zeyM39wE)
+    #           tracks = RSpotify::Base.find(ids, 'track')
+    #           tracks.class       #=> Array
+    #           tracks.first.class #=> RSpotify::Track
     def self.find(ids)
       super(ids, 'track')
     end
 
+    # Returns array of Track objects matching the query, ordered by popularity
+    #
+    # @param query [String]
+    # @param limit [Integer]
+    # @param offset [Integer]
+    # @return [Array<Track>]
+    #
+    # @example
+    #           tracks = RSpotify::Track.search('Thriller')
+    #           tracks.size        #=> 20
+    #           tracks.first.class #=> RSpotify::Track
+    #           tracks.first.name  #=> "Thriller"
+    #
+    #           tracks = RSpotify::Track.search('Thriller', 10)
+    #           tracks.size #=> 10
     def self.search(query, limit = 20, offset = 0)
       super(query, 'track', limit, offset)
     end

data/lib/rspotify/user.rb

@@ -2,22 +2,38 @@ module RSpotify
 
   class User < Base
 
+    # Returns User object with id provided
+    #
+    # @param ids [String]
+    # @return [User]
+    #
+    # @example
+    #           user = RSpotify::User.find('wizzler')
+    #           user.class #=> RSpotify::User
+    #           user.id    #=> "wizzler"
     def self.find(id)
-      if id.is_a? Array
-        warn 'Spotify API does not support finding several users simultaneously'
-        return false
-      end
       super(id, 'user')
     end
 
-    def self.search
-      #TODO
+    # Spotify does not support search for users. Prints warning and returns false
+    def self.search(*args)
+      warn 'Spotify API does not support search for users'
+      false
     end
 
     def initialize(options = {})
       super(options)
     end
 
+    # Returns all playlists from user
+    #
+    # @return [Array<Playlist>]
+    #
+    # @example
+    #           playlists = user.playlists
+    #           playlists.class       #=> Array
+    #           playlists.first.class #=> RSpotify::Playlist
+    #           playlists.first.name  #=> "Movie Soundtrack Masterpieces"
     def playlists
       return @playlists unless @playlists.nil?
       playlists = RSpotify.auth_get("users/#{@id}/playlists")['items']

data/lib/rspotify/version.rb

@@ -1,3 +1,3 @@
 module RSpotify
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspotify
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Guilherme Sad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-23 00:00:00.000000000 Z
+date: 2014-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest_client