pandata 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 41b8bbfd247c0f180d0d3db4c385a9780d67f3af
-  data.tar.gz: 25e9aa7769864eae1bbb5c37f8157ed4905b1234
+  metadata.gz: b110672f1843569186fff6c0c073defe047b0932
+  data.tar.gz: bf753689e76d89c1b0ce7a92e1c2491f6d021392
 SHA512:
-  metadata.gz: f498522a3bedfb5234bd1ae76a0655ca8ea2c997e44665e7920c2e2d65a664c023246cbedb08803eff016691edcd487722bc717bd70646e0bf5be76397a255f8
-  data.tar.gz: 47cf7b5378e3bd2d9ceaa38388f24c90afc01921d409003844a9436de3045951d01060fec9d707565eb8c923eb7880b7f1593a37f9c51c5ca7d920a7c30efd91
+  metadata.gz: 0aa2816fa28182cf3bce1f1a813663624279095ff2de56922afa58b110b3e26faa0b661fc1a33df416d90d64c08b3e741174806521d7d65fedf03afa293bb438
+  data.tar.gz: 79cd4ce5b6a65d08585164040d39dd6a952cb8a5fd65ab55023ab4aaf6aaa402e063af7105eb977fd904ee12d6a90ce7bc10d388525c00070840392abac91129

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Brian Ustas 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# Pandata
+
+Pandata is a Ruby 1.9+ library for downloading a user's Pandora.com data. This data includes:
+
+- Playing Station *
+- Recent Activity *
+- Stations *
+- Bookmarks (artists, tracks) *
+- Likes (albums, artists, stations, tracks)
+- Followers
+- Following
+
+Where possible, Pandora [feeds][1] are used (indicated by an * above).
+
+Pandata can only access **public** Pandora profiles. This option can be changed in Pandora's settings.
+
+## Installing
+
+Pandata is a Ruby gem. To install, execute:
+
+    gem install pandata
+
+This also installs a command-line tool called 'pandata'.
+
+## Usage
+
+Pandata can be used as a Ruby library or command-line tool.
+
+To identify a user, you must supply either an email address or a webname.
+
+A **webname** is what Pandora uses to identify a user and it remains constant even if the user ties a new email address to their Pandora account.
+To find your webname, go to 'My Profile' and you'll see your webname in the URL. For example:
+
+pandora.com/profile/\<my_webname\>
+
+### As a Library
+
+First, create a new Pandata scraper for a user:
+
+    require 'pandata'
+    
+    # Scraper.get takes either an email or a webname.
+    # Returns an array of similar webnames if no match is found.
+    johns_scraper = Pandata::Scraper.get('john@example.com')
+
+Next, start scraping!
+
+    # Get only liked tracks
+    likes = johns_scraper.likes(:tracks)
+
+    # Get all bookmarks (artists and tracks)
+    bookmarks = johns_scraper.bookmarks
+
+    # Get all stations
+    stations = johns_scraper.stations
+
+    # Get all followers
+    followers = johns_scraper.followers
+
+For more information, see the documentation for Pandata::Scraper.
+
+### As a Command-Line Tool
+
+All output is sorted alphabetically, duplicates are removed and tracks are grouped under their owning artist.
+
+    pandata <email|webname> [options]
+
+**Options:**
+
+For an up-to-date list, check out:
+
+    pandata --help
+
+**Examples:**
+
+    pandata john@example.com --liked_tracks
+
+    # Get liked tracks, artists and bookmarked tracks + output as JSON.
+    pandata my_webname -lLb --json
+
+    # Get all data and output to a file.
+    pandata my_webname --all -o my_pandora_data.txt
+
+[1]: http://www.pandora.com/feeds

data/lib/pandata.rb

@@ -9,7 +9,7 @@ module Pandata
   module Version
     MAJOR = 0
     MINOR = 1
-    PATCH = 1
+    PATCH = 2
     BUILD = nil
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')

data/lib/pandata/argv_parser.rb

@@ -5,18 +5,17 @@ module Pandata
 
   # Parses command-line input.
   class ArgvParser
-    # Prevent instances
     private_class_method :new
 
-    # Takes an ARGV (array) argument.
-    #
-    # Returns a hash with:
-    # - :opts (OptionParser object)
-    # - :user_id (string)
-    # - :output_file (string)
-    # - :data_to_get (array)
-    # - :get_all_data (boolean)
-    # - :return_as_json (boolean)
+    # Parses an ARGV array for options.
+    # @param argv [Array] an ARGV array
+    # @return [Hash]
+    #   - :opts [OptionParser]
+    #   - :user_id [String]
+    #   - :output_file [String]
+    #   - :data_to_get [Array]
+    #   - :get_all_data [Boolean]
+    #   - :return_as_json [Boolean]
     def self.parse(argv)
       options = { data_to_get: [] }
       get_all_data = false
