rturk 2.10.3 → 2.11.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e315bf746bf3734838ccc4b111232cb716d31ca
+  data.tar.gz: 0c168e252589bc94ec2c052ed9daad5f2a372cfb
+SHA512:
+  metadata.gz: 73b53fbc9af91652ed7bc54d8a30e8e3f3b0617d16909e2e79bb371dba1916c2be25236afeb3de1e724f21c19281d37e1ed46ffb513b18834038ae5eb6bba548
+  data.tar.gz: f639e6d9564ed50418a7f57a9e6b1172f85dbcbf49220d4efcbe3af44647c3ae90ae7d311f63b377bb4bac5103bd6616ffa7c4b69da7dc94e464183b5876b49a

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -1,5 +1,4 @@
 language: ruby
 rvm:
   - 1.9.3
-  - 1.8.7
-  - ree
+  - 2.0.0

data/Gemfile

@@ -1,2 +1,2 @@
 source "http://rubygems.org"
-gemspec
+gemspec

data/README.markdown

@@ -25,7 +25,7 @@ Let's say you have a form at "http://myapp.com/turkers/add_tags" where Turkers c
 
     RTurk.setup(YourAWSAccessKeyId, YourAWSAccessKey, :sandbox => true)
     hit = RTurk::Hit.create(:title => "Add some tags to a photo") do |hit|
-      hit.assignments = 2
+      hit.max_assignments = 2
       hit.description = 'blah'
       hit.question("http://myapp.com/turkers/add_tags",
                    :frame_height => 1000)  # pixels for iframe
@@ -82,6 +82,10 @@ Here's a quick peak at what happens on the Mechanical Turk side.
 
 A worker takes a look at your hit. The page will contain an iframe with your question URL loaded inside of it.
 
+If you want to use an Amazon-hosted [QuestionForm](http://docs.amazonwebservices.com/AWSMechTurk/2008-08-02/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html), do
+
+    hit.question_form "<Question>What color is the sky?</Question>" # not the real format
+
 Amazon will append the AssignmentID parameter to the URL for your own information. In preview mode this will look like
 
     http://myapp.com/turkers/add_tags?item_id=1234&AssignmentId=ASSIGNMENT_ID_NOT_AVAILABLE
@@ -101,14 +105,17 @@ Anything submitted in this form will be sent to Amazon and saved for your review
 
 ## More information
 
-Take a look at the [Amazon MTurk developer docs](http://docs.amazonwebservices.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/) for more information. They have a complete list of API operations, all of which can be called with this library.
+Take a look at the [Amazon MTurk developer docs](http://docs.amazonwebservices.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/) for more information. They have a complete list of API operations, many of which can be called with this library.
+
+Mark gave a [presentation about RTurk at the Atlanta Ruby User Group](http://www.atlruby.org/markpercival/posts/109-Mechanical-Turk-Ruby-Gem) that got recorded as a 20-minute screencast video.
 
 ## Contributors
 
-[Zach Hale](http://github.com/zachhale)  
-[David Balatero](http://github.com/dbalatero)  
-[Rob Hanlon](http://github.com/ohwillie)  
-[Haris Amin](http://github.com/hamin)  
-[Tyler](http://github.com/tkieft)  
-[David Dai](http://github.com/newtonsapple)  
+[Zach Hale](http://github.com/zachhale)
+[David Balatero](http://github.com/dbalatero)
+[Rob Hanlon](http://github.com/ohwillie)
+[Haris Amin](http://github.com/hamin)
+[Tyler](http://github.com/tkieft)
+[David Dai](http://github.com/newtonsapple)
+[Alex Chaffee](http://github.com/alexch)
 

data/examples/create_hit.rb

@@ -6,7 +6,7 @@ RTurk::setup(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
 hit = RTurk::Hit.create(:title => 'Write a tweet for me') do |hit|
   hit.description = 'Simply write a witty twitter update for my account'
   hit.reward = 0.05
-  hit.assignments = 1
+  hit.max_assignments = 1
   hit.question("http://mpercival.com.s3.amazonaws.com/newtweet.html")
 end
 

data/lib/rturk/adapters/assignment.rb

@@ -47,6 +47,8 @@ module RTurk
     def method_missing(method, *args)
       if self.source.respond_to?(method)
         self.source.send(method, *args)
+      else
+        super
       end
     end
   end

data/lib/rturk/adapters/hit.rb

@@ -10,7 +10,7 @@ module RTurk
   #
   #     RTurk.setup(YourAWSAccessKeyId, YourAWSAccessKey, :sandbox => true)
   #     hit = RTurk::Hit.create(:title => "Add some tags to a photo") do |hit|
-  #       hit.assignments = 2
+  #       hit.max_assignments = 2
   #       hit.question("http://myapp.com/turkers/add_tags")
   #       hit.reward = 0.05
   #       hit.qualifications.approval_rate, {:gt => 80}
@@ -40,14 +40,18 @@ module RTurk
       end
 
       def all_reviewable
-        RTurk.GetReviewableHITs.hit_ids.inject([]) do |arr, hit_id|
-          arr << new(hit_id); arr
+        [].tap do |hits|
+          RTurk.GetReviewableHITs.hit_ids.each do |hit_id|
+            hits << new(hit_id)
+          end
         end
       end
 
       def all
-        RTurk.SearchHITs.hits.inject([]) do |arr, hit|
-          arr << new(hit.id, hit); arr;
+        [].tap do |hits|
+          RTurk.SearchHITs.hits.each do |hit|
+            hits << new(hit.id, hit)
+          end
         end
       end
 
@@ -119,6 +123,8 @@ module RTurk
         @source.send(method, *args)
       elsif self.details.respond_to?(method)
         self.details.send(method)
+      else
+        super
       end
     end
   end

data/lib/rturk/builders/answer_key_builder.rb

@@ -0,0 +1,39 @@
+require "erector/xml_widget"
+
+# see http://docs.amazonwebservices.com/AWSMechTurk/2008-08-02/AWSMturkAPI/index.html?ApiReference_CreateQualificationTypeOperation.html
+class RTurk::AnswerKey < Erector::XMLWidget
+
+  XMLNS = "http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/AnswerKey.xsd"
+
+  %w{
+  AnswerKey
+    Question
+      QuestionIdentifier
+      AnswerOption
+        SelectionIdentifier
+        AnswerScore
+      DefaultScore
+    QualificationValueMapping
+      PercentageMapping
+        MaximumSummedScore
+      ScaleMapping
+        SummedScoreMultiplier
+      RangeMapping
+        SummedScoreRange
+          InclusiveLowerBound
+          InclusiveUpperBound
+          QualificationValue
+        OutOfRangeQualificationValue
+  }.uniq.each do |element_name|
+    tag element_name
+    tag element_name, :snake_case
+  end
+
+  def content
+    answer_key :xmlns => XMLNS do
+      answer_key_content
+    end
+  end
+
+end
+

data/lib/rturk/builders/{question_builder.rb → external_question_builder.rb}

@@ -2,51 +2,51 @@ require 'cgi'
 require 'uri'
 
 module RTurk
-  class Question
-    
+  class ExternalQuestion
+
     attr_accessor :url, :url_params, :frame_height
-    
+
     def initialize(url, opts = {})
       @url = url
       self.frame_height = opts.delete(:frame_height) || 400
       self.url_params = opts
     end
-    
+
     def querystring
       @url_params.collect { |key, value| [CGI.escape(key.to_s), CGI.escape(value.to_s)].join('=') }.join('&')
     end
-    
+
     def url
       unless querystring.empty?
         # slam the params onto url, if url already has params, add 'em with a &
-        u = @url.index('?') ? "#{@url}&#{querystring}" : "#{@url}?#{querystring}" 
+        u = @url.index('?') ? "#{@url}&#{querystring}" : "#{@url}?#{querystring}"
       else
         u = @url
       end
       CGI.escapeHTML(u) #URL should be XML/HTML escaped
     end
-    
+
     def params
       @url_params
     end
-    
+
     def params=(param_set)
       @url_params = param_set
     end
-    
+
     def to_params
       raise RTurk::MissingParameters, "needs a url to build an external question" unless @url
       # TODO: update the xmlns schema... maybe
       xml = <<-XML
 <ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
-  <ExternalURL>#{url}</ExternalURL>	
+  <ExternalURL>#{url}</ExternalURL>
   <FrameHeight>#{frame_height}</FrameHeight>
 </ExternalQuestion>
       XML
       xml
     end
-    
+
   end
-  
-  
-end
+
+
+end

data/lib/rturk/builders/qualification_builder.rb

@@ -9,10 +9,28 @@ module RTurk
     COMPARATORS = {:gt => 'GreaterThan', :lt => 'LessThan', :gte => 'GreaterThanOrEqualTo',
                    :lte => 'LessThanOrEqualTo', :eql => 'EqualTo', :not => 'NotEqualTo', :exists => 'Exists'}
 
-    TYPES = {:approval_rate => '000000000000000000L0', :submission_rate => '00000000000000000000',
-             :abandoned_rate => '00000000000000000070', :return_rate => '000000000000000000E0',
-             :rejection_rate => '000000000000000000S0', :hits_approved => '00000000000000000040',
-             :adult => '00000000000000000060', :country => '00000000000000000071'}
+    def self.types
+      system_qualification_types ||= {
+        :approval_rate => '000000000000000000L0', :submission_rate => '00000000000000000000',
+        :abandoned_rate => '00000000000000000070', :return_rate => '000000000000000000E0',
+        :rejection_rate => '000000000000000000S0', :hits_approved => '00000000000000000040',
+        :adult => '00000000000000000060', :country => '00000000000000000071',
+      }
+
+      # Amazon Master qualification ids vary between sandbox and real environments - see https://forums.aws.amazon.com/thread.jspa?threadID=70812
+      system_qualification_types.merge(if RTurk.sandbox?
+        {
+          :categorization_masters => '2F1KVCNHMVHV8E9PBUB2A4J79LU20F',
+          :photo_moderation_masters => '2TGBB6BFMFFOM08IBMAFGGESC1UWJX',
+        }
+      else
+        {
+          :categorization_masters => '2NDP2L92HECWY8NS8H3CK0CP5L9GHO',
+          :photo_moderation_masters => '21VZU98JHSTLZ5BPP4A9NOBJEK3DPG',
+        }
+      end)
+    end
+
 
     attr_accessor :qualifier
 
@@ -31,15 +49,17 @@ module RTurk
       if type.is_a?(String)
         qualifier[:QualificationTypeId] = type
       elsif type.is_a?(Symbol)
-        qualifier[:QualificationTypeId] = types[type]
+        qualifier[:QualificationTypeId] = Qualification.types[type]
       end
+
       if opts.is_a?(Hash)
         qualifier[:RequiredToPreview] = opts['RequiredToPreview'].to_s unless opts['RequiredToPreview'].nil?
         qualifier.merge!(build_comparator(opts))
       elsif opts == true || opts == false
-         qualifier[:IntegerValue] = opts == true ? 1 : 0
-         qualifier[:Comparator] = COMPARATORS[:eql]
+        qualifier[:IntegerValue] = opts == true ? 1 : 0
+        qualifier[:Comparator] = COMPARATORS[:eql]
       end
+
       qualifier
     end
 
@@ -53,11 +73,6 @@ module RTurk
       params
     end
 
-    def types
-      # Could use this later to add other TYPES programatically
-      TYPES
-    end
-
     private
 
     def build_comparator(opts)
@@ -65,6 +80,7 @@ module RTurk
       opts.each do |k,v|
         if COMPARATORS.has_key?(k)
           qualifier[:Comparator] = COMPARATORS[k]
+          next if v.nil?  # to allow :exists => nil
           if v.to_s.match(/[A-Z]./)
             qualifier[:Country] = v
           else

data/lib/rturk/builders/qualifications_builder.rb

@@ -32,8 +32,10 @@ module RTurk
 
 
     def method_missing(method, *args)
-      if RTurk::Qualification::TYPES.include?(method)
+      if RTurk::Qualification.types.include?(method)
         self.add(method, *args)
+      else
+        super
       end
     end
 

data/lib/rturk/builders/question_form_builder.rb

@@ -0,0 +1,86 @@
+require 'cgi'
+require 'uri'
+require "erector/xml_widget"
+
+module RTurk
+  # see http://docs.amazonwebservices.com/AWSMechTurk/2008-08-02/AWSMturkAPI/ApiReference_QuestionFormDataStructureArticle.html
+  # @param options hash (optional)
+  # ::xml:: raw xml (optional). If it starts with \<QuestionForm then it's used as the full QuestionForm value. Otherwise it is wrapped in a \<QuestionForm\> element. If it is nil then we use Erector to call its subclass' #question_form_content method.
+  class QuestionForm < Erector::XMLWidget
+
+    XMLNS = "http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd"
+
+    needs :xml => nil
+
+    def to_params
+      to_xml  # create a new output string and call 'content' via Erector
+    end
+
+    # todo: fill out Application subelements
+    # todo: fill out EmbeddedBinary subelements
+    %w{
+    QuestionForm
+      Overview
+        Title
+        List
+        Binary
+          MimeType
+            Type
+            SubType
+          DataURL
+          AltText
+        Application
+        EmbeddedBinary
+        FormattedContent
+
+      Question
+        QuestionIdentifier
+        DisplayName
+        IsRequired
+        QuestionContent
+        AnswerSpecification
+          FreeTextAnswer
+            Constraints
+              IsNumeric
+              Length
+              AnswerFormatRegex
+            DefaultText
+            NumberOfLinesSuggestion
+          SelectionAnswer
+            MinSelectionCount
+            MaxSelectionCount
+            StyleSuggestion
+            Selections
+              Selection
+                SelectionIdentifier
+                  Text
+                  FormattedContent
+                  Binary
+              OtherSelection
+          FileUploadAnswer
+            MaxFileSizeInBytes
+            MinFileSizeInBytes
+    }.uniq.each do |element_name|
+      tag element_name
+      tag element_name, :snake_case unless element_name == 'Text'
+    end
+
+    tag "Text", "text_element"  # very sticky since 'text' is a core Erector method
+
+    def content
+      if @xml and @xml.strip =~ /^<QuestionForm/
+        rawtext @xml
+      else
+        question_form :xmlns => XMLNS do
+          question_form_content
+        end
+      end
+    end
+
+    def question_form_content
+      rawtext @xml  # by default, use the parameter
+    end
+
+  end
+
+end

data/lib/rturk/operations/create_hit.rb

@@ -2,8 +2,8 @@ require File.join(File.dirname(__FILE__), 'register_hit_type')
 
 module RTurk
   class CreateHIT < RegisterHITType
-    attr_accessor :hit_type_id, :assignments, :lifetime, :note
-    
+    attr_accessor :hit_type_id, :max_assignments, :lifetime, :annotation
+
     def parse(response)
       RTurk::CreateHITResponse.new(response)
     end
@@ -11,22 +11,30 @@ module RTurk
     # Gives us access to a question builder attached to this HIT
     #
     # @param [String, Hash] URL Params, if none is passed, simply returns the question
-    # @return [RTurk::Question] The question if instantiated or nil
+    # @return [RTurk::ExternalQuestion] The question if instantiated or nil
     def question(*args)
       unless args.empty?
-        @question ||= RTurk::Question.new(*args)
+        @question ||= RTurk::ExternalQuestion.new(*args)
       else
         @question
       end
     end
 
+    def question_form(text_or_widget)
+      if text_or_widget.is_a? Erector::XMLWidget
+        @question = text_or_widget
+      else
+        @question = RTurk::QuestionForm.new(:xml => text)
+      end
+    end
+
     def to_params
       super.merge(
-        'HITTypeId'           => hit_type_id, 
-        'MaxAssignments'      => (assignments || 1),
+        'HITTypeId'           => hit_type_id,
+        'MaxAssignments'      => (max_assignments || 1),
         'Question'            => question.to_params,
         'LifetimeInSeconds'   => (lifetime || 3600),
-        'RequesterAnnotation' => note
+        'RequesterAnnotation' => annotation
       )
     end
 
@@ -41,7 +49,7 @@ module RTurk
         super # validate as RegisterHitType
       end
     end
-    
+
     def required_fields
       super << :question
     end