mturk — boto v2.21.1

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.21.1 »

# mturk

## boto.mturk

## boto.mturk.connection

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 `boto.mturk.connection.` `BaseAutoResultElement`(connection)

  Base class to automatically add attributes when parsing XML

  `endElement`(name, value, connection)
  `startElement`(name, attrs, connection)

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 `boto.mturk.connection.` `HITTypeId`(connection)

  Class to extract an HITTypeId structure from a response

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)
  `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.amazonwebservices.com/AWSMechTurk/2012-03-25/AWSMturkAPI/ApiReference_CreateHITOperation.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
    PageNumber
      The number of the page in the filtered results list being returned. A positive integer
    TotalNumResults
      The total number of HITs in the filtered results list based on this call. A non-negative integer

    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 `boto.mturk.connection.` `MTurkRequestError`(status, reason, body=None)

  Error for MTurk Requests

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 `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 `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 `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 `boto.mturk.layoutparam.` `LayoutParameter`(name, value)

  Representation of a single HIT layout parameter

  `get_as_params`()

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 `boto.mturk.notification.` `Event`(d)

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 0x105d5f8a0>
  `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `boto.mturk.qualification.` `Qualifications`(requirements=None)
  `add`(req)
  `get_as_params`()

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 `boto.mturk.question.` `AnswerSpecification`(spec)
  `get_as_xml`()
  `template` = '<AnswerSpecification>%(spec)s</AnswerSpecification>'

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 `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 `boto.mturk.question.` `Constraint`
  `get_as_xml`()
  `get_attributes`()

class `boto.mturk.question.` `Constraints`
  `get_as_xml`()
  `template` = '<Constraints>%(content)s</Constraints>'

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 `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 `boto.mturk.question.` `Flash`(url, *args, **kwargs)
  `get_inner_content`(content)

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 `boto.mturk.question.` `FreeTextAnswer`(default=None, constraints=None, num_lines=None)
  `get_as_xml`()
  `template` = '<FreeTextAnswer>%(items)s</FreeTextAnswer>'

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 `boto.mturk.question.` `JavaApplet`(path, filename, *args, **kwargs)
  `get_inner_content`(content)

class `boto.mturk.question.` `LengthConstraint`(min_length=None, max_length=None)
  `attribute_names` = ('minLength', 'maxLength')
  `template` = '<Length %(attrs)s />'

class `boto.mturk.question.` `List`

  A bulleted list suitable for OrderedContent or Overview content

  `get_as_xml`()

class `boto.mturk.question.` `NumberOfLinesSuggestion`(num_lines=1)
  `get_as_xml`()
  `template` = '<NumberOfLinesSuggestion>%(num_lines)s</NumberOfLinesSuggestion>'

class `boto.mturk.question.` `NumericConstraint`(min_value=None, max_value=None)
  `attribute_names` = ('minValue', 'maxValue')
  `template` = '<IsNumeric %(attrs)s />'

class `boto.mturk.question.` `OrderedContent`
  `append_field`(field, value)
  `get_as_xml`()

class `boto.mturk.question.` `Overview`
  `get_as_params`(label='Overview')
  `get_as_xml`()
  `template` = '<Overview>%(content)s</Overview>'

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 `boto.mturk.question.` `QuestionContent`
  `get_as_xml`()
  `template` = '<QuestionContent>%(content)s</QuestionContent>'

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 `boto.mturk.question.` `RegExConstraint`(pattern, error_text=None, flags=None)
  `attribute_names` = ('regex', 'errorText', 'flags')
  `get_attributes`()
  `template` = '<AnswerFormatRegex %(attrs)s />'

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 `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 `boto.mturk.question.` `ValidatingXML`
  `validate`()

class `boto.mturk.question.` `XMLTemplate`
  `get_as_xml`()

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.21.1 »