@@ -127,5 +126,6 @@ Options:
 
       options
     end
+
   end
 end

data/lib/pandata/data_formatter.rb

@@ -5,15 +5,8 @@ module Pandata
   # Sorts and formats Pandata::Scraper data as a string for printing.
   class DataFormatter
 
-    # Takes an array or string and returns a string with each item on its own line.
-    #--
-    #
-    # Example output:
-    # - item1
-    # - item2
-    # - item3
-    #
-    #++
+    # @param data [Array, String]
+    # Returns a string with each array item on its own line.
     def list(data)
       data = [data] unless data.kind_of?(Array)
       str = ''
@@ -22,21 +15,25 @@ module Pandata
     end
 
     # Identical to #list but sorts alphabetically ignoring 'the'.
+    # @param data [Array]
     def sort_list(data)
       list custom_sort(data)
     end
 
-    # Takes an array of hashes with :artist and :track keys.
+    # @param tracks [Array] array of hashes with :artist and :track keys
+    # Returns a string with tracks grouped under owning artist.
     def tracks(tracks)
       artists_items(tracks, :track)
     end
 
-    # Takes an array of hashes with :artist and :album keys.
+    # @param albums [Array] array of hashes with :artist and :album keys
+    # Returns a string with albums grouped under owning artist.
     def albums(albums)
       artists_items(albums, :album)
     end
 
-    # Takes an array of hashes with :name, :webname and :href keys.
+    # @param data [Array] array of hashes with :name, :webname and :href keys
+    # Returns a string with followers/ing sorted by webname.
     def followx(data)
       str = ''
       data.sort_by { |item| item[:webname].downcase }.each do |hash|
@@ -49,11 +46,14 @@ module Pandata
 
     private
 
-    # Takes an array or hash.
     # Sorts alphabetically ignoring the initial 'The' when sorting strings.
     # Also case-insensitive to prevent lowercase names from being sorted last.
+    # @param enumerable [Array, Hash]
+    # @return [Array, Hash]
     def custom_sort(enumerable)
-      sorted_array = enumerable.sort_by { |key, _| key.sub(/^the\s*/i, '').downcase }
+      sorted_array = enumerable.sort_by do |key, _|
+        key.sub(/^the\s*/i, '').downcase
+      end
 
       # sort_by() returns an array when called on hashes.
       if enumerable.kind_of?(Hash)
@@ -66,21 +66,9 @@ module Pandata
       end
     end
 
-    # Takes an array of hashes with :artist and another key belonging to an
-    # artist (e.g. :track or :album).
-    # Returns a string with each artist name on a line with the artist's items
-    # listed and indented below. Sorts the output, too.
-    #--
-    #
-    # Example output:
-    # - Artist1:
-    #   - item2
-    #   - item3
-    # - Artist2:
-    #   - item1
-    #   - item1
-    #
-    #++
+    # @param data [Array] array of hashes with :artist and item_name
+    # @param item_name [Symbol] e.g. :track or :album
+    # Returns a string with items grouped under their owning artist.
     def artists_items(data, item_name)
       artists_items = {}
 

data/lib/pandata/downloader.rb

@@ -2,11 +2,9 @@ require 'json'
 require 'open-uri'
 
 module Pandata
-  # Custom Pandata error
-  class PandataError < StandardError
-  end
+  class PandataError < StandardError; end
 
-  # Retrieves data from Pandora and handles errors.
+  # Retrieves data from Pandora.com and handles errors.
   class Downloader
     # A GitHub Gist that contains an updated cookie allowing access to 'login-only' visible data.
     CONFIG_URL = 'https://gist.github.com/ustasb/596f1ee96d03463fde77/raw/pandata_config.json'
@@ -17,13 +15,14 @@ module Pandata
 
     # Gets a Pandora cookie and returns a Downloader instance.
     def initialize
-      # If we already have a cookie, don't get another.
       unless Downloader.cookie
         Downloader.cookie = get_cookie
       end
     end
 
-    # Downloads a page and returns its content as a string.
+    # Downloads and reads a page from a URL.
+    # @param url [String]
+    # @return [String] contents of page
     def read_page(url)
       download(url, Downloader.cookie).read
     end
@@ -31,6 +30,9 @@ module Pandata
     private
 
     # Downloads a page and handles errors.
+    # @param url [String]
+    # @param cookie [String]
+    # @return [File]
     def download(url, cookie = '')
       escaped_url = URI.escape(url)
 

data/lib/pandata/parser.rb

@@ -5,7 +5,9 @@ module Pandata
   # Parses HTML/XML pages from Pandora for relevant data.
   class Parser
 
