howcast 0.7.4 → 0.7.15

data/howcast.gemspec

@@ -1,97 +1,38 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "howcast/version"
 
 Gem::Specification.new do |s|
-  s.name = %q{howcast}
-  s.version = "0.7.4"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Jingshen Jimmy Zhang", "Ian Smith-Heisters"]
-  s.date = %q{2010-04-05}
+  s.name        = "howcast"
+  s.version     = Howcast::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jingshen Jimmy Zhang", "Ian Smith-Heisters", "Juris Galang"]
+  s.email       = ["support@howcast.com"]
+  s.homepage    = "http://api.howcast.com/"
+  s.summary     = %q{Ruby-bindings for the Howcast API}
   s.description = %q{    Howcast offers an Application Programming Interface (API) which allows
-    developers to build applications that interface with Howcast. The Howcast
-    API is RESTful (REpresentational State Transfer) and users of this API will
-    be able: 1) Retreive detailed information about a single video, including
-    metadata such as title, description, video views, rating etc; 2) Retrieve a
-    list of videos restricted by a set of filters offered by Howcast and sorted
-    using several metrics that you can specify (most recent, most views, etc);
-    3) Search for video; 4) And much more. Note: Before you can use our APIs,
-    you must register an API key, that is submitted with each request.
-}
-  s.email = %q{support@howcast.com}
-  s.extra_rdoc_files = [
-    "README.markdown"
-  ]
-  s.files = [
-    "CHANGELOG",
-     "License.txt",
-     "Manifest",
-     "README.markdown",
-     "Rakefile",
-     "VERSION",
-     "howcast-0.7.3.gem",
-     "howcast.gemspec",
-     "lib/howcast.rb",
-     "lib/howcast/client.rb",
-     "lib/howcast/client/base.rb",
-     "lib/howcast/client/category.rb",
-     "lib/howcast/client/homepage.rb",
-     "lib/howcast/client/marker.rb",
-     "lib/howcast/client/playlist.rb",
-     "lib/howcast/client/search.rb",
-     "lib/howcast/client/user.rb",
-     "lib/howcast/client/video.rb",
-     "lib/howcast/errors.rb",
-     "lib/howcast/logging.rb",
-     "spec/howcast/client/base_spec.rb",
-     "spec/howcast/client/category_spec.rb",
-     "spec/howcast/client/homepage_spec.rb",
-     "spec/howcast/client/playlist_spec.rb",
-     "spec/howcast/client/search_spec.rb",
-     "spec/howcast/client/user_spec.rb",
-     "spec/howcast/client/video_spec.rb",
-     "spec/output_capture_helper.rb",
-     "spec/spec.opts",
-     "spec/spec_helper.rb",
-     "spec/string_matchers_helper.rb",
-     "spec/xml_fixtures_helper.rb",
-     "tasks/github.rake"
-  ]
-  s.homepage = %q{http://github.com/howcast/howcast-gem}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
-  s.summary = %q{Howcast API Ruby Wrapper}
-  s.test_files = [
-    "spec/howcast/client/base_spec.rb",
-     "spec/howcast/client/category_spec.rb",
-     "spec/howcast/client/homepage_spec.rb",
-     "spec/howcast/client/playlist_spec.rb",
-     "spec/howcast/client/search_spec.rb",
-     "spec/howcast/client/user_spec.rb",
-     "spec/howcast/client/video_spec.rb",
-     "spec/output_capture_helper.rb",
-     "spec/spec_helper.rb",
-     "spec/string_matchers_helper.rb",
-     "spec/xml_fixtures_helper.rb"
-  ]
+      developers to build applications that interface with Howcast. The Howcast
+      API is RESTful (REpresentational State Transfer) and users of this API will
+      be able: 1) Retreive detailed information about a single video, including
+      metadata such as title, description, video views, rating etc; 2) Retrieve a
+      list of videos restricted by a set of filters offered by Howcast and sorted
+      using several metrics that you can specify (most recent, most views, etc);
+      3) Search for video; 4) And much more. Note: Before you can use our APIs,
+      you must register an API key, that is submitted with each request.
+  }
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  s.rubyforge_project = "howcast"
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<hpricot>, [">= 0"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-    else
-      s.add_dependency(%q<hpricot>, [">= 0"])
-      s.add_dependency(%q<rspec>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<hpricot>, [">= 0"])
-    s.add_dependency(%q<rspec>, [">= 0"])
-  end
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_runtime_dependency(%q<hpricot>, [">= 0"])
+  s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
+  
+  #s.add_development_dependency(%q<jeweler>, [">= 0"])
+  s.add_development_dependency(%q<rake>, [">= 0"])
+  s.add_development_dependency(%q<rspec>, [">= 0"])
+  s.add_development_dependency(%q<ruby-debug>, [">= 0"])
 end
-

data/lib/howcast.rb

@@ -1,6 +1,6 @@
 module Howcast; end
 
-%w(howcast/client howcast/errors howcast/logging).each do |dependency|
+%w(howcast/version howcast/client howcast/errors howcast/logging).each do |dependency|
   require(File.expand_path(File.join(File.dirname(__FILE__), dependency)))
 end
 

data/lib/howcast/client.rb

@@ -2,6 +2,6 @@
 class Howcast::Client
 end
 
-%w(client/base client/video client/search client/category client/marker client/user client/homepage client/playlist).each do |dependency|
+%w(client/utils client/base client/video client/search client/category client/marker client/user client/homepage client/playlist client/type).each do |dependency|
   require(File.expand_path(File.join(File.dirname(__FILE__), dependency)))
 end

data/lib/howcast/client/base.rb

@@ -22,10 +22,16 @@
 #++
 
 require 'rubygems'
+require 'benchmark'
+require 'timeout'
 require 'hpricot'
+require 'nokogiri'
 require 'open-uri'
 require 'uri'
 
+require File.expand_path(File.join(File.dirname(__FILE__), '../hpricot/elements'))
+require File.expand_path(File.join(File.dirname(__FILE__), '../ext/string'))
+
 class Howcast::Client
   attr_accessor :key
   
@@ -56,210 +62,248 @@ class Howcast::Client
     end
 
     def base_uri
-      @base_uri ||= URI.parse("http://www.howcast.com")
+      @base_uri ||= URI.parse("http://api.howcast.com")
     end
   end
+  
   protected
-    # Establishes a connection with the Howcast API. Will auto append the api key, that was used
-    # to instantiate the Client object, to the URL
-    #
-    # === Inputs
-    #
-    # * <tt>relative_path</tt> -- should be the path after <tt>http://www.howcast.com/</tt>
-    #
-    # === Outputs
-    # 
-    # Hpricot object encapsulating the xml returned from the Howcast API
-    #
-    # === Exceptions
-    # 
-    # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested +relative_path+ is malformed or not available (404)
-    # * <tt>Howcast::ApiKeyNotFound</tt> -- raised if the +api_key+ is invalid
-    #
-    # === Examples
-    #
-    # Get the Hpricot data for most recent howcast studios videos
-    #   establish_connection("videos/most_recent/howcast_studios.xml") 
-    def establish_connection(relative_path_and_query)
-      uri = self.class.base_uri.dup
-      relative_path_and_query = '/' + relative_path_and_query unless relative_path_and_query[0] == '/'
-      uri.path, uri.query = *relative_path_and_query.split('?')
-      h = Hpricot.XML(open(url = attach_api_key(uri)))
-      Howcast.log.info "Established connection with: '#{url}'"
-      raise Howcast::ApiKeyNotFound if h.at(:error) && h.at(:error).inner_html.match(/Invalid API Key/)
-      return h
+  # Establishes a connection with the Howcast API. Will auto append the api key, that was used
+  # to instantiate the Client object, to the URL
+  #
+  # === Inputs
+  #
+  # * <tt>relative_path</tt> -- should be the path after <tt>http://www.howcast.com/</tt>
+  #
+  # === Outputs
+  # 
+  # Hpricot object encapsulating the xml returned from the Howcast API
+  #
+  # === Exceptions
+  # 
+  # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested +relative_path+ is malformed or not available (404)
+  # * <tt>Howcast::ApiKeyNotFound</tt> -- raised if the +api_key+ is invalid
+  #
+  # === Examples
+  #
+  # Get the Hpricot data for most recent howcast studios videos
+  #   establish_connection("videos/most_recent/howcast_studios.xml") 
+  def establish_connection(relative_path_and_query)
+    begin
+      uri                      = self.class.base_uri.dup
+      relative_path_and_query  = '/' + relative_path_and_query unless relative_path_and_query[0] == '/'
+      uri.path, uri.query      = *relative_path_and_query.split('?')
+
+      doc  = nil
+      time = Benchmark.realtime do
+        doc = Hpricot.XML open(attach_api_key uri)
+      end
+      Howcast.log.info "Established connection with: '#{uri.to_s}' after #{time * 1000}ms"
+
+      raise Howcast::ApiKeyNotFound \
+        if doc.at(:err) && doc.at(:err)['msg'].match(/Invalid API Key/)
+
+      doc
+    rescue Timeout::Error
+      raise Howcast::ApiError, "Timed-out after #{time * 1000}ms while attempting to access the API at #{uri.to_s}"
     rescue URI::InvalidURIError
-      raise Howcast::ApiNotFound.new("Invalid URL #{url.inspect} requested. Refer to the Howcast API for supported URL's")
-    rescue OpenURI::HTTPError => boom
-      raise Howcast::ApiError.new("HTTP error #{boom.message} accessing the API. Refer to the Howcast API for supported URL's")
+      raise Howcast::ApiNotFound, "Invalid URL #{uri.to_s} requested."
+    rescue OpenURI::HTTPError => e
+      raise Howcast::ApiError, "HTTP error #{e.message} accessing the API at #{uri.to_s}."
     end
-    
-    # Parses the xml for a single item from +xml+ and creates a new +klass+ object
-    #
-    # === Inputs
-    #
-    # * <tt>xml</tt> -- See below for a sample xml input
-    # * <tt>klass</tt> -- Class to create - Video | Category supported
-    #
-    # Sample input xml
-    #   <video>
-    #      <id>1086</id>
-    #      <rating>96</rating>
-    #      <title>How To Choose a Paintbrush</title>
-    #      <category-id>19</category-id>
-    #      <description>
-    #         <![CDATA[Yes, you could just use your fingers, but selecting the best brushes for your painting might achieve a slightly more grown-up result.]]>
-    #      </description>
-    #      <views>362</views>
-    #      <permalink>http://www.howcast.com/guides/1086-How-To-Choose-a-Paintbrush</permalink>
-    #      <username>michaelrsanchez</username>
-    #      <created-at>Thu, 20 Dec 2007 14:14:58 -0800</created-at>
-    #    </video>
-    #
-    # === Outputs 
-    # 
-    # +klass+ object with initialized attributes
-    def parse_single_xml(xml, klass)
-      hash = {}
-      klass.attr_accessors.each do |attribute|
-        node_name = attribute.to_s.gsub("_", "-") # xml schema uses hyphens for spaces, but ruby uses underscores
-        if node_name == "category-hierarchy"
-          hash[attribute] = category_hierarchy_for(xml) unless xml.at(node_name).nil?
-        elsif node_name == "ingredients"
-          hash[attribute] = ingredients_for(xml) unless xml.at(node_name).nil?
-        elsif node_name == "markers"
-          hash[attribute] = markers_for(xml) unless xml.at(node_name).nil?
-        elsif node_name == "related-videos"
-          hash[attribute] = related_videos_for(xml) unless xml.at(node_name).nil?
-        elsif node_name == "videos"
-          hash[attribute] = videos_for(xml) unless xml.at(node_name).nil?
-        elsif node_name == "playlist-thumbnail-url"
-          # TO DO: Resolve this hack, xml attributes aren't named consistently
-          hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : xml.at("thumbnail-url").inner_text.strip
-        else
-          hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : ""
-        end
+  end
+  
+  # Parses the xml for a single item from +xml+ and creates a new +klass+ object
+  #
+  # === Inputs
+  #
+  # * <tt>xml</tt> -- See below for a sample xml input
+  # * <tt>klass</tt> -- Class to create - Video | Category supported
+  #
+  # Sample input xml
+  #   <video>
+  #      <id>1086</id>
+  #      <rating>96</rating>
+  #      <title>How To Choose a Paintbrush</title>
+  #      <category-id>19</category-id>
+  #      <description>
+  #         <![CDATA[Yes, you could just use your fingers, but selecting the best brushes for your painting might achieve a slightly more grown-up result.]]>
+  #      </description>
+  #      <views>362</views>
+  #      <permalink>http://www.howcast.com/guides/1086-How-To-Choose-a-Paintbrush</permalink>
+  #      <username>michaelrsanchez</username>
+  #      <created-at>Thu, 20 Dec 2007 14:14:58 -0800</created-at>
+  #    </video>
+  #
+  # === Outputs 
+  # 
+  # +klass+ object with initialized attributes
+  def parse_single_xml(xml, klass)
+    hash = { }
+    klass.attr_accessors.each do |attribute|
+      node_name = attribute.to_s.gsub("_", "-") # xml schema uses hyphens for spaces, but ruby uses underscores
+      if node_name == "category-hierarchy"
+        hash[attribute] = category_hierarchy_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "playlist-memberships"
+        hash[attribute] = playlist_memberships_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "ingredients"
+        hash[attribute] = ingredients_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "markers"
+        hash[attribute] = markers_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "related-videos"
+        hash[attribute] = related_videos_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "videos"
+        hash[attribute] = videos_for(xml) unless xml.at(node_name).nil?
+      elsif node_name == "playlist-thumbnail-url"
+        # TODO: Resolve this hack, xml attributes aren't named consistently
+        hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : xml.at("thumbnail-url").inner_text.strip
+      elsif node_name == "type"
+        hash[attribute] = type_for(xml) unless xml.at(node_name).nil?
+      elsif %w{ ads-allowed mature-content }.include? node_name
+        hash[attribute] = !xml.at(node_name).nil? ? "true" : ""
+      else
+        hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : ""
       end
-      hash.values.all?{|v| v==""} ? nil : klass.new(hash)
-    end
-      
-    # Creates parameters to append to a uri
-    # 
-    # === Inputs
-    # 
-    # Options are:
-    # * <tt>:page</tt> -- the page number
-    # * <tt>:use_ampersand</tt> -- boolean to return ampersand (defaults to false)
-    #
-    # === Outputs
-    #
-    # A valid suffix string to append to the end of a url
-    #
-    # === Examples
-    #
-    # "?page=2"
-    #   uri_suffix(:page => 2)
-    # "&page=2"
-    #   uri_suffix(:page => 3, :use_ampersand => true)
-    def uri_suffix(opts)
-      opts && opts[:page] ? "#{opts[:use_ampersand] ? '&' : '?'}page=#{opts[:page]}" : ""
     end
+    hash.values.all?{ |v| (v == "") or (v.respond_to?(:empty?) and v.empty?) } ? nil : klass.new(hash)
+  end
     
-    # Appends the api key to a uri and returns the appended uri
-    # 
-    # === Inputs
-    # 
-    # * <tt>uri</tt> -- the URI object to append the api_key to
-    #
-    # === Outputs
-    #
-    # The uri with the api_key appended to the query string
-    #
-    # === Examples
-    #
-    #   attach_api_key(URI.parse("http://www.howcast.com")).to_s
-    #   => "http://www.howcast.com?api_key=APIKEYHERE"
-    #   
-    #   attach_api_key(URI.parse("http://www.howcast.com/videos/most_recent/all?page=2")).to_s
-    #   => "http://www.howcast.com/videos/most_recent/all?page=2&api_key=APIKEYHERE"
-    def attach_api_key(uri)
-      uri = uri.dup
-      key = "api_key=#{self.key}"
-      uri.query = uri.query.to_s.strip != "" ? uri.query+"&"+key : key
-      uri
-    end
+  # Creates parameters to append to a uri
+  # 
+  # === Inputs
+  # 
+  # Options are:
+  # * <tt>:page</tt> -- the page number
+  # * <tt>:use_ampersand</tt> -- boolean to return ampersand (defaults to false)
+  #
+  # === Outputs
+  #
+  # A valid suffix string to append to the end of a url
+  #
+  # === Examples
+  #
+  # "?page=2"
+  #   uri_suffix(:page => 2)
+  # "&page=2"
+  #   uri_suffix(:page => 3, :use_ampersand => true)
+  def uri_suffix(opts)
+    opts && opts[:page] ? "#{opts[:use_ampersand] ? '&' : '?'}page=#{opts[:page]}" : ""
+  end
+  
+  # Appends the api key to a uri and returns the appended uri
+  # 
+  # === Inputs
+  # 
+  # * <tt>uri</tt> -- the URI object to append the api_key to
+  #
+  # === Outputs
+  #
+  # The uri with the api_key appended to the query string
+  #
+  # === Examples
+  #
+  #   attach_api_key(URI.parse("http://www.howcast.com")).to_s
+  #   => "http://www.howcast.com?api_key=APIKEYHERE"
+  #   
+  #   attach_api_key(URI.parse("http://www.howcast.com/videos/most_recent/all?page=2")).to_s
+  #   => "http://www.howcast.com/videos/most_recent/all?page=2&api_key=APIKEYHERE"
+  def attach_api_key(uri)
+    uri = uri.dup
+    key = "api_key=#{self.key}"
+    uri.query = uri.query.to_s.strip != "" ? uri.query+"&"+key : key
+    uri
+  end
 
-    # From merb/core_ext/hash.rb, line 87
-    def hash_to_params hash
-      params = ''
-      stack = []
+  # From merb/core_ext/hash.rb, line 87
+  def hash_to_params hash
+    params = ''
+    stack = []
 
-      hash.each do |k, v|
-        if v.is_a?(Hash)
-          stack << [k,v]
-        else
-          params << "#{k}=#{v}&"
-        end
+    hash.keys.sort{ |a, b| a.to_s <=> b.to_s }.each do |k|
+      v = hash[k]
+      if v.is_a?(Hash)
+        stack << [k,v]
+      else
+        params << "#{k}=#{v}&"
       end
+    end
 
-      stack.each do |parent, h|
-        h.each do |k, v|
-          if v.is_a?(Hash)
-            stack << ["#{parent}[#{k}]", v]
-          else
-            params << "#{parent}[#{k}]=#{v}&"
-          end
+    stack.each do |parent, h|
+      h.each do |k, v|
+        if v.is_a?(Hash)
+          stack << ["#{parent}[#{k}]", v]
+        else
+          params << "#{parent}[#{k}]=#{v}&"
         end
       end
-
-      params.chop! # trailing &
-      params
     end
+
+    params.chop! # trailing &
+    params
+  end
     
   private
-    def category_hierarchy_for(xml)
-      categories = []
-      node = xml.at('category-hierarchy')
-      node.children_of_type('category').each do |child|
-        category = Category.new(:id => child['id'], :parent_id => child['parent_id'], :name => child.inner_text)
-        categories << category
-      end unless node.nil?
-      categories
-    end
-    
-    def ingredients_for(xml)
-      ingredients = []
-      node = xml.at('ingredients')
-      node.children_of_type('ingredient').each do |child|
-        ingredients << child.inner_text.strip
-      end unless node.nil?
-      ingredients
-    end
-    
-    def markers_for(xml)
-      markers = []
-      node = xml.at('markers')
-      node.children_of_type('marker').each do |child|
-        markers << parse_single_xml(child, Marker)
-      end unless node.nil?
-      markers
-    end
-    
-    def related_videos_for(xml)
-      related = []
-      node = xml.at('related-videos')
-      node.children_of_type('video').each do |child|
-        related << parse_single_xml(child, Video)
-      end unless node.nil?
-      related
-    end
-    
-    def videos_for(xml)
-      videos = []
-      node = xml.at('videos')
-      node.children_of_type('video').each do |child|
-        videos << parse_single_xml(child, Video)
-      end unless node.nil?
-      videos
+  def category_hierarchy_for(xml)
+    categories = []
+    node = xml.at('category-hierarchy')
+    node.children_of_type('category').each do |child|
+      category = Category.new(:id => child['id'], :parent_id => child['parent_id'], :name => child.inner_text, :permalink => child['permalink'])
+      categories << category
+    end unless node.nil?
+    categories
+  end
+
+  def playlist_memberships_for(xml)
+    memberships = []
+    node = xml.at('playlist-memberships')
+    node.children_of_type('playlist').each do |child|
+      playlist = Playlist.new(:id => child['id'], :title => child.inner_text)
+      memberships << playlist
+    end unless node.nil?
+    memberships
+  end
+  
+  def ingredients_for(xml)
+    ingredients = []
+    node = xml.at('ingredients')
+    node.children_of_type('ingredient').each do |child|
+      ingredients << child.inner_text.strip
+    end unless node.nil?
+    ingredients
+  end
+  
+  def markers_for(xml)
+    markers = []
+    node = xml.at('markers')
+    node.children_of_type('marker').each do |child|
+      markers << parse_single_xml(child, Marker)
+    end unless node.nil?
+    markers
+  end
+  
+  def type_for(xml)
+    node = xml.at('type')
+    if node['status'] && node['class']
+      Type.new(:name => node.inner_text.strip, :kind => node['class'], :status => node['status'])
+    else
+      node.inner_text.strip
     end
+  end
+  
+  def related_videos_for(xml)
+    related = []
+    node = xml.at('related-videos')
+    node.children_of_type('video').each do |child|
+      related << parse_single_xml(child, Video)
+    end unless node.nil?
+    related
+  end
+  
+  def videos_for(xml)
+    videos = []
+    node = xml.at('videos')
+    node.children_of_type('video').each do |child|
+      videos << parse_single_xml(child, Video)
+    end unless node.nil?
+    videos
+  end
 end