rturk 1.0.5 → 2.0.0

data/lib/rturk/responses/get_hit_response.rb

@@ -0,0 +1,80 @@
+# Parses the GetHIT Response
+#
+# <?xml version="1.0"?>
+# <GetHITResponse>
+#   <OperationRequest>
+#     <RequestId>49341251-fcbd-45c3-ab98-8fbe2e4d8060</RequestId>
+#   </OperationRequest>
+#   <HIT>
+#     <Request>
+#       <IsValid>True</IsValid>
+#     </Request>
+#     <HITId>GR4R3HY3YGBZXDCAPJWZ</HITId>
+#     <HITTypeId>YGKZ2W5X6YFZ08ZRXXZZ</HITTypeId>
+#     <CreationTime>2009-06-25T04:21:17Z</CreationTime>
+#     <Title>Write a twitter update</Title>
+#     <Description>Simply write a twitter update for me</Description>
+#     <Question>&lt;ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd"&gt;
+#   &lt;ExternalURL&gt;http://s3.amazonaws.com/mpercival.com/newtweet.html?id=foo&lt;/ExternalURL&gt; 
+#   &lt;FrameHeight&gt;400&lt;/FrameHeight&gt;
+# &lt;/ExternalQuestion&gt;
+# </Question>
+#     <Keywords>twitter, blogging, writing, english</Keywords>
+#     <HITStatus>Reviewable</HITStatus>
+#     <MaxAssignments>1</MaxAssignments>
+#     <Reward>
+#       <Amount>0.10</Amount>
+#       <CurrencyCode>USD</CurrencyCode>
+#       <FormattedPrice>$0.10</FormattedPrice>
+#     </Reward>
+#     <AutoApprovalDelayInSeconds>3600</AutoApprovalDelayInSeconds>
+#     <Expiration>2009-06-25T05:21:17Z</Expiration>
+#     <AssignmentDurationInSeconds>3600</AssignmentDurationInSeconds>
+#     <NumberOfSimilarHITs>0</NumberOfSimilarHITs>
+#     <RequesterAnnotation>OptionalNote</RequesterAnnotation>
+#     <QualificationRequirement>
+#       <QualificationTypeId>000000000000000000L0</QualificationTypeId>
+#       <Comparator>GreaterThan</Comparator>
+#       <IntegerValue>90</IntegerValue>
+#       <RequiredToPreview>0</RequiredToPreview>
+#     </QualificationRequirement>
+#     <HITReviewStatus>NotReviewed</HITReviewStatus>
+#   </HIT>
+# </GetHITResponse>
+
+module RTurk
+  
+  class GetHITResponse < Response
+    
+    attr_accessor :id, :type_id, :status, :title, :description, :reward, :assignments
+    attr_accessor :similar_hits, :review_status, :expires_at, :auto_approval
+    
+    def initialize(response)
+      @raw_xml = response
+      @xml = Nokogiri::XML(@raw_xml)
+      raise_errors
+      map_content(@xml.xpath('//HIT'),
+        :id => 'HITId',
+        :type_id => 'HITTypeId',
+        :status => 'HITStatus',
+        :title => "Title",
+        :description => 'Description',
+        :assignments => 'MaxAssignments',
+        :similar_hits => 'NumberOfSimilarHITs',
+        :review_status => 'HITReviewStatus',
+        :expires_at => 'Expiration',
+        :auto_approval => 'AutoApprovalDelayInSeconds'
+      )
+    end
+    
+    def expires_at=(time)
+      @expires_at = Time.parse(time)
+    end
+    
+    def auto_approval=(seconds)
+      @auto_approval = seconds.to_i
+    end
+    
+  end
+  
+end

data/lib/rturk/responses/get_reviewable_hits_response.rb

@@ -0,0 +1,33 @@
+# <GetReviewableHITsResult>
+#   <Request>
+#     <IsValid>True</IsValid>
+#   </Request>
+#   <NumResults>3</NumResults>
+#   <TotalNumResults>3</TotalNumResults>
+#   <PageNumber>1</PageNumber>
+#   <HIT>
+#     <HITId>GBHZVQX3EHXZ2AYDY2T0</HITId>
+#   </HIT>
+#   <HIT>
+#     <HITId>GBHZVQX3EHXZ2AYDY2T1</HITId>
+#   </HIT>
+#   <HIT>
+#     <HITId>GBHZVQX3EHXZ2AYDY2T2</HITId>
+#   </HIT>
+# </GetReviewableHITsResult>
+
+module RTurk
+  
+  class GetReviewableHITsResponse < Response
+    
+    def hits
+      @hits ||= []
+      @xml.xpath('//HIT').each do |hit_xml|
+        @hits << RTurk::Hit.new(hit_xml.inner_text.strip)
+      end
+      @hits
+    end
+    
+  end
+  
+end

data/lib/rturk/utilities.rb

@@ -5,7 +5,7 @@ module RTurk::Utilities
     phrase.gsub!(/\_/, '')
     return phrase
   end
-  
+
   def stringify_keys(ahash)
     ahash = ahash.inject({}) do |options, (key, value)|
       options[(key.to_s rescue key) || key] = value
@@ -14,4 +14,22 @@ module RTurk::Utilities
     ahash
   end
 
+  def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
+    if first_letter_in_uppercase
+      lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+    else
+      lower_case_and_underscored_word.first + camelize(lower_case_and_underscored_word)[1..-1]
+    end
+  end
+
+  def underscore(camel_cased_word)
+    camel_cased_word.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+
 end
+
+# TODO: Build an Nokogiri from_xml parser, should return a hash

data/lib/rturk/xml_utilities.rb

@@ -0,0 +1,23 @@
+module RTurk::XmlUtilities
+
+  def xml_to_hash(noko_xml)
+    hash = {}
+    noko_xml.children.each do |child|
+      next if child.blank?
+      if child.text?
+        return child.text
+      else
+        hash[child.name] = xml_to_hash(child)
+      end
+    end
+    hash
+  end
+
+  def map_content(xml_obj, hash)
+    hash.each_pair do |k,v|
+      self.send("#{k.to_s}=", xml_obj.xpath(v).inner_text)
+    end
+  end
+
+
+end

data/rturk.gemspec