-    # Returns an array of webnames.
+    # Get the webnames from a user ID search.
+    # @param html [String]
+    # @return [Array] array of webnames
     def get_webnames_from_search(html)
       user_links = Nokogiri::HTML(html).css('.user_name a')
       webnames = []
@@ -17,8 +19,9 @@ module Pandata
       webnames
     end
 
-    # Returns the query parameters necessary to get the next page of data
-    # from Pandora.
+    # Get the query parameters necessary to get the next page of data from Pandora.
+    # @param html [String]
+    # @return [Hash, False]
     def get_next_data_indices(html)
       show_more = Nokogiri::HTML(html).css('.show_more')[0]
 
@@ -36,7 +39,8 @@ module Pandata
       end
     end
 
-    # Returns an array of recent activities.
+    # @param xml [String]
+    # Returns an array of recent activity names.
     def get_recent_activity(xml)
       activity_names = []
 
@@ -47,6 +51,7 @@ module Pandata
       activity_names
     end
 
+    # @param xml [String]
     # Returns an array of station names.
     def get_stations(xml)
       stations = []
@@ -58,7 +63,8 @@ module Pandata
       stations
     end
 
-    # Returns the currently playing station name.
+    # @param xml [String]
+    # @return [String]
     def get_playing_station(xml)
       station = ''
 
@@ -70,6 +76,7 @@ module Pandata
       station
     end
 
+    # @param xml [String]
     # Returns an array of hashes with :artist and :track keys.
     def get_bookmarked_tracks(xml)
       tracks = []
@@ -82,6 +89,7 @@ module Pandata
       tracks
     end
 
+    # @param xml [String]
     # Returns an array of artist names.
     def get_bookmarked_artists(xml)
       artists = []
@@ -93,6 +101,7 @@ module Pandata
       artists
     end
 
+    # @param html [String]
     # Returns an array of hashes with :artist and :track keys.
     def get_liked_tracks(html)
       tracks = []
@@ -104,16 +113,19 @@ module Pandata
       tracks
     end
 
+    # @param html [String]
     # Returns an array of artist names.
     def get_liked_artists(html)
       get_infobox_titles(html)
     end
 
+    # @param html [String]
     # Returns an array of station names.
     def get_liked_stations(html)
       get_infobox_titles(html)
     end
 
+    # @param html [String]
     # Returns an array of hashes with :artist and :album keys.
     def get_liked_albums(html)
       albums = []
@@ -125,11 +137,13 @@ module Pandata
       albums
     end
 
+    # @param html [String]
     # Returns an array of hashes with :name, :webname and :href keys.
     def get_following(html)
       get_followx_users(html)
     end
 
+    # @param html [String]
     # Returns an array of hashes with :name, :webname and :href keys.
     def get_followers(html)
       get_followx_users(html)
@@ -138,6 +152,7 @@ module Pandata
     private
 
     # Loops over each 'item' tag and yields the title and description.
+    # @param xml [String]
     def xml_each_item(xml)
       Nokogiri::XML(xml).css('item').each do |item|
         title = item.at_css('title').text
@@ -147,6 +162,7 @@ module Pandata
     end
 
     # Loops over each .infobox container and yields the title and subtitle.
+    # @param html [String]
     def infobox_each_link(html)
       Nokogiri::HTML(html).css('.infobox').each do |infobox|
         infobox_body = infobox.css('.infobox-body')
@@ -159,6 +175,7 @@ module Pandata
       end
     end
 
+    # @param html [String]
     # Returns an array of titles from #infobox_each_link.
     def get_infobox_titles(html)
       titles = []
@@ -166,8 +183,9 @@ module Pandata
       titles
     end
 
-    # Loops over each .follow_section container and returns a hash with
-    # :name, :webname and :href keys.
+    # Loops over each .follow_section container.
+    # @param html [String]
+    # @return [Hash] with keys :name, :webname and :href
     def get_followx_users(html)
       users = []
 

data/lib/pandata/scraper.rb

@@ -12,10 +12,11 @@ module Pandata
     # the user ties a new email address to their Pandora account.
     attr_reader :webname
 
-    # Takes either an email or a webname string.
-    # Returns either:
-    # - a new scraper object for the supplied user ID.
-    # - an array of similar webnames because a matching Pandora user could not be found.
+    # If possible, get a Scraper instance for the user_id otherwise return
+    # an array of similar webnames.
+    # @param user_id [String] email or webname
+    # @return [Scraper] a scraper object for the supplied user ID
+    # @return [Array] array of similar webnames
     def self.get(user_id)
       search_url = DATA_FEED_URLS[:user_search] % { searchString: user_id }
       html = Downloader.new.read_page(search_url)
