yanapi 0.3.1 → 0.3.2

data/CHANGELOG

@@ -1,22 +1,33 @@
-=== COMPLETED
-==== 0.3.1
+== COMPLETED
+=== 0.3.2
+The main class +Query+ reimplemented and covered by tests.
+
+The overall documentation enhanced.
+=== 0.3.1
 All four search methods implemented.
-==== 0.1.1
+
+WARNING! This is the first release with a new two dimensional interface! Consult
+README for further details.
+=== 0.1.1
 Small fixes in the documentation.
-==== 0.1.0
-The search methods <tt>questionSearch</tt> and <tt>getByCategory</tt>.
-==== 0.0.1
+=== 0.1.0
+The search methods <tt>questionSearch</tt> and <tt>getByCategory</tt>
+implemented without tests.
+=== 0.0.1
 Initial release of the lib.
 
 
-=== PLANNED
-==== 0.4.0
+== PLANNED
+=== 0.4.0
 Enhance the documentation.
 
 Implement multivalue parameters.
-==== 0.5.0
-==== 0.6.0
-==== 0.7.0
-==== 0.8.0
-==== 0.9.0
-==== 1.0.0
+=== 0.5.0
+Implement semantic checks for all query types.
+
+Enhance the documentation.
+=== 0.6.0
+=== 0.7.0
+=== 0.8.0
+=== 0.9.0
+=== 1.0.0

data/README

@@ -21,13 +21,25 @@ It is possible to restrict key word based search through a category.
 
 Question Search and User Search cannot be extended by key words or category IDs.
 
-Yanapi tries to as flexible as possible. It restricts unallowed parameter
+YANAPI tries to as flexible as possible. It restricts unallowed parameter
 combinations and forces using mandatory ones. But it doesn't care about defaults.
 For example, as for this writing the default output value is an xml based format.
 If it changes in the future, the user will be responsible to choose the format.
 No defaults are hardcoded in YANAPI.
+
 YANAPI provides the minimal acceptable query. 
 
+== INSTALLATION
+To install YANAPI ussue the following command:
+  $ gem install yanapi
+
+You might want to install versions prior to +0.3.1+:
+  $ gem install yanapi -v 0.1.1
+
+If you want to do a system wide installation, do this as root
+(possibly using +sudo+).
+
+Alternatively use your Gemfile for dependency management.
 == SYNOPSIS
 
 YANAPI requires a parameter hash with two dimensions:
@@ -57,7 +69,7 @@ A small example shall demostrate the usage:
   api.get # => default xml structure
 
 