@@ -0,0 +1,143 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rturk}
+  s.version = "2.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mark Percival"]
+  s.date = %q{2009-10-26}
+  s.email = %q{mark@mpercival.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".gitignore",
+     ".gitmodules",
+     ".yardoc",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "TODO.markdown",
+     "VERSION",
+     "examples/blank_slate.rb",
+     "examples/create_hit.rb",
+     "examples/mturk.sample.yml",
+     "examples/newtweet.html",
+     "examples/review_answer.rb",
+     "lib/rturk.rb",
+     "lib/rturk/adapters/answers.rb",
+     "lib/rturk/adapters/assignment.rb",
+     "lib/rturk/adapters/hit.rb",
+     "lib/rturk/builders/qualification_builder.rb",
+     "lib/rturk/builders/qualifications_builder.rb",
+     "lib/rturk/builders/question_builder.rb",
+     "lib/rturk/errors.rb",
+     "lib/rturk/logger.rb",
+     "lib/rturk/macros.rb",
+     "lib/rturk/operation.rb",
+     "lib/rturk/operations/approve_assignment.rb",
+     "lib/rturk/operations/create_hit.rb",
+     "lib/rturk/operations/disable_hit.rb",
+     "lib/rturk/operations/dispose_hit.rb",
+     "lib/rturk/operations/force_expire_hit.rb",
+     "lib/rturk/operations/get_account_balance.rb",
+     "lib/rturk/operations/get_assignments_for_hit.rb",
+     "lib/rturk/operations/get_hit.rb",
+     "lib/rturk/operations/get_reviewable_hits.rb",
+     "lib/rturk/operations/grant_bonus.rb",
+     "lib/rturk/operations/reject_assignment.rb",
+     "lib/rturk/requester.rb",
+     "lib/rturk/response.rb",
+     "lib/rturk/responses/create_hit_response.rb",
+     "lib/rturk/responses/get_account_balance_response.rb",
+     "lib/rturk/responses/get_assignments_for_hit_response.rb",
+     "lib/rturk/responses/get_hit_response.rb",
+     "lib/rturk/responses/get_reviewable_hits_response.rb",
+     "lib/rturk/utilities.rb",
+     "lib/rturk/xml_utilities.rb",
+     "rturk.gemspec",
+     "spec/adapters/answers_spec.rb",
+     "spec/adapters/assignment_spec.rb",
+     "spec/adapters/hit_spec.rb",
+     "spec/builders/qualification_spec.rb",
+     "spec/builders/qualifications_spec.rb",
+     "spec/builders/question_spec.rb",
+     "spec/fake_responses/approve_assignment.xml",
+     "spec/fake_responses/create_hit.xml",
+     "spec/fake_responses/disable_hit.xml",
+     "spec/fake_responses/dispose_hit.xml",
+     "spec/fake_responses/force_expire_hit.xml",
+     "spec/fake_responses/get_account_balance.xml",
+     "spec/fake_responses/get_assignments.xml",
+     "spec/fake_responses/get_hit.xml",
+     "spec/fake_responses/get_reviewable_hits.xml",
+     "spec/fake_responses/grant_bonus.xml",
+     "spec/fake_responses/invalid_credentials.xml",
+     "spec/fake_responses/reject_assignment.xml",
+     "spec/mturk.sample.yml",
+     "spec/operations/approve_assignment_spec.rb",
+     "spec/operations/create_hit_spec.rb",
+     "spec/operations/disable_hit_spec.rb",
+     "spec/operations/dispose_hit_spec.rb",
+     "spec/operations/force_expire_hit_spec.rb",
+     "spec/operations/get_account_balance_spec.rb",
+     "spec/operations/get_assignments_spec.rb",
+     "spec/operations/get_hit_spec.rb",
+     "spec/operations/get_reviewable_hits_spec.rb",
+     "spec/operations/grant_bonus_spec.rb",
+     "spec/operations/reject_assignment_spec.rb",
+     "spec/requester_spec.rb",
+     "spec/response_spec.rb",
+     "spec/rturk_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/tmp",
+     "spec/xml_parse_spec.rb"
+  ]
+  s.homepage = %q{http://github.com/markpercival/rturk}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Mechanical Turk API Wrapper}
+  s.test_files = [
+    "spec/adapters/answers_spec.rb",
+     "spec/adapters/assignment_spec.rb",
+     "spec/adapters/hit_spec.rb",
+     "spec/builders/qualification_spec.rb",
+     "spec/builders/qualifications_spec.rb",
+     "spec/builders/question_spec.rb",
+     "spec/operations/approve_assignment_spec.rb",
+     "spec/operations/create_hit_spec.rb",
+     "spec/operations/disable_hit_spec.rb",
+     "spec/operations/dispose_hit_spec.rb",
+     "spec/operations/force_expire_hit_spec.rb",
+     "spec/operations/get_account_balance_spec.rb",
+     "spec/operations/get_assignments_spec.rb",
+     "spec/operations/get_hit_spec.rb",
+     "spec/operations/get_reviewable_hits_spec.rb",
+     "spec/operations/grant_bonus_spec.rb",
+     "spec/operations/reject_assignment_spec.rb",
+     "spec/requester_spec.rb",
+     "spec/response_spec.rb",
+     "spec/rturk_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/xml_parse_spec.rb",
+     "examples/blank_slate.rb",
+     "examples/create_hit.rb",
+     "examples/review_answer.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/spec/adapters/answers_spec.rb

@@ -0,0 +1,27 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+
+describe RTurk::Answers do
+  
+  before(:all) do
+    @answer =  <<-XML
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;QuestionFormAnswers xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionFormAnswers.xsd"&gt;
+&lt;Answer&gt;
+&lt;QuestionIdentifier&gt;tweet&lt;/QuestionIdentifier&gt;
+&lt;FreeText&gt;This is my tweet!&lt;/FreeText&gt;
+&lt;/Answer&gt;
+&lt;Answer&gt;
+&lt;QuestionIdentifier&gt;Submit&lt;/QuestionIdentifier&gt;
+&lt;FreeText&gt;Submit&lt;/FreeText&gt;
+&lt;/Answer&gt;
+&lt;/QuestionFormAnswers&gt;
+XML
+  end
+  
+  it "should parse a answer" do
+    RTurk::Answers.new(@answer).to_hash.should == {"Submit"=>"Submit", "tweet"=>"This is my tweet!"}
+  end
+
+  
+end

data/spec/adapters/hit_spec.rb

@@ -0,0 +1,46 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+describe "HIT adapter" do
+
+  before(:all) do
+    aws = YAML.load(File.open(File.join(SPEC_ROOT, 'mturk.yml')))
+    RTurk.setup(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
+    faker('create_hit', :operation => 'CreateHIT')
+    faker('get_hit', :operation => 'GetHIT')
+    faker('get_reviewable_hits', :operation => 'GetReviewableHITs')
+    faker('get_assignments', :operation => 'GetAssignments')
+    faker('force_expire_hit', :operation => 'ForceExpireHIT')
+    faker('dispose_hit', :operation => 'DisposeHIT')
+  end
+
+  it "should let us create a hit" do
+    RTurk::Hit.create(:title => 'foo', :description => 'do foo', :question => 'http://mpercival.com', :reward => 0.05)
+  end
+  
+  it "should automagically request additional information on an existing hit" do
+    hit = RTurk::Hit.new(12345)
+    hit.type_id.should eql("YGKZ2W5X6YFZ08ZRXXZZ")
+    hit.url.should eql("http://workersandbox.mturk.com/mturk/preview?groupId=YGKZ2W5X6YFZ08ZRXXZZ")
+  end
+  
+  it "should get all reviewable hits" do
+    hits = RTurk::Hit.all_reviewable
+    hits.size.should eql(3)
+  end
+  
+  it "should find assignments for a hit" do
+    hits = RTurk::Hit.all_reviewable
+    hits.first.assignments.first.answers["tweet"].should eql('This is my tweet!')
+  end
+  
+  it "should expire a hit" do
+    hits = RTurk::Hit.all_reviewable
+    hits.first.expire!
+  end
+  
+  it "should dispose of a hit" do
+    hits = RTurk::Hit.all_reviewable
+    hits.first.dispose!
+  end
+
+end

data/spec/builders/qualification_spec.rb

@@ -0,0 +1,53 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+
+describe RTurk::Qualifications do
+  
+  # Possible values coming back
+  # {"QualificationTypeId","Comparator", "IntegerValue", "LocaleValue.Country","RequiredToPreview"}
+
+  before(:each) do
+
+  end
+
+  it "should build a qualification for Approval rate" do
+    @qualification = RTurk::Qualification.new('000000000000000000L0', :gt => 90)
+    @qualification.to_params.should eql({"QualificationTypeId" => '000000000000000000L0',"Comparator" => 'GreaterThan',
+                                         "IntegerValue" => 90, "RequiredToPreview" => "true"})
+  end
+  
+  it "should build a qualification for boolean qualification" do
+    @qualification = RTurk::Qualification.new('00000000000000000060', true)
+    @qualification.to_params.should eql({"QualificationTypeId" => '00000000000000000060',"Comparator" => 'EqualTo',
+                                         "IntegerValue" => 1, "RequiredToPreview" => "true"})
+  end
+  
+  it "should build a qualification for country qualification" do
+    @qualification = RTurk::Qualification.new('00000000000000000071', :eql => 'PH')
+    @qualification.to_params.should eql({"QualificationTypeId" => '00000000000000000071',"Comparator" => 'EqualTo',
+                                         "LocaleValue.Country" => 'PH', "RequiredToPreview" => "true"})
+  end
+  
+  context 'passing in symbols representing a TypeID' do
+    
+    it "should build a qualification for Approval rate" do
+      @qualification = RTurk::Qualification.new(:approval_rate, :gt => 90)
+      @qualification.to_params.should eql({"QualificationTypeId" => '000000000000000000L0',"Comparator" => 'GreaterThan',
+                                           "IntegerValue" => 90, "RequiredToPreview" => "true"})
+    end
+
+    it "should build a qualification for boolean qualification" do
+      @qualification = RTurk::Qualification.new(:adult, true)
+      @qualification.to_params.should eql({"QualificationTypeId" => '00000000000000000060',"Comparator" => 'EqualTo',
+                                           "IntegerValue" => 1, "RequiredToPreview" => "true"})
+    end
+
+    it "should build a qualification for country qualification" do
+      @qualification = RTurk::Qualification.new(:country, :eql => 'PH')
+      @qualification.to_params.should eql({"QualificationTypeId" => '00000000000000000071',"Comparator" => 'EqualTo',
+                                           "LocaleValue.Country" => 'PH', "RequiredToPreview" => "true"})
+    end
+    
+  end
+
+end