@@ -38,27 +39,29 @@ module Pandata
       @webname = webname
     end
 
-    # Returns an array of the user's recent activity.
+    # Get the user's recent activity.
+    # @return [Array] array of activity names
     def recent_activity
       scrape_for(:recent_activity, :get_recent_activity)
     end
 
-    # Returns the user's currently playing station.
+    # Get the user's playing station.
+    # @return [String]
     def playing_station
       scrape_for(:playing_station, :get_playing_station).first
     end
 
-    # Returns an array of the user's stations.
+    # Get the user's stations.
+    # @return [Array] array of station names
     def stations
       scrape_for(:stations, :get_stations)
     end
 
-    # Returns a user's bookmarked data.
-    #
-    # Bookmark types:
-    # - :artists - Returns an array of artist names.
-    # - :tracks - Returns an array of hashes with :artist and :track keys.
-    # - :all - Returns a hash with all bookmarked data.
+    # Get the user's bookmarked data.
+    # @param bookmark_type [Symbol]
+    #   - :artists - returns an array of artist names
+    #   - :tracks - returns an array of hashes with :artist and :track keys
+    #   - :all - returns a hash with all bookmarked data
     def bookmarks(bookmark_type = :all)
       case bookmark_type
       when :tracks
@@ -71,14 +74,13 @@ module Pandata
       end
     end
 
-    # Returns a user's liked data. (The results from giving a 'thumbs up.')
-    #
-    # Like types:
-    # - :artists - Returns an array of artist names.
-    # - :albums - Returns an array of album names.
-    # - :stations - Returns an array of station names.
-    # - :tracks - Returns an array of hashes with :artist and :track keys.
-    # - :all - Returns a hash with all liked data.
+    # Get the user's liked data. (The results from giving a 'thumbs up.')
+    # @param like_type [Symbol]
+    #   - :artists - returns an array of artist names
+    #   - :albums - returns an array of hashes with :artist and :album keys
+    #   - :stations - returns an array of station names
+    #   - :tracks - returns an array of hashes with :artist and :track keys
+    #   - :all - returns a hash with all liked data
     def likes(like_type = :all)
       case like_type
       when :tracks
@@ -97,17 +99,17 @@ module Pandata
       end
     end
 
-    # Returns the *public* users being followed by the user.
-    #
-    # Returns an array of hashes with keys:
-    # - :name - Profile name
-    # - :webname - Unique Pandora ID
-    # - :href - URL to online Pandora profile.
+    # Get the *public* users being followed by the user.
+    # @return [Array] array of hashes with keys:
+    #   - :name - profile name
+    #   - :webname - unique Pandora ID
+    #   - :href - URL to online Pandora profile
     def following
       scrape_for(:following, :get_following)
     end
 
-    # Returns the user's followers in a format identical to #following.
+    # Get the user's *public* followers.
+    # @return [Array] identical to #following
     def followers
       scrape_for(:followers, :get_followers)
     end
@@ -116,6 +118,9 @@ module Pandata
 
     # Downloads all data for a given type, calls the supplied Pandata::Parser
     # method and removes any duplicates.
+    # @param data_type [Symbol]
+    # @param parser_method [Symbol] method to be sent to the Parser instance
+    # @return [Array]
     def scrape_for(data_type, parser_method)
       results = []
 
@@ -139,6 +144,7 @@ module Pandata
     # Downloads all data given a starting URL. Some Pandora feeds only return
     # 5 - 10 items per page but contain a link to the next set of data. Threads
     # cannot be used because page A be must visited to know how to obtain page B.
+    # @param url [String]
     def download_all_data(url)
       next_data_indices = {}
 
@@ -150,6 +156,8 @@ module Pandata
     end
 
     # Grabs a URL from DATA_FEED_URLS and formats it appropriately.
+    # @param data_name [Symbol]
+    # @param next_data_indices [Symbol] query parameters to get the next set of data
     def get_url(data_name, next_data_indices = {})
       next_data_indices = {
         nextStartIndex: 0,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pandata
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Brian Ustas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-11 00:00:00.000000000 Z
+date: 2013-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -38,13 +38,29 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.12.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.5
 description: A library and tool for downloading Pandora.com data (likes, bookmarks,
   stations, etc.)
 email: brianustas@gmail.com
 executables:
 - pandata
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- LICENSE
+- README.md
 files:
 - lib/pandata/argv_parser.rb
 - lib/pandata/data_formatter.rb
@@ -53,6 +69,8 @@ files:
 - lib/pandata/parser.rb
 - lib/pandata/scraper.rb
 - lib/pandata.rb
+- LICENSE
+- README.md
 - bin/pandata
 homepage: https://github.com/ustasb/pandata
 licenses: