
mturk
*****


boto.mturk
==========


boto.mturk.connection
=====================

class class boto.mturk.connection.Assignment(connection)

   Class to extract an Assignment structure from a response (used in
   ResultSet)

   Will have attributes named as per the Developer Guide, e.g.
   AssignmentId, WorkerId, HITId, Answer, etc

   endElement(name, value, connection)

class class boto.mturk.connection.BaseAutoResultElement(connection)

   Base class to automatically add attributes when parsing XML

   endElement(name, value, connection)

   startElement(name, attrs, connection)

class class boto.mturk.connection.HIT(connection)

   Class to extract a HIT structure from a response (used in
   ResultSet)

   Will have attributes named as per the Developer Guide, e.g. HITId,
   HITTypeId, CreationTime

   expired

      Has this HIT expired yet?

class class boto.mturk.connection.HITTypeId(connection)

   Class to extract an HITTypeId structure from a response

class class boto.mturk.connection.MTurkConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, host=None, debug=0, https_connection_factory=None, security_token=None, profile_name=None)

   APIVersion = '2012-03-25'

   approve_assignment(assignment_id, feedback=None)

   approve_rejected_assignment(assignment_id, feedback=None)

   assign_qualification(qualification_type_id, worker_id, value=1, send_notification=True)

   block_worker(worker_id, reason)

      Block a worker from working on my tasks.

   change_hit_type_of_hit(hit_id, hit_type)

      Change the HIT type of an existing HIT. Note that the reward
      associated with the new HIT type must match the reward of the
      current HIT type in order for the operation to be valid.

   create_hit(hit_type=None, question=None, hit_layout=None, lifetime=datetime.timedelta(7), max_assignments=1, title=None, description=None, keywords=None, reward=None, duration=datetime.timedelta(7), approval_delay=None, annotation=None, questions=None, qualifications=None, layout_params=None, response_groups=None)

      Creates a new HIT. Returns a ResultSet See: http://docs.amazonwe
      bservices.com/AWSMechTurk/2012-03-25/AWSMturkAPI/ApiReference_Cr
      eateHITOperation.html

   create_qualification_type(name, description, status, keywords=None, retry_delay=None, test=None, answer_key=None, answer_key_xml=None, test_duration=None, auto_granted=False, auto_granted_value=1)

      Create a new Qualification Type.

      name: This will be visible to workers and must be unique for a
         given requester.

      description: description shown to workers.  Max 2000 characters.

      status: 'Active' or 'Inactive'

      keywords: list of keyword strings or comma separated string.
         Max length of 1000 characters when concatenated with commas.

      retry_delay: number of seconds after requesting a
         qualification the worker must wait before they can ask again.
         If not specified, workers can only request this qualification
         once.

      test: a QuestionForm

      answer_key: an XML string of your answer key, for automatically
         scored qualification tests. (Consider implementing an
         AnswerKey class for this to support.)

      test_duration: the number of seconds a worker has to complete
      the test.

      auto_granted: if True, requests for the Qualification are
      granted
         immediately.  Can't coexist with a test.

      auto_granted_value: auto_granted qualifications are given this
      value.

   disable_hit(hit_id, response_groups=None)

      Remove a HIT from the Mechanical Turk marketplace, approves all
      submitted assignments that have not already been approved or
      rejected, and disposes of the HIT and all assignment data.

      Assignments for the HIT that have already been submitted, but
      not yet approved or rejected, will be automatically approved.
      Assignments in progress at the time of the call to DisableHIT
      will be approved once the assignments are submitted. You will be
      charged for approval of these assignments.  DisableHIT
      completely disposes of the HIT and all submitted assignment
      data. Assignment results data cannot be retrieved for a HIT that
      has been disposed.

      It is not possible to re-enable a HIT once it has been disabled.
      To make the work from a disabled HIT available again, create a
      new HIT.

   dispose_hit(hit_id)

      Dispose of a HIT that is no longer needed.

      Only HITs in the "reviewable" state, with all submitted
      assignments approved or rejected, can be disposed. A Requester
      can call GetReviewableHITs to determine which HITs are
      reviewable, then call GetAssignmentsForHIT to retrieve the
      assignments.  Disposing of a HIT removes the HIT from the
      results of a call to GetReviewableHITs.

   dispose_qualification_type(qualification_type_id)

      TODO: Document.

   static duration_as_seconds(duration)

   expire_hit(hit_id)

      Expire a HIT that is no longer needed.

      The effect is identical to the HIT expiring on its own. The HIT
      no longer appears on the Mechanical Turk web site, and no new
      Workers are allowed to accept the HIT. Workers who have accepted
      the HIT prior to expiration are allowed to complete it or return
      it, or allow the assignment duration to elapse (abandon the
      HIT). Once all remaining assignments have been submitted, the
      expired HIT becomes"reviewable", and will be returned by a call
      to GetReviewableHITs.

   extend_hit(hit_id, assignments_increment=None, expiration_increment=None)

      Increase the maximum number of assignments, or extend the
      expiration date, of an existing HIT.

      NOTE: If a HIT has a status of Reviewable and the HIT is
      extended to make it Available, the HIT will not be returned by
      GetReviewableHITs, and its submitted assignments will not be
      returned by GetAssignmentsForHIT, until the HIT is Reviewable
      again.  Assignment auto-approval will still happen on its
      original schedule, even if the HIT has been extended. Be sure to
      retrieve and approve (or reject) submitted assignments before
      extending the HIT, if so desired.

   get_account_balance()

   get_all_hits()

      Return all of a Requester's HITs

      Despite what search_hits says, it does not return all hits, but
      instead returns a page of hits. This method will pull the hits
      from the server 100 at a time, but will yield the results
      iteratively, so subsequent requests are made on demand.

   get_all_qualifications_for_qual_type(qualification_type_id)

   get_assignment(assignment_id, response_groups=None)

      Retrieves an assignment using the assignment's ID. Requesters
      can only retrieve their own assignments, and only assignments
      whose related HIT has not been disposed.

      The returned ResultSet will have the following attributes:

      Request
         This element is present only if the Request ResponseGroup is
         specified.

      Assignment
         The assignment. The response includes one Assignment object.

      HIT
         The HIT associated with this assignment. The response
         includes one HIT object.

   get_assignments(hit_id, status=None, sort_by='SubmitTime', sort_direction='Ascending', page_size=10, page_number=1, response_groups=None)

      Retrieves completed assignments for a HIT. Use this operation to
      retrieve the results for a HIT.

      The returned ResultSet will have the following attributes:

      NumResults
         The number of assignments on the page in the filtered results
         list, equivalent to the number of assignments being returned
         by this call. A non-negative integer, as a string.

      PageNumber
         The number of the page in the filtered results list being
         returned. A positive integer, as a string.

      TotalNumResults
         The total number of HITs in the filtered results list based
         on this call. A non-negative integer, as a string.

      The ResultSet will contain zero or more Assignment objects

   get_help(about, help_type='Operation')

      Return information about the Mechanical Turk Service operations
      and response group NOTE - this is basically useless as it just
      returns the URL of the documentation

      help_type: either 'Operation' or 'ResponseGroup'

   get_hit(hit_id, response_groups=None)

   static get_keywords_as_string(keywords)

      Returns a comma+space-separated string of keywords from either a
      list or a string

   static get_price_as_price(reward)

      Returns a Price data structure from either a float or a Price

   get_qualification_requests(qualification_type_id, sort_by='Expiration', sort_direction='Ascending', page_size=10, page_number=1)

      TODO: Document.

   get_qualification_score(qualification_type_id, worker_id)

      TODO: Document.

   get_qualification_type(qualification_type_id)

   get_qualifications_for_qualification_type(qualification_type_id, page_size=100, page_number=1)

   get_reviewable_hits(hit_type=None, status='Reviewable', sort_by='Expiration', sort_direction='Ascending', page_size=10, page_number=1)

      Retrieve the HITs that have a status of Reviewable, or HITs that
      have a status of Reviewing, and that belong to the Requester
      calling the operation.

   grant_bonus(worker_id, assignment_id, bonus_price, reason)

      Issues a payment of money from your account to a Worker.  To be
      eligible for a bonus, the Worker must have submitted results for
      one of your HITs, and have had those results approved or
      rejected. This payment happens separately from the reward you
      pay to the Worker when you approve the Worker's assignment.  The
      Bonus must be passed in as an instance of the Price object.

   grant_qualification(qualification_request_id, integer_value=1)

      TODO: Document.

   notify_workers(worker_ids, subject, message_text)

      Send a text message to workers.

   register_hit_type(title, description, reward, duration, keywords=None, approval_delay=None, qual_req=None)

      Register a new HIT Type title, description are strings reward is
      a Price object duration can be a timedelta, or an object
      castable to an int

   reject_assignment(assignment_id, feedback=None)

   revoke_qualification(subject_id, qualification_type_id, reason=None)

      TODO: Document.

   search_hits(sort_by='CreationTime', sort_direction='Ascending', page_size=10, page_number=1, response_groups=None)

      Return a page of a Requester's HITs, on behalf of the Requester.
      The operation returns HITs of any status, except for HITs that
      have been disposed with the DisposeHIT operation. Note: The
      SearchHITs operation does not accept any search parameters that
      filter the results.

   search_qualification_types(query=None, sort_by='Name', sort_direction='Ascending', page_size=10, page_number=1, must_be_requestable=True, must_be_owned_by_caller=True)

      TODO: Document.

   send_test_event_notification(hit_type, url, event_types=None, test_event_type='Ping')

      Performs a SendTestEventNotification operation with REST
      notification for a specified HIT type

   set_email_notification(hit_type, email, event_types=None)

      Performs a SetHITTypeNotification operation to set email
      notification for a specified HIT type

   set_rest_notification(hit_type, url, event_types=None)

      Performs a SetHITTypeNotification operation to set REST
      notification for a specified HIT type

   set_reviewing(hit_id, revert=None)

      Update a HIT with a status of Reviewable to have a status of
      Reviewing, or reverts a Reviewing HIT back to the Reviewable
      status.

      Only HITs with a status of Reviewable can be updated with a
      status of Reviewing.  Similarly, only Reviewing HITs can be
      reverted back to a status of Reviewable.

   set_sqs_notification(hit_type, queue_url, event_types=None)

      Performs a SetHITTypeNotification operation so set SQS
      notification for a specified HIT type. Queue URL is of form:
      https://queue.amazonaws.com/<CUSTOMER_ID>/<QUEUE_NAME> and can
      be found when looking at the details for a Queue in the AWS
      Console

   unblock_worker(worker_id, reason)

      Unblock a worker from working on my tasks.

   update_qualification_score(qualification_type_id, worker_id, value)

      TODO: Document.

   update_qualification_type(qualification_type_id, description=None, status=None, retry_delay=None, test=None, answer_key=None, test_duration=None, auto_granted=None, auto_granted_value=None)

exception exception boto.mturk.connection.MTurkRequestError(status, reason, body=None)

   Error for MTurk Requests

class class boto.mturk.connection.Qualification(connection)

   Class to extract an Qualification structure from a response (used
   in ResultSet)

   Will have attributes named as per the Developer Guide such as
   QualificationTypeId, IntegerValue. Does not seem to contain
   GrantTime.

class class boto.mturk.connection.QualificationRequest(connection)

   Class to extract an QualificationRequest structure from a response
   (used in ResultSet)

   Will have attributes named as per the Developer Guide, e.g.
   QualificationRequestId, QualificationTypeId, SubjectId, etc

   endElement(name, value, connection)

class class boto.mturk.connection.QualificationType(connection)

   Class to extract an QualificationType structure from a response
   (used in ResultSet)

   Will have attributes named as per the Developer Guide, e.g.
   QualificationTypeId, CreationTime, Name, etc

class class boto.mturk.connection.QuestionFormAnswer(connection)

   Class to extract Answers from inside the embedded XML
   QuestionFormAnswers element inside the Answer element which is part
   of the Assignment and QualificationRequest structures

   A QuestionFormAnswers element contains an Answer element for each
   question in the HIT or Qualification test for which the Worker
   provided an answer. Each Answer contains a QuestionIdentifier
   element whose value corresponds to the QuestionIdentifier of a
   Question in the QuestionForm. See the QuestionForm data structure
   for more information about questions and answer specifications.

   If the question expects a free-text answer, the Answer element
   contains a FreeText element. This element contains the Worker's
   answer

   *NOTE* - currently really only supports free-text and selection
   answers

   endElement(name, value, connection)


boto.mturk.layoutparam
======================

class class boto.mturk.layoutparam.LayoutParameter(name, value)

   Representation of a single HIT layout parameter

   get_as_params()

class class boto.mturk.layoutparam.LayoutParameters(layoutParameters=None)

   add(req)

   get_as_params()


boto.mturk.notification
=======================

Provides NotificationMessage and Event classes, with utility methods,
for implementations of the Mechanical Turk Notification API.

class class boto.mturk.notification.Event(d)

class class boto.mturk.notification.NotificationMessage(d)

   Constructor; expects parameter d to be a dict of string parameters
   from a REST transport notification message

   EVENT_PATTERN = 'Event\\.(?P<n>\\d+)\\.(?P<param>\\w+)'

   EVENT_RE = <_sre.SRE_Pattern object at 0xb8c5aa88>

   NOTIFICATION_VERSION = '2006-05-05'

   NOTIFICATION_WSDL = 'http://mechanicalturk.amazonaws.com/AWSMechanicalTurk/2006-05-05/AWSMechanicalTurkRequesterNotification.wsdl'

   OPERATION_NAME = 'Notify'

   SERVICE_NAME = 'AWSMechanicalTurkRequesterNotification'

   verify(secret_key)

      Verifies the authenticity of a notification message.

      TODO: This is doing a form of authentication and
         this functionality should really be merged with the pluggable
         authentication mechanism at some point.


boto.mturk.price
================

class class boto.mturk.price.Price(amount=0.0, currency_code='USD')

   endElement(name, value, connection)

   get_as_params(label, ord=1)

   startElement(name, attrs, connection)


boto.mturk.qualification
========================

class class boto.mturk.qualification.AdultRequirement(comparator, integer_value, required_to_preview=False)

   Requires workers to acknowledge that they are over 18 and that they
   agree to work on potentially offensive content. The value type is
   boolean, 1 (required), 0 (not required, the default).

class class boto.mturk.qualification.LocaleRequirement(comparator, locale, required_to_preview=False)

   A Qualification requirement based on the Worker's location. The
   Worker's location is specified by the Worker to Mechanical Turk
   when the Worker creates his account.

   get_as_params()

class class boto.mturk.qualification.NumberHitsApprovedRequirement(comparator, integer_value, required_to_preview=False)

   Specifies the total number of HITs submitted by a Worker that have
   been approved. The value is an integer greater than or equal to 0.

class class boto.mturk.qualification.PercentAssignmentsAbandonedRequirement(comparator, integer_value, required_to_preview=False)

   The percentage of assignments the Worker has abandoned (allowed the
   deadline to elapse), over all assignments the Worker has accepted.
   The value is an integer between 0 and 100.

class class boto.mturk.qualification.PercentAssignmentsApprovedRequirement(comparator, integer_value, required_to_preview=False)

   The percentage of assignments the Worker has submitted that were
   subsequently approved by the Requester, over all assignments the
   Worker has submitted. The value is an integer between 0 and 100.

class class boto.mturk.qualification.PercentAssignmentsRejectedRequirement(comparator, integer_value, required_to_preview=False)

   The percentage of assignments the Worker has submitted that were
   subsequently rejected by the Requester, over all assignments the
   Worker has submitted. The value is an integer between 0 and 100.

class class boto.mturk.qualification.PercentAssignmentsReturnedRequirement(comparator, integer_value, required_to_preview=False)

   The percentage of assignments the Worker has returned, over all
   assignments the Worker has accepted. The value is an integer
   between 0 and 100.

class class boto.mturk.qualification.PercentAssignmentsSubmittedRequirement(comparator, integer_value, required_to_preview=False)

   The percentage of assignments the Worker has submitted, over all
   assignments the Worker has accepted. The value is an integer
   between 0 and 100.

class class boto.mturk.qualification.Qualifications(requirements=None)

   add(req)

   get_as_params()

class class boto.mturk.qualification.Requirement(qualification_type_id, comparator, integer_value=None, required_to_preview=False)

   Representation of a single requirement

   get_as_params()


boto.mturk.question
===================

class class boto.mturk.question.AnswerSpecification(spec)

   get_as_xml()

   template = '<AnswerSpecification>%(spec)s</AnswerSpecification>'

class class boto.mturk.question.Application(width, height, **parameters)

   get_as_xml()

   get_inner_content(content)

   parameter_template = '<Name>%(name)s</Name><Value>%(value)s</Value>'

   template = '<Application><%(class_)s>%(content)s</%(class_)s></Application>'

class class boto.mturk.question.Binary(type, subtype, url, alt_text)

   template = '<Binary><MimeType><Type>%(type)s</Type><SubType>%(subtype)s</SubType></MimeType><DataURL>%(url)s</DataURL><AltText>%(alt_text)s</AltText></Binary>'

class class boto.mturk.question.Constraint

   get_as_xml()

   get_attributes()

class class boto.mturk.question.Constraints

   get_as_xml()

   template = '<Constraints>%(content)s</Constraints>'

class class boto.mturk.question.ExternalQuestion(external_url, frame_height)

   An object for constructing an External Question.

   get_as_params(label='ExternalQuestion')

   get_as_xml()

   schema_url = 'http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd'

   template = '<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd"><ExternalURL>%(external_url)s</ExternalURL><FrameHeight>%(frame_height)s</FrameHeight></ExternalQuestion>'

class class boto.mturk.question.FileUploadAnswer(min_bytes, max_bytes)

   get_as_xml()

   template = '<FileUploadAnswer><MaxFileSizeInBytes>%(max_bytes)d</MaxFileSizeInBytes><MinFileSizeInBytes>%(min_bytes)d</MinFileSizeInBytes></FileUploadAnswer>'

class class boto.mturk.question.Flash(url, *args, **kwargs)

   get_inner_content(content)

class class boto.mturk.question.FormattedContent(content)

   schema_url = 'http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/FormattedContentXHTMLSubset.xsd'

   template = '<FormattedContent><![CDATA[%(content)s]]></FormattedContent>'

class class boto.mturk.question.FreeTextAnswer(default=None, constraints=None, num_lines=None)

   get_as_xml()

   template = '<FreeTextAnswer>%(items)s</FreeTextAnswer>'

class class boto.mturk.question.HTMLQuestion(html_form, frame_height)

   get_as_params(label='HTMLQuestion')

   get_as_xml()

   schema_url = 'http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd'

   template = '<HTMLQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd"><HTMLContent><![CDATA[<!DOCTYPE html>%(html_form)s]]></HTMLContent><FrameHeight>%(frame_height)s</FrameHeight></HTMLQuestion>'

class class boto.mturk.question.JavaApplet(path, filename, *args, **kwargs)

   get_inner_content(content)

class class boto.mturk.question.LengthConstraint(min_length=None, max_length=None)

   attribute_names = ('minLength', 'maxLength')

   template = '<Length %(attrs)s />'

class class boto.mturk.question.List

   A bulleted list suitable for OrderedContent or Overview content

   get_as_xml()

class class boto.mturk.question.NumberOfLinesSuggestion(num_lines=1)

   get_as_xml()

   template = '<NumberOfLinesSuggestion>%(num_lines)s</NumberOfLinesSuggestion>'

class class boto.mturk.question.NumericConstraint(min_value=None, max_value=None)

   attribute_names = ('minValue', 'maxValue')

   template = '<IsNumeric %(attrs)s />'

class class boto.mturk.question.OrderedContent

   append_field(field, value)

   get_as_xml()

class class boto.mturk.question.Overview

   get_as_params(label='Overview')

   get_as_xml()

   template = '<Overview>%(content)s</Overview>'

class class boto.mturk.question.Question(identifier, content, answer_spec, is_required=False, display_name=None)

   get_as_params(label='Question')

   get_as_xml()

   template = '<Question>%(items)s</Question>'

class class boto.mturk.question.QuestionContent

   get_as_xml()

   template = '<QuestionContent>%(content)s</QuestionContent>'

class class boto.mturk.question.QuestionForm

   From the AMT API docs:

   The top-most element of the QuestionForm data structure is a
   QuestionForm element. This element contains optional Overview
   elements and one or more Question elements. There can be any number
   of these two element types listed in any order. The following
   example structure has an Overview element and a Question element
   followed by a second Overview element and Question element--all
   within the same QuestionForm.

      <QuestionForm xmlns="[the QuestionForm schema URL]">
          <Overview>
              [...]
          </Overview>
          <Question>
              [...]
          </Question>
          <Overview>
              [...]
          </Overview>
          <Question>
              [...]
          </Question>
          [...]
      </QuestionForm>

   QuestionForm is implemented as a list, so to construct a
   QuestionForm, simply append Questions and Overviews (with at least
   one Question).

   get_as_xml()

   is_valid()

   schema_url = 'http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd'

   xml_template = '<QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd">%(items)s</QuestionForm>'

class class boto.mturk.question.RegExConstraint(pattern, error_text=None, flags=None)

   attribute_names = ('regex', 'errorText', 'flags')

   get_attributes()

   template = '<AnswerFormatRegex %(attrs)s />'

class class boto.mturk.question.SelectionAnswer(min=1, max=1, style=None, selections=None, type='text', other=False)

   A class to generate SelectionAnswer XML data structures. Does not
   yet implement Binary selection options.

   ACCEPTED_STYLES = ['radiobutton', 'dropdown', 'checkbox', 'list', 'combobox', 'multichooser']

   MAX_SELECTION_COUNT_XML_TEMPLATE = '<MaxSelectionCount>%s</MaxSelectionCount>'

   MIN_SELECTION_COUNT_XML_TEMPLATE = '<MinSelectionCount>%s</MinSelectionCount>'

   OTHER_SELECTION_ELEMENT_NAME = 'OtherSelection'

   SELECTIONANSWER_XML_TEMPLATE = '<SelectionAnswer>%s%s<Selections>%s</Selections></SelectionAnswer>'

   SELECTION_VALUE_XML_TEMPLATE = '<%s>%s</%s>'

   SELECTION_XML_TEMPLATE = '<Selection><SelectionIdentifier>%s</SelectionIdentifier>%s</Selection>'

   STYLE_XML_TEMPLATE = '<StyleSuggestion>%s</StyleSuggestion>'

   get_as_xml()

class class boto.mturk.question.SimpleField(field, value)

   A Simple name/value pair that can be easily rendered as XML.

   >>> SimpleField('Text', 'A text string').get_as_xml()
   '<Text>A text string</Text>'

   template = '<%(field)s>%(value)s</%(field)s>'

class class boto.mturk.question.ValidatingXML

   validate()

class class boto.mturk.question.XMLTemplate

   get_as_xml()