-For details on particular keys and defaults see {the official description}[http://developer.yahoo.com/answers/] and the RDoc documentation in this libruary.
+For details on particular keys and defaults see {the official description}[http://developer.yahoo.com/answers/] and the RDoc documentation in this library.
 
 == EXCEPTION HIERARCHY
 While using YANAPI you can face three kinds of errors:
@@ -90,5 +102,6 @@ Please contact me with your suggestions, bug reports and feature requests.
 == LICENSE
 
 YANAPI is a copyrighted software by Andrei Beliankou, 2011.
+
 You may use, redistribute and change it under the terms
 provided in the LICENSE file.

data/lib/yanapi/api.rb

@@ -1,5 +1,5 @@
 # :title: YANAPI, Yahoo! Answers API
-# :main: README.rdoc
+# :main: README
 
 require 'yanapi/version'
 require 'yanapi/term_query'

data/lib/yanapi/error.rb

@@ -20,9 +20,13 @@ module YANAPI
   # A technical error accessing the server,
   # may be caught and handled with a new attempt.
   class ExternalError < Error
-    def initialize(exception)
-      msg = "Some external error occured:\n" +
-            "#{exception.class}: #{exception.message}"
+    def initialize(arg)
+      msg = "Some external error occured:\n"
+      if arg.kind_of?(String)
+        msg += arg
+      else
+        msg += "#{exception.class}: #{exception.message}"        
+      end
       super(msg)
     end
   end

data/lib/yanapi/query.rb

@@ -16,8 +16,8 @@ module YANAPI
     VALID_OUTPUT_FORMATS = [nil, 'xml', 'php', 'rss', 'json']
     
     # It accepts a two dimensional hash:
-    # {:method => 'questionSearch', :query_params =>
-    #   {:appid => 'YahooDemo', :query => 'Haus'}}
+    #   {:method => 'questionSearch', :query_params =>
+    #     {:appid => 'YahooDemo', :query => 'Haus'}}
     def initialize(params)
       @method = params[:method]
       @params = check_params(params[:query_params])
@@ -25,43 +25,24 @@ module YANAPI
       @output = @params[:output] || 'xml'            
     end
     
-    # main method
+    # This is the main method. It gets the body of the HTTP response and
+    # invokes the respective check.
+    # It returns the response or <nil> if the response is emtpy.
     def get
-      http_response = Net::HTTP.get_response(@url)
+
+      http_response = get_response(@url)
       
       case @output
       when 'xml'
-        # Set the value to STRICT (0), otherwise no errors will be raised!
-        xml = Nokogiri::XML::Document.parse(http_response.body, nil, nil, 0)
-        result = prove_xml(xml) ? http_response.body : nil
+        prove_xml(http_response)
       when 'json'
-        raise NotImplementedError, 'We do not handle JSON yet!'
+        fail NotImplementedError, 'We do not handle JSON yet!'
       when 'php'
-        raise NotImplementedError, 'We do not handle PHP yet!'
+        fail NotImplementedError, 'We do not handle PHP yet!'
       when 'rss'
-        raise NotImplementedError, 'We do not handle RSS yet!'
+        fail NotImplementedError, 'We do not handle RSS yet!'
       end
 
-      # TODO: make a fine grained distinction
-      case http_response
-      when Net::HTTPSuccess
-        return result
-
-      when Net::HTTPBadRequest,
-        Net::HTTPForbidden,
-        Net::HTTPServiceUnavailable
-        raise ExternalError.new("#{http_response}:\n\n#{result}")
-      else
-        raise ExternalError.new("#{http_response}:\n\n#{result}")
-      end
-
-    # are all external errors caught here?
-    rescue Net::HTTPError, SocketError, Timeout::Error,
-           IOError, SystemCallError => e
-      raise ExternalError, e
-    # add JSON, PHP, RSS errors here
-    rescue Nokogiri::XML::SyntaxError => e
-      raise ContentError.new(e)
     end # get
 
     #########
@@ -90,7 +71,7 @@ module YANAPI
       # Multiple values will be provided as Arrays:
       # :category_id => [123, 456, 789].
       params.each_pair do |k, v|
-        unless (v.instance_of?(String) || v.instance_of?(Fixnum))
+        unless (v.kind_of?(String) || v.kind_of?(Fixnum))
           fail UserError, "The value <:#{k}> is not unique!"
         end
       end
@@ -107,7 +88,7 @@ module YANAPI
 
 
       expanded_params = expand_params(params) # It is an array now! 
-      escaped_params = params.collect do |k, v|
+      escaped_params = expanded_params.map do |k, v|
         k = URI.escape(k.to_s, unsafe = reserved_chars)
         v = URI.escape(v.to_s, unsafe = reserved_chars)
         "#{k}=#{v}"
@@ -135,26 +116,54 @@ module YANAPI
       expanded_params.sort_by { |k, v| [k.to_s, v.to_s] }
     end
 
-    # proves the presense of an error
-    # proves it the answer set is empty
-    def prove_xml(xml)
+    # It sends a HTTP request, rescues any external errors issuing an
+    # YANAPI::ExternalError, checks the HTTP code and fails if it is not 200.
+    # Otherwise it returns the body of the HTTP response.
+    def get_response(url)
+      begin
+        http_response = Net::HTTP.get_response(url)
+      rescue Net::HTTPError, SocketError, Timeout::Error, IOError => e
+        fail ExternalError, e
+      end
+      
+      case http_response
+      when Net::HTTPSuccess
+        http_response.body
+      when Net::HTTPBadRequest,
+           Net::HTTPForbidden,
+           Net::HTTPServiceUnavailable
+        # These errors are documented by Yahoo!.
+        fail(ExternalError, http_response.header) 
+      else
+        fail(ExternalError, "Unexpected HTTP response: #{http_response.header}.")
+      end
+      
+    end
+
+    # It parses the input, checks for xml validity and proves if it is empty.
+    # It returns then <xml> as string or <nil> if the answer is emtpy.
+    def prove_xml(xml_as_str)
+      begin
+        # Set the value to STRICT (0), otherwise no errors will be raised!
+        xml = Nokogiri::XML::Document.parse(xml_as_str, nil, nil, 0)
+      rescue Nokogiri::XML::SyntaxError
+        fail(ContentError, 'Erroneous XML response!')
+      end
+      
       error = xml.at_xpath('/xmlns:Error', xml.root.namespaces)
       if error
         message = 'The following errors were detected:'
         error.xpath('//xmlns:Message', xml.root.namespaces).each do |msg|
           message << "\n" + msg.content
         end
-        raise ContentError.new(message)
+        fail(ContentError, message)
       end
 
       question = xml.at_xpath('//xmlns:Question', xml.root.namespaces)
 
-      if question
-        xml
-      else
-        nil
-      end
-    end    
+      question ? xml_as_str : nil
+    end
+
   end # Query
   
 end # YANAPI

data/lib/yanapi/version.rb

@@ -1,3 +1,3 @@
 module YANAPI
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/test/test_query.rb

@@ -40,8 +40,7 @@ class TestQuery < Test::Unit::TestCase
 
   # The following constants should have the given value and type.
   def test_values_of_constants
-    assert_equal('http://answers.yahooapis.com',
-                 YANAPI::Query::HOST)
+    assert_equal('http://answers.yahooapis.com', YANAPI::Query::HOST)
     assert_equal('AnswersService', YANAPI::Query::SERVICE)
     assert_equal('V1', YANAPI::Query::SERVICE_VERSION)
   end
@@ -95,7 +94,18 @@ class TestQuery < Test::Unit::TestCase
 
   
   ## Functional tests
-  
+
+  # It should create well formed urls.
+  def test_url_form
+    q = YANAPI::Query.new(@params)
+    print q.inspect
+    etalon_url = 'http://answers.yahooapis.com/AnswersService/V1/questionSearch?appid=YahooDemo&output=xml&query=Haus'
+    real_url = q.instance_variable_get(:@url).to_s
+    assert_equal(etalon_url, real_url)
+
+    warn "\nWARNING! Expand this test for multivalue parameters!\n"
+  end
+
   # It should return <nil> if the server response contains
   # no answer. It is possible if we out of range or search criteria
   # are too strict.
@@ -122,7 +132,7 @@ class TestQuery < Test::Unit::TestCase
     assert_instance_of(String, actual_api_answer, 'Not String!')
     assert_equal(expected_api_answer, actual_api_answer)
 
-    warn "\nAdd tests for <php>, <json> and <rss>!\n"
+    warn "\nWANRING! Add tests for <php>, <json> and <rss>!\n"
   end
 
   # It should fail with an appropriate exception

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yanapi
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 23
   prerelease: 
   segments: 
   - 0
   - 3
-  - 1
-  version: 0.3.1
+  - 2
+  version: 0.3.2
 platform: ruby
 authors: 
 - Andrei Beliankou
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-05 00:00:00 Z
+date: 2011-08-10 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: nokogiri
@@ -32,9 +32,25 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: fakeweb
+  name: rdoc
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 33
+        segments: 
+        - 3
+        - 9
+        - 1
+        version: 3.9.1
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -44,7 +60,7 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id002
+  version_requirements: *id003
 description: YANAPI is a programmatic API for Yahoo! Answers web services. It enables you to search for questions using key words, user IDs, category names and IDs and a pricise ID of a question. The output is provided in the xml format as well as json, php and rss.
 email: a.belenkow@uni-trier.de
 executables: []
@@ -124,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: yanapi
-rubygems_version: 1.7.2
+rubygems_version: 1.8.7
 signing_key: 
 specification_version: 3
 summary: YANAPI is an API for Yahoo! Answers web services.