tiegz-ruby-mtv 1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Tieg Zaharia
+
+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

@@ -0,0 +1,52 @@
+ruby-mtv
+    by Tieg Zaharia
+    http://github.com/tiegz/ruby-mtv
+ 
+== DESCRIPTION:
+ 
+This is a Ruby library for the MTV api. Right now it has classes for Artists and Videos, although
+there is much to be done, spec'd and/or tested!
+ 
+== REQUIREMENTS:
+ 
+* git (http://git.or.cz) tested with 1.5.3.4
+ 
+== INSTALL:
+ 
+  $ gem sources -a http://gems.github.com/ (you only need to do this once)
+  $ gem install tiegz-ruby-mtv
+ 
+== USAGE:
+
+Require the gem...
+
+  require 'tiegz-ruby-mtv'
+
+To find an artist,
+
+  artist = MTV::Artist.search('dinosaur jr').first
+  # => #<MTV::Artist name: "Dinosaur Jr.", uid: "dinosaur_jr", uri: "http://api.mtvnservices.com/1/artist/dinosaur_jr/">
+
+To find related artists,
+
+  artist.related
+  # => [#<MTV::Artist name: "Afghan Whigs", uid: "afghan_whigs", uri: "http://api.mtvnservices.com/1/artist/afghan_whigs/">, 
+        #<MTV::Artist name: "The Breeders", uid: "breeders", uri: "http://api.mtvnservices.com/1/artist/breeders/">, ... ]
+
+To find a video,
+
+  video = MTV::Video.search('dinosaur jr').first
+  # => #<MTV::Video title: "Been There All the Time", uid: "hznHivqrbHHDAXBAZ", artist_name: "Dinosaur Jr.", 
+                    uri: "http://api.mtvnservices.com/1/video/hznHivqrbHHDAXB...", 
+                    artist_uri: "http://api.mtvnservices.com/1/artist/dinosaur_jr/">
+  v.artist
+  # => #<MTV::Artist name: "Dinosaur Jr.", uid: "dinosaur_jr", uri: "http://api.mtvnservices.com/1/artist/dinosaur_jr/">
+
+To find all videos for an artist,
+
+  artist.videos
+  # => [#<MTV::Video title: ["Been There All the Time"], uid: "hznHivqrbHHDAXBAZ", artist_name: ["Dinosaur Jr."] ...>, ... ] 
+
+== RELEVANT LINKS
+
+    MTVN api docs: http://developer.mtvnservices.com/docs

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+
+

data/TODO

@@ -0,0 +1,4 @@
+- Fix edge cases where no string is passed to a #find, #browse, #search, etc. method
+- Add request cacheing
+- Add specs (with mock requests)
+- Better rdocs

data/ruby-mtv.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name     = "ruby-mtv"
+  s.version  = "1.0"
+  s.date     = "2008-09-16"
+  s.summary  = "Ruby wrapper library for MTV api"
+  s.email    = "tiegzaharia@gmail.com"
+  s.homepage = "http://github.com/tiegz/ruby-mtv"
+  s.description = "ruby-mtv is a Ruby library for accessing Artist and Video objects through the MTVN api."
+  s.has_rdoc = true
+  s.authors  = ["Tieg Zaharia"]
+  s.files    = ["MIT-LICENSE",
+    "Rakefile",
+    "README",
+    "ruby-mtv.gemspec",
+    "ruby-mtv.rb",
+    "TODO"]
+  s.test_files = []
+  s.rdoc_options = ["--main", "README"]
+  s.extra_rdoc_files = ["README"]
+  s.add_dependency("active-support", ["> 2.0.2"])
+end

data/ruby-mtv.rb

@@ -0,0 +1,283 @@
+require 'rubygems'
+require 'activesupport'
+require 'open-uri'
+require 'benchmark'
+
+module MTV
+  class Error < StandardError; end
+    
+  class << self
+    attr_accessor :base_url, :host, :protocol, :debug
+
+  end
+
+  self.host = "api.mtvnservices.com/1"
+  self.protocol = "http"
+  self.base_url = "#{protocol}://#{host}"
+  self.debug = true if ENV['DEBUG']
+  
+  class Base
+    def initialize(values={})
+      values.each { |k, v| send "#{k}=", v }
+    end
+
+    class << self
+      def request path
+        url = URI.escape "#{MTV.base_url}/#{path}"
+        response = nil
+        seconds = Benchmark.realtime { response = open url }
+        puts "  \e[4;36;1mREQUEST (#{sprintf("%f", seconds)})\e[0m   \e[0;1m#{url}\e[0m" if MTV.debug
+        response.is_a?(String) ? response : response.read
+      rescue OpenURI::HTTPError => e
+        puts "  \e[4;36;1mREQUEST (404)\e[0m   \e[0;1m#{url}\e[0m" if MTV.debug
+        nil
+      end
+    
+      protected
+      # assuming that the uid for the artist is downcase and no spaces, this tries to match better
+      def string_to_uid(str)
+        str.downcase.underscore.gsub(" ", "_")
+      end
+    end
+    
+    # Copied from ActiveRecord::Base
+    def attribute_for_inspect(attr_name)
+      value = send(attr_name)
+
+      if value.is_a?(String) && value.length > 50
+        "#{value[0..50]}...".inspect
+      elsif value.is_a?(Date) || value.is_a?(Time)
+        %("#{value.to_s(:db)}")
+      else
+        value.inspect
+      end
+    end
+  end
+  
+  # This class represents a musical artist in MTV's database.
+  class Artist < Base
+    attr_accessor :name, :uid, :uri, :links, :updated
+
+    def initialize(values={})
+      super(values)
+      self.uid = uri.gsub(MTV.base_url + "/artist", '').delete '/' unless @uid
+    end
+    
+    def inspect
+      attrs = [:name, :uid, :uri].map { |name| "#{name}: #{attribute_for_inspect(name)}" }.compact.join(", ")
+      "#<#{self.class} #{attrs}>"
+    end
+    
+    # artist = MTV::Artist.search('In Flames')[2]
+    # MTV::Artist.browse => I Am Ghost, IB3, INXS, Ice Cube, ...
+    def browse
+      @browse ||= Artist.browse(uid.first)
+    end
+
+    # artist = MTV::Artist.search 'Frank Zappa'
+    # MTV::Artist.browse => Amon Amarth, Amorphis, Arch Enemy, Arcturus, Borknagar, ...
+    def related
+      @related ||= Artist.related(self)
+    end
+    
+    # artist = MTV::Artist.find('beck')
+    # MTV::Artist.videos => ... 
+    def videos
+      @videos ||= Video.from_artist(self)
+    end
+    
+    class << self
+      # MTV::Artist.browse 'x' => X, X-Clan, The X-Ecutioners, Xiren, Xscape, Xtreme, Xzibit
+      def browse(letter='a')
+        response = request "artist/browse/#{letter.to_s.first}/"
+        raise Error, "That artist not found!" if response.nil? || response.empty?
+        parse_many response
+      end
+      
+      # MTV::Artist.find 'beck'
+      # MTV::Artist.find 'meGADeath'
+      def find(name, options={})
+        return name if name.is_a? Artist
+        
+        options.symbolize_keys!
+        name = string_to_uid(options[:name] || name)
+        
+        response = request "artist/#{name}/"
+        raise Error, "That artist not found!" if response.nil? || response.empty?
+        parse_one response
+      end
+      
+      # MTV::Artist.related 'qtip'
+      # MTV::Artist.related MTV::Artist.find('qtip')
+      def related(artist)
+        artist = find(artist)
+        response = request "artist/#{artist.uid}/related/"
+        raise Error, "That artist not found!" if response.nil? || response.empty?
+        parse_many response
+      end
+      
+      # MTV::Artist.search 'beck', :max_results => 1, :start_index => 1
+      def search(term=nil, options={})
+        options.symbolize_keys!
+        params = {}
+        params[:'max-results'] = options[:max_results] || 1
+        params[:'start-index'] = options[:start_index]
+        term                   = options[:term] || term
+        params.reject! { |k,v| !v }
+        response = request "artist/search?#{term.to_query('term')}&#{params.to_param}"
+        raise Error, "That artist not found!" if response.nil? || response.empty?
+        parse_many response
+      end
+      
+      def videos(artist)
+        MTV::Video.from_artist(artist)
+      end
+      
+      protected
+      def parse_many(body)
+        entries = XmlSimple.xml_in(body)['entry']
+        raise Error, "That artist not found!" if entries.nil?
+        entries = [entries] unless entries.is_a? Array
+        entries.map { |entry|
+          instantiate entry
+        }.reject { |artist| MTV::Artist.name.nil? || MTV::Artist.name.empty? }
+      end
+      
+      def parse_one(body)
+        entry = XmlSimple.xml_in(body)
+        raise Error, "That artist not found!" if entry['author'].first['name'].nil? || entry['author'].first['name'].empty?
+        instantiate entry
+      end
+      
+      def instantiate(entry={})
+        Artist.new(:name => entry['author'].first['name'].to_s,
+          :uri => entry['author'].first['uri'].to_s,
+          :links => entry['link'].map { |link| link['href'].to_s },
+          :updated => entry['updated'].to_s.to_datetime)
+      end
+    end
+  end
+
+  # This class represents a music video in MTV's database.
+  class Video < Base
+    attr_accessor :artist, :artist_name, :artist_uri, :category, :content, :credit, 
+                  :media_player_url, :media_thumbnails, :media_title, :media_description,
+                  :media_keywords, :media_duration, :media_expression, :media_url, :media_type, 
+                  :media_credits, :media_category, :media_medium,
+                  :title, :published, :uid, :updated, :uri, :vid
+
+    def initialize(values={})
+      super(values)
+      self.uid = uri.gsub(MTV.base_url + "/video", '').delete '/' unless @uid
+      self.vid = media_url.split(':').last
+    end
+
+    def artist
+      @artist ||= Artist.find(artist_uri.gsub(MTV.base_url + "/artist", '').delete('/'))
+    end
+
+    def inspect
+      attrs = [:title, :uid, :artist_name, :uri, :artist_uri].map { |name| "#{name}: #{attribute_for_inspect(name)}" }.compact.join(", ")
+      "#<#{self.class} #{attrs}>"
+    end
+    
+    def thumbnails=(val)
+      @thumbnails = (val.is_a?(Array) ? val : [val]).map { |t| Thumbnail.new(t['url'], t['width'], t['height']) unless t.nil? }
+    end
+    
+    class << self
+      # MTV::Video.find '1234abcd'
+      def find(uid, options={})
+        return uid if uid.is_a? Artist
+        
+        options.symbolize_keys!
+        uid = options[:uid] || uid
+        
+        response = request "video/#{uid}/"
+        raise Error, "That video not found!" if response.nil? || response.empty?
+        parse_one response
+      end
+
+      # MTV::Video.from_artist(Artist.find('beck'))
+      # MTV::Video.from_artist('beck')
+      def from_artist(artist)
+        artist_uid = artist.is_a?(Artist) ? artist.uid : string_to_uid(artist)
+
+        response = request "artist/#{artist_uid}/videos"
+        raise Error, "No videos found!" if response.nil? || response.empty?
+        parse_many response
+      end
+      
+      # http://api.mtvnservices.com/1/video/search/[parameters]
+      # MTV::Video.search 'the golden age', :max_results => 1, :start_index => 1
+      def search(term=nil, options={})
+        options.symbolize_keys!
+        params = { :'max-results' => (options[:max_results] || 1),
+                   :'start-index' => options[:start_index] }.reject { |k,v| v.nil? || v.to_s.empty? }.to_param
+        params = "&#{params}" unless params.empty?
+        term   = (options[:term] || term).to_query('term')
+
+        response = request "video/search?#{term}#{params}"
+        raise Error, "No videos not found!" if response.nil? || response.empty?
+        parse_many response
+      end
+      
+      protected
+      def parse_many(body)
+        body = hack_media_enclosures(body)
+        entries = XmlSimple.xml_in(body)['entry']
+        entries = [entries] unless entries.is_a? Array
+        entries.reject! { |entry| entry.nil? }
+        entries.map { |entry|
+          instantiate entry
+        }
+      end
+      
+      def parse_one(body)
+        body = hack_media_enclosures(body)
+        entry = XmlSimple.xml_in(body)
+        raise Error, "That artist not found!" if entry['author']['name'].nil? || entry['author']['name'].empty?
+        instantiate entry
+      end
+      
+      # HACK because XmlSimple doesn't seem to handle enclosures, we'll replace colons with hyphens
+      # TODO write a better regexp for that hack :\
+      def hack_media_enclosures(body)
+        body.gsub("<media:", "<media_").gsub("</media:", "</media_")
+      end
+      
+      def instantiate(entry={})
+        Video.new(:title => entry['title'],
+          :artist_uri => entry['author'].first['uri'],
+          :artist_name => entry['author'].first['name'],
+          :published => entry['published'],
+          :content => entry['content'], # Artist Name, Video Title, and Record Label
+          :uri => entry['link'].select { |link| link['rel'] == 'self' }.first['href'],
+          :updated => (entry['updated'].to_datetime rescue nil),
+          :media_category => entry['media_category'], # governing agreement
+          :media_credits => entry['media_credit'].map { |credit| "#{credit['content'] || 'N/A'} (#{credit['role']})}" }.join(', '),
+          :media_description => entry['media_description'],
+          :media_duration => entry['media_content'].first['duration'],
+          :media_expression => entry['media_content'].first['expression'],
+          :media_keywords => entry['media_keywords'],
+          :media_medium => entry['media_content'].first['medium'],
+          :media_player_url => entry['media_player'].first['url'],
+          :media_thumbnails => entry['media_thumbnail'],
+          :media_title => entry['media_title'],
+          :media_type => entry['media_content'].first['type'],
+          :media_url => entry['media_content'].first['url'])
+      end
+    end
+  end
+  
+  class Thumbnail
+    attr_accessor :url, :width, :height
+    def initialize(url, width, height)
+      self.url = url
+      self.width = width
+      self.height = height
+    end
+  end
+
+end
+

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: tiegz-ruby-mtv
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Tieg Zaharia
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-09-16 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: active-support
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 2.0.2
+    version: 
+description: ruby-mtv is a Ruby library for accessing Artist and Video objects through the MTVN api.
+email: tiegzaharia@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- MIT-LICENSE
+- Rakefile
+- README
+- ruby-mtv.gemspec
+- ruby-mtv.rb
+- TODO
+has_rdoc: true
+homepage: http://github.com/tiegz/ruby-mtv
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby wrapper library for MTV api
+test_files: []
+