rturk 1.0.5 → 2.0.0

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "doc"]
+	path = doc
+	url = git@github.com:markpercival/rturk.git

data/README.markdown

@@ -11,7 +11,7 @@ You'd be better off with amazon's official library, in all its XML cruftiness.
 
 ## Installation
 
-    sudo gem install markpercival-rturk --source http://gems.github.com
+    sudo gem install rturk --source http://gemcutter.org
     
 ## Use
 
@@ -21,42 +21,62 @@ Let's say you have a form at "http://myapp.com/turkers/add_tags" where Turkers c
 
     require 'rturk'
 
-    props = {:Title=>"Add tags to an item", 
-             :MaxAssignments=>1, :LifetimeInSeconds=>3600, 
-             :Reward=>{:Amount=>0.05, :CurrencyCode=>"USD"}, 
-             :Keywords=>"twitter, blogging, writing, english", 
-             :Description=>"Simply add some tags for me",
-             :RequesterAnnotation=>"Example1",
-             :AssignmentDurationInSeconds=>3600, :AutoApprovalDelayInSeconds=>3600, 
-             :QualificationRequirement=>[{
-               # Approval rate of greater than 90%
-               :QualificationTypeId=>"000000000000000000L0", 
-               :IntegerValue=>90, 
-               :Comparator=>"GreaterThan", 
-               :RequiredToPreview=>"false"
-               }]
-            }
-
-    @turk = RTurk::Requester.new(AWSAccessKeyId, AWSAccessKey, :sandbox => true)
-    page = RTurk::ExternalQuestionBuilder.build(
-      "http://myapp.com/turkers/add_tags", :item_id => '1234')
+    RTurk.setup(YourAWSAccessKeyId, YourAWSAccessKey, :sandbox => true)
+    hit = RTurk::Hit.create(:title => "Add some tags to a photo") do |hit|
+      hit.assignments = 2
+      hit.question("http://myapp.com/turkers/add_tags")
+      hit.reward = 0.05
+      hit.qualifications.approval_rate, {:gt => 80}
+    end
     
-    # Turkers will be directed to http://myapp.com/turkers/add_tags?item_id=1234&AssignmentId=abcd12345
-
-    p @turk.create_hit(props, page)
+    p hit.url #=>  'https://workersandbox.mturk.com:443/mturk/preview?groupId=Q29J3XZQ1ASZH5YNKZDZ'
     
-### Reviewing HIT's
-
-    require 'rturk'
-    @turk = RTurk::Requester.new(AWSAccessKeyId, AWSAccessKey, :sandbox => true)
+### Reviewing and Approving hits HIT's
+
+    hits = RTurk::Hit.all_reviewable
+
+    puts "#{hits.size} reviewable hits. \n"
+
+    unless hits.empty?
+      puts "Reviewing all assignments"
+  
+      hits.each do |hit|
+        hit.assignments.each do |assignment|
+          puts assignment.answers['tags']
+          assignment.approve! if assignment.status == 'Submitted'
+        end
+      end
+    end
+  
+### Wiping all your hits out
+
+    hits = RTurk::Hit.all_reviewable
+
+    puts "#{hits.size} reviewable hits. \n"
+
+    unless hits.empty?
+      puts "Approving all assignments and disposing of each hit!"
+  
+      hits.each do |hit|
+        hit.expire!
+        hit.assignments.each do |assignment|
+          assignment.approve!
+        end
+        hit.dispose!
+      end
+    end
+    
+    
+### Logging
+Want to see what's going on - enable logging.
 
-    p @turk.getAssignmentsForHIT(:HITId => 'abcde1234567890')
+RTurk::Logger.level = Logger::DEBUG
     
 ## Nitty Gritty
 
 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 external URL loaded inside of it.
+A worker takes a look at your hit. The page will contain an iframe with your question URL loaded inside of it.
 
 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

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+require 'yard'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rturk"
+    gem.summary = %Q{Mechanical Turk API Wrapper}
+    gem.email = "mark@mpercival.com"
+    gem.homepage = "http://github.com/markpercival/rturk"
+    gem.authors = ["Mark Percival"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rturk-gem #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'lib/**/*.rb']
+end

data/TODO.markdown

@@ -0,0 +1,3 @@
+Fakeweb all requests, should be able to turn off
+Better error handling and checking
+Operations should include request?

data/VERSION

@@ -1 +1 @@
-1.0.3
+2.0.0

data/examples/blank_slate.rb

@@ -1,6 +1,23 @@
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'rubygems'
 require '../lib/rturk'
-root = File.expand_path(File.dirname(__FILE__))
-aws = YAML.load(File.open(File.join(root, 'mturk.yml')))
-@turk = RTurk::Requester.new(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
 
-@turk.blank_slate
+aws = YAML.load(File.open(File.join(File.dirname(__FILE__), 'mturk.yml')))
+RTurk::setup(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
+
+hits = RTurk::Hit.all_reviewable
+
+puts "#{hits.size} reviewable hits. \n"
+
+unless hits.empty?
+  puts "Approving all assignments and disposing of each hit!"
+  
+  hits.each do |hit|
+    hit.expire!
+    hit.assignments.each do |assignment|
+      assignment.approve!
+    end
+    hit.dispose!
+  end
+end
+

data/examples/create_hit.rb

@@ -0,0 +1,19 @@
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'rubygems'
+require '../lib/rturk'
+
+aws = YAML.load(File.open(File.join(File.dirname(__FILE__), 'mturk.yml')))
+RTurk::setup(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
+
+root = File.expand_path(File.dirname(__FILE__))
+aws = YAML.load(File.open(File.join(root, 'mturk.yml')))
+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.question("http://mpercival.com.s3.amazonaws.com/newtweet.html")
+end
+
+p hit.url

data/examples/newtweet.html

@@ -55,7 +55,6 @@
   <li>MUST BE LESS THAN 120 CHARACTERS</li>
   <li>Could be about an interesting topic or current event</li>
   <li>Could also make up something about what I'm currently doing</li>
-  <li>Should not be vulgar or crass</li>
 
   <li>Should fool people into thinking I am clever and witty</li>
 </ul>

data/examples/review_answer.rb

@@ -1,8 +1,21 @@
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'rubygems'
 require '../lib/rturk'
-root = File.expand_path(File.dirname(__FILE__))
-aws = YAML.load(File.open(File.join(root, 'mturk.yml')))
-@turk = RTurk::Requester.new(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
 
-last_hit = File.open(File.join(root, 'last_hit'), 'r').read
+aws = YAML.load(File.open(File.join(File.dirname(__FILE__), 'mturk.yml')))
+RTurk::setup(aws['AWSAccessKeyId'], aws['AWSAccessKey'], :sandbox => true)
 
-p @turk.getAssignmentsForHIT(:HITId => last_hit)
+hits = RTurk::Hit.all_reviewable
+
+puts "#{hits.size} reviewable hits. \n"
+
+unless hits.empty?
+  puts "Reviewing all assignments"
+  
+  hits.each do |hit|
+    hit.assignments.each do |assignment|
+      puts assignment.answers['tweet']
+      assignment.approve! if assignment.status == 'Submitted'
+    end
+  end
+end

data/lib/rturk.rb

@@ -1,11 +1,38 @@
 module RTurk
-end
+  require 'rturk/logger'
+
+  SANDBOX = 'http://mechanicalturk.sandbox.amazonaws.com/'
+  PRODUCTION = 'http://mechanicalturk.amazonaws.com/'
+  class << self
+    attr_reader :access_key, :secret_key, :host
+
+    def setup(access_key, secret_key, opts ={})
+      @access_key = access_key
+      @secret_key = secret_key
+      @host = opts[:sandbox] ? SANDBOX : PRODUCTION
+    end
+    
+    def sandbox?
+      @host == SANDBOX
+    end
+    
+    def log
+      RTurk::Logger.logger
+    end
 
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+  end
+
+end
 
 require 'rturk/utilities'
-require 'rturk/custom_operations'
-require 'rturk/answer'
-require 'rturk/external_question_builder'
+require 'rturk/xml_utilities'
 require 'rturk/requester'
+require 'rturk/response'
+Dir.glob(File.join(File.dirname(__FILE__), 'rturk', 'responses', '*.rb')).each {|f| require f }
+require 'rturk/operation'
+Dir.glob(File.join(File.dirname(__FILE__), 'rturk', 'operations', '*.rb')).each {|f| require f }
+Dir.glob(File.join(File.dirname(__FILE__), 'rturk', 'builders', '*.rb')).each {|f| require f }
+Dir.glob(File.join(File.dirname(__FILE__), 'rturk', 'adapters', '*.rb')).each {|f| require f }
+Dir.glob(File.join(File.dirname(__FILE__), 'rturk', 'parsers', '*.rb')).each {|f| require f }
+
+require 'rturk/errors'

data/lib/rturk/adapters/answers.rb

@@ -0,0 +1,38 @@
+require 'cgi'
+
+module RTurk
+  class Answers
+
+    attr_accessor :answer_hash
+
+    def initialize(xml)
+      answer_xml = Nokogiri::XML(CGI.unescapeHTML(xml))
+      @answer_hash = {}
+      answers = answer_xml.xpath('//xmlns:Answer')
+      answers.each do |answer|
+        key, value = nil, nil
+        answer.children.each do |child|
+          next if child.blank?
+          if child.name == 'QuestionIdentifier'
+            key = child.inner_text
+          else
+            value = child.inner_text
+          end
+        end
+        @answer_hash[key] = value
+      end
+    end
+    
+    
+    # @param [<String, Symbol>] The string or symbol of the question name
+    # @return [String] The value of the question name
+    def [](key)
+      @answer_hash[key]
+    end
+    
+    def to_hash
+      @answer_hash
+    end
+
+  end
+end

data/lib/rturk/adapters/assignment.rb

@@ -0,0 +1,75 @@
+require 'time'
+
+module RTurk
+  
+  # Parses:
+  # <Assignment>
+  #   <AssignmentId>GYFTRHZ5J3DZREY48WNZE38ZR9RR1ZPMXGWE7WE0</AssignmentId>
+  #   <WorkerId>AD20WXZZP9XXK</WorkerId>
+  #   <HITId>GYFTRHZ5J3DZREY48WNZ</HITId>
+  #   <AssignmentStatus>Approved</AssignmentStatus>
+  #   <AutoApprovalTime>2009-08-12T19:21:54Z</AutoApprovalTime>
+  #   <AcceptTime>2009-07-13T19:21:40Z</AcceptTime>
+  #   <SubmitTime>2009-07-13T19:21:54Z</SubmitTime>
+  #   <ApprovalTime>2009-07-13T19:27:54Z</ApprovalTime>
+  #   <Answer>
+  #     <?xml version="1.0" encoding="UTF-8"?>
+  #     <QuestionFormAnswers xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionFormAnswers.xsd">
+  #       <Answer>
+  #         <QuestionIdentifier>Question100</QuestionIdentifier>
+  #         <FreeText>Move to X.</FreeText>
+  #       </Answer>
+  #     </QuestionFormAnswers>
+  #   </Answer>
+  # </Assignment>
+  
+  class Assignment
+    include RTurk::XmlUtilities
+    
+    attr_accessor :worker_id, :id, :status, :submitted_at, :accepted_at, :approved_at
+    attr_reader :answers
+    
+    def initialize(xml_object)
+      map_content(xml_object,
+        :id => 'AssignmentId',
+        :worker_id => 'WorkerId',
+        :status => 'AssignmentStatus',
+        :accepted_at => 'AcceptTime',
+        :approved_at => "ApprovalTime",
+        :submitted_at => 'SubmitTime')
+        self.answers = xml_object.xpath('Answer').children.to_s
+    end
+    
+    def approved_at=(time)
+      @approved_at = Time.parse(time)
+    end
+    
+    def submitted_at=(time)
+      @submitted_at = Time.parse(time)
+    end
+
+    def accepted_at=(time)
+      @accepted_at = Time.parse(time)
+    end
+    
+    def approve!(feedback = nil)
+      RTurk::ApproveAssignment(:assignment_id => self.id, :feedback => feedback)
+    end
+    
+    def reject!(reason)
+      RTurk::ApproveAssignment(:assignment_id => self.id, :feedback => reason)
+    end
+    
+    def bonus!(amount, reason)
+     RTurk::GrantBonus(:amount, :feedback => reason)
+    end
+    
+    def answers=(answer_xml)
+      unless answer_xml.empty?
+        @answers = RTurk::Answers.new(answer_xml)
+      end
+    end
+    
+  end
+  
+end

data/lib/rturk/adapters/hit.rb

@@ -0,0 +1,97 @@
+module RTurk
+
+  # =The RTurk Hit Adapter
+  # 
+  # Lets us interact with Mechanical Turk without having to know all the operations.
+  #
+  # == Basic usage
+  # @example
+  #     require 'rturk'
+  # 
+  #     RTurk.setup(YourAWSAccessKeyId, YourAWSAccessKey, :sandbox => true)
+  #     hit = RTurk::Hit.create(:title => "Add some tags to a photo") do |hit|
+  #       hit.assignments = 2
+  #       hit.question("http://myapp.com/turkers/add_tags")
+  #       hit.reward = 0.05
+  #       hit.qualifications.approval_rate, {:gt => 80}
+  #     end
+  #     
+  #     hit.url #=>  'http://mturk.amazonaws.com/?group_id=12345678'
+  
+  
+  class Hit
+    include RTurk::XmlUtilities
+
+    class << self;
+
+      def create(*args, &blk)
+        response = RTurk::CreateHIT(*args, &blk)
+        response.hit
+      end
+      
+      def find(id)
+        
+      end
+      
+      def all_reviewable
+        RTurk.GetReviewableHITs.hits
+      end
+
+    end
+
+    attr_accessor :id
+
+    def initialize(id, type = nil)
+      @id, @type = id, type
+    end
+
+    def assignments
+      RTurk::GetAssignmentsForHIT(:hit_id => self.id).assignments
+    end
+
+    def type_id
+      @type_id ||= details.type_id
+    end
+    
+    def status
+      @status ||= details.status
+    end
+    
+    def expires_at
+      @expires_at ||= details.expires_at
+    end
+
+    def title
+      @title ||= details.title
+    end
+    
+    def details
+      @details ||= RTurk::GetHIT(:hit_id => self.id)
+    end
+     
+    def expire!
+      RTurk::ForceExpireHIT(:hit_id => self.id)
+    end
+    
+    def dispose!
+      RTurk::DisposeHIT(:hit_id => self.id) 
+    end
+    
+    def disable!
+      RTurk::DisableHIT(:hit_id => self.id) 
+    end
+
+
+    def url
+      if RTurk.sandbox?
+        "http://workersandbox.mturk.com/mturk/preview?groupId=#{self.type_id}" # Sandbox Url
+      else
+        "http://mturk.com/mturk/preview?groupId=#{self.type_id}" # Production Url
+      end
+    end
+
+
+
+  end
+
+end