/boto-2.5.2/boto/mturk/connection.py
Python | 920 lines | 765 code | 50 blank | 105 comment | 28 complexity | e2099f4b275b2b556a8adaf6e3bbf63d MD5 | raw file
- # Copyright (c) 2006,2007 Mitch Garnaat http://garnaat.org/
- #
- # Permission is hereby granted, free of charge, to any person obtaining a
- # copy of this software and associated documentation files (the
- # "Software"), to deal in the Software without restriction, including
- # without limitation the rights to use, copy, modify, merge, publish, dis-
- # tribute, sublicense, and/or sell copies of the Software, and to permit
- # persons to whom the Software is furnished to do so, subject to the fol-
- # lowing conditions:
- #
- # The above copyright notice and this permission notice shall be included
- # in all copies or substantial portions of the Software.
- #
- # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
- # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
- # ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
- # SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
- # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
- # IN THE SOFTWARE.
- import xml.sax
- import datetime
- import itertools
- from boto import handler
- from boto import config
- from boto.mturk.price import Price
- import boto.mturk.notification
- from boto.connection import AWSQueryConnection
- from boto.exception import EC2ResponseError
- from boto.resultset import ResultSet
- from boto.mturk.question import QuestionForm, ExternalQuestion
- class MTurkRequestError(EC2ResponseError):
- "Error for MTurk Requests"
- # todo: subclass from an abstract parent of EC2ResponseError
- class MTurkConnection(AWSQueryConnection):
-
- APIVersion = '2008-08-02'
-
- def __init__(self, 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):
- if not host:
- if config.has_option('MTurk', 'sandbox') and config.get('MTurk', 'sandbox') == 'True':
- host = 'mechanicalturk.sandbox.amazonaws.com'
- else:
- host = 'mechanicalturk.amazonaws.com'
- AWSQueryConnection.__init__(self, aws_access_key_id,
- aws_secret_access_key,
- is_secure, port, proxy, proxy_port,
- proxy_user, proxy_pass, host, debug,
- https_connection_factory)
-
- def _required_auth_capability(self):
- return ['mturk']
- def get_account_balance(self):
- """
- """
- params = {}
- return self._process_request('GetAccountBalance', params,
- [('AvailableBalance', Price),
- ('OnHoldBalance', Price)])
-
- def register_hit_type(self, 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
- """
- params = dict(
- Title=title,
- Description=description,
- AssignmentDurationInSeconds=
- self.duration_as_seconds(duration),
- )
- params.update(MTurkConnection.get_price_as_price(reward).get_as_params('Reward'))
- if keywords:
- params['Keywords'] = self.get_keywords_as_string(keywords)
- if approval_delay is not None:
- d = self.duration_as_seconds(approval_delay)
- params['AutoApprovalDelayInSeconds'] = d
- if qual_req is not None:
- params.update(qual_req.get_as_params())
- return self._process_request('RegisterHITType', params, [('HITTypeId', HITTypeId)])
- def set_email_notification(self, hit_type, email, event_types=None):
- """
- Performs a SetHITTypeNotification operation to set email
- notification for a specified HIT type
- """
- return self._set_notification(hit_type, 'Email', email, event_types)
-
- def set_rest_notification(self, hit_type, url, event_types=None):
- """
- Performs a SetHITTypeNotification operation to set REST notification
- for a specified HIT type
- """
- return self._set_notification(hit_type, 'REST', url, event_types)
-
- def _set_notification(self, hit_type, transport, destination, event_types=None):
- """
- Common SetHITTypeNotification operation to set notification for a
- specified HIT type
- """
- assert isinstance(hit_type, str), "hit_type argument should be a string."
-
- params = {'HITTypeId': hit_type}
-
- # from the Developer Guide:
- # The 'Active' parameter is optional. If omitted, the active status of
- # the HIT type's notification specification is unchanged. All HIT types
- # begin with their notification specifications in the "inactive" status.
- notification_params = {'Destination': destination,
- 'Transport': transport,
- 'Version': boto.mturk.notification.NotificationMessage.NOTIFICATION_VERSION,
- 'Active': True,
- }
- # add specific event types if required
- if event_types:
- self.build_list_params(notification_params, event_types, 'EventType')
-
- # Set up dict of 'Notification.1.Transport' etc. values
- notification_rest_params = {}
- num = 1
- for key in notification_params:
- notification_rest_params['Notification.%d.%s' % (num, key)] = notification_params[key]
-
- # Update main params dict
- params.update(notification_rest_params)
-
- # Execute operation
- return self._process_request('SetHITTypeNotification', params)
-
- def create_hit(self, hit_type=None, question=None,
- lifetime=datetime.timedelta(days=7),
- max_assignments=1,
- title=None, description=None, keywords=None,
- reward=None, duration=datetime.timedelta(days=7),
- approval_delay=None, annotation=None,
- questions=None, qualifications=None,
- response_groups=None):
- """
- Creates a new HIT.
- Returns a ResultSet
- See: http://docs.amazonwebservices.com/AWSMechanicalTurkRequester/2006-10-31/ApiReference_CreateHITOperation.html
- """
-
- # handle single or multiple questions
- neither = question is None and questions is None
- both = question is not None and questions is not None
- if neither or both:
- raise ValueError("Must specify either question (single Question instance) or questions (list or QuestionForm instance), but not both")
- if question:
- questions = [question]
- question_param = QuestionForm(questions)
- if isinstance(question, QuestionForm):
- question_param = question
- elif isinstance(question, ExternalQuestion):
- question_param = question
-
- # Handle basic required arguments and set up params dict
- params = {'Question': question_param.get_as_xml(),
- 'LifetimeInSeconds':
- self.duration_as_seconds(lifetime),
- 'MaxAssignments': max_assignments,
- }
- # if hit type specified then add it
- # else add the additional required parameters
- if hit_type:
- params['HITTypeId'] = hit_type
- else:
- # Handle keywords
- final_keywords = MTurkConnection.get_keywords_as_string(keywords)
-
- # Handle price argument
- final_price = MTurkConnection.get_price_as_price(reward)
-
- final_duration = self.duration_as_seconds(duration)
- additional_params = dict(
- Title=title,
- Description=description,
- Keywords=final_keywords,
- AssignmentDurationInSeconds=final_duration,
- )
- additional_params.update(final_price.get_as_params('Reward'))
- if approval_delay is not None:
- d = self.duration_as_seconds(approval_delay)
- additional_params['AutoApprovalDelayInSeconds'] = d
- # add these params to the others
- params.update(additional_params)
- # add the annotation if specified
- if annotation is not None:
- params['RequesterAnnotation'] = annotation
-
- # Add the Qualifications if specified
- if qualifications is not None:
- params.update(qualifications.get_as_params())
- # Handle optional response groups argument
- if response_groups:
- self.build_list_params(params, response_groups, 'ResponseGroup')
-
- # Submit
- return self._process_request('CreateHIT', params, [('HIT', HIT),])
- def change_hit_type_of_hit(self, 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.
-
- :type hit_id: str
- :type hit_type: str
- """
- params = {'HITId' : hit_id,
- 'HITTypeId': hit_type}
- return self._process_request('ChangeHITTypeOfHIT', params)
-
- def get_reviewable_hits(self, 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.
- """
- params = {'Status' : status,
- 'SortProperty' : sort_by,
- 'SortDirection' : sort_direction,
- 'PageSize' : page_size,
- 'PageNumber' : page_number}
- # Handle optional hit_type argument
- if hit_type is not None:
- params.update({'HITTypeId': hit_type})
- return self._process_request('GetReviewableHITs', params, [('HIT', HIT),])
- @staticmethod
- def _get_pages(page_size, total_records):
- """
- Given a page size (records per page) and a total number of
- records, return the page numbers to be retrieved.
- """
- pages = total_records/page_size+bool(total_records%page_size)
- return range(1, pages+1)
- def get_all_hits(self):
- """
- 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.
- """
- page_size = 100
- search_rs = self.search_hits(page_size=page_size)
- total_records = int(search_rs.TotalNumResults)
- get_page_hits = lambda page: self.search_hits(page_size=page_size, page_number=page)
- page_nums = self._get_pages(page_size, total_records)
- hit_sets = itertools.imap(get_page_hits, page_nums)
- return itertools.chain.from_iterable(hit_sets)
- def search_hits(self, 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.
- """
- params = {'SortProperty' : sort_by,
- 'SortDirection' : sort_direction,
- 'PageSize' : page_size,
- 'PageNumber' : page_number}
- # Handle optional response groups argument
- if response_groups:
- self.build_list_params(params, response_groups, 'ResponseGroup')
-
- return self._process_request('SearchHITs', params, [('HIT', HIT),])
- def get_assignments(self, 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
- """
- params = {'HITId' : hit_id,
- 'SortProperty' : sort_by,
- 'SortDirection' : sort_direction,
- 'PageSize' : page_size,
- 'PageNumber' : page_number}
- if status is not None:
- params['AssignmentStatus'] = status
- # Handle optional response groups argument
- if response_groups:
- self.build_list_params(params, response_groups, 'ResponseGroup')
-
- return self._process_request('GetAssignmentsForHIT', params,
- [('Assignment', Assignment),])
- def approve_assignment(self, assignment_id, feedback=None):
- """
- """
- params = {'AssignmentId': assignment_id,}
- if feedback:
- params['RequesterFeedback'] = feedback
- return self._process_request('ApproveAssignment', params)
- def reject_assignment(self, assignment_id, feedback=None):
- """
- """
- params = {'AssignmentId': assignment_id,}
- if feedback:
- params['RequesterFeedback'] = feedback
- return self._process_request('RejectAssignment', params)
- def get_hit(self, hit_id, response_groups=None):
- """
- """
- params = {'HITId': hit_id,}
- # Handle optional response groups argument
- if response_groups:
- self.build_list_params(params, response_groups, 'ResponseGroup')
-
- return self._process_request('GetHIT', params, [('HIT', HIT),])
- def set_reviewing(self, 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.
- """
- params = {'HITId': hit_id,}
- if revert:
- params['Revert'] = revert
- return self._process_request('SetHITAsReviewing', params)
- def disable_hit(self, 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.
- """
- params = {'HITId': hit_id,}
- # Handle optional response groups argument
- if response_groups:
- self.build_list_params(params, response_groups, 'ResponseGroup')
-
- return self._process_request('DisableHIT', params)
- def dispose_hit(self, 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. """
- params = {'HITId': hit_id,}
- return self._process_request('DisposeHIT', params)
- def expire_hit(self, 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.
- """
- params = {'HITId': hit_id,}
- return self._process_request('ForceExpireHIT', params)
- def extend_hit(self, 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.
- """
- # must provide assignment *or* expiration increment
- if (assignments_increment is None and expiration_increment is None) or \
- (assignments_increment is not None and expiration_increment is not None):
- raise ValueError("Must specify either assignments_increment or expiration_increment, but not both")
- params = {'HITId': hit_id,}
- if assignments_increment:
- params['MaxAssignmentsIncrement'] = assignments_increment
- if expiration_increment:
- params['ExpirationIncrementInSeconds'] = expiration_increment
- return self._process_request('ExtendHIT', params)
- def get_help(self, 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'
- """
- params = {'About': about, 'HelpType': help_type,}
- return self._process_request('Help', params)
- def grant_bonus(self, 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.
- """
- params = bonus_price.get_as_params('BonusAmount', 1)
- params['WorkerId'] = worker_id
- params['AssignmentId'] = assignment_id
- params['Reason'] = reason
- return self._process_request('GrantBonus', params)
- def block_worker(self, worker_id, reason):
- """
- Block a worker from working on my tasks.
- """
- params = {'WorkerId': worker_id, 'Reason': reason}
- return self._process_request('BlockWorker', params)
- def unblock_worker(self, worker_id, reason):
- """
- Unblock a worker from working on my tasks.
- """
- params = {'WorkerId': worker_id, 'Reason': reason}
- return self._process_request('UnblockWorker', params)
-
- def notify_workers(self, worker_ids, subject, message_text):
- """
- Send a text message to workers.
- """
- params = {'Subject' : subject,
- 'MessageText': message_text}
- self.build_list_params(params, worker_ids, 'WorkerId')
- return self._process_request('NotifyWorkers', params)
- def create_qualification_type(self,
- 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.
- """
- params = {'Name': name,
- 'Description': description,
- 'QualificationTypeStatus': status,
- }
- if retry_delay is not None:
- params['RetryDelayInSeconds'] = retry_delay
- if test is not None:
- assert(isinstance(test, QuestionForm))
- assert(test_duration is not None)
- params['Test'] = test.get_as_xml()
- if test_duration is not None:
- params['TestDurationInSeconds'] = test_duration
- if answer_key is not None:
- if isinstance(answer_key, basestring):
- params['AnswerKey'] = answer_key # xml
- else:
- raise TypeError
- # Eventually someone will write an AnswerKey class.
- if auto_granted:
- assert(test is None)
- params['AutoGranted'] = True
- params['AutoGrantedValue'] = auto_granted_value
- if keywords:
- params['Keywords'] = self.get_keywords_as_string(keywords)
- return self._process_request('CreateQualificationType', params,
- [('QualificationType', QualificationType),])
- def get_qualification_type(self, qualification_type_id):
- params = {'QualificationTypeId' : qualification_type_id }
- return self._process_request('GetQualificationType', params,
- [('QualificationType', QualificationType),])
- def get_qualifications_for_qualification_type(self, qualification_type_id):
- params = {'QualificationTypeId' : qualification_type_id }
- return self._process_request('GetQualificationsForQualificationType', params,
- [('QualificationType', QualificationType),])
- def update_qualification_type(self, 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):
- params = {'QualificationTypeId' : qualification_type_id }
- if description is not None:
- params['Description'] = description
- if status is not None:
- params['QualificationTypeStatus'] = status
- if retry_delay is not None:
- params['RetryDelayInSeconds'] = retry_delay
- if test is not None:
- assert(isinstance(test, QuestionForm))
- params['Test'] = test.get_as_xml()
- if test_duration is not None:
- params['TestDurationInSeconds'] = test_duration
- if answer_key is not None:
- if isinstance(answer_key, basestring):
- params['AnswerKey'] = answer_key # xml
- else:
- raise TypeError
- # Eventually someone will write an AnswerKey class.
- if auto_granted is not None:
- params['AutoGranted'] = auto_granted
- if auto_granted_value is not None:
- params['AutoGrantedValue'] = auto_granted_value
- return self._process_request('UpdateQualificationType', params,
- [('QualificationType', QualificationType),])
- def dispose_qualification_type(self, qualification_type_id):
- """TODO: Document."""
- params = {'QualificationTypeId' : qualification_type_id}
- return self._process_request('DisposeQualificationType', params)
- def search_qualification_types(self, 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."""
- params = {'Query' : query,
- 'SortProperty' : sort_by,
- 'SortDirection' : sort_direction,
- 'PageSize' : page_size,
- 'PageNumber' : page_number,
- 'MustBeRequestable' : must_be_requestable,
- 'MustBeOwnedByCaller' : must_be_owned_by_caller}
- return self._process_request('SearchQualificationTypes', params,
- [('QualificationType', QualificationType),])
- def get_qualification_requests(self, qualification_type_id,
- sort_by='Expiration',
- sort_direction='Ascending', page_size=10,
- page_number=1):
- """TODO: Document."""
- params = {'QualificationTypeId' : qualification_type_id,
- 'SortProperty' : sort_by,
- 'SortDirection' : sort_direction,
- 'PageSize' : page_size,
- 'PageNumber' : page_number}
- return self._process_request('GetQualificationRequests', params,
- [('QualificationRequest', QualificationRequest),])
- def grant_qualification(self, qualification_request_id, integer_value=1):
- """TODO: Document."""
- params = {'QualificationRequestId' : qualification_request_id,
- 'IntegerValue' : integer_value}
- return self._process_request('GrantQualification', params)
- def revoke_qualification(self, subject_id, qualification_type_id,
- reason=None):
- """TODO: Document."""
- params = {'SubjectId' : subject_id,
- 'QualificationTypeId' : qualification_type_id,
- 'Reason' : reason}
- return self._process_request('RevokeQualification', params)
- def assign_qualification(self, qualification_type_id, worker_id,
- value=1, send_notification=True):
- params = {'QualificationTypeId' : qualification_type_id,
- 'WorkerId' : worker_id,
- 'IntegerValue' : value,
- 'SendNotification' : send_notification}
- return self._process_request('AssignQualification', params)
- def get_qualification_score(self, qualification_type_id, worker_id):
- """TODO: Document."""
- params = {'QualificationTypeId' : qualification_type_id,
- 'SubjectId' : worker_id}
- return self._process_request('GetQualificationScore', params,
- [('Qualification', Qualification),])
- def update_qualification_score(self, qualification_type_id, worker_id,
- value):
- """TODO: Document."""
- params = {'QualificationTypeId' : qualification_type_id,
- 'SubjectId' : worker_id,
- 'IntegerValue' : value}
- return self._process_request('UpdateQualificationScore', params)
- def _process_request(self, request_type, params, marker_elems=None):
- """
- Helper to process the xml response from AWS
- """
- response = self.make_request(request_type, params, verb='POST')
- return self._process_response(response, marker_elems)
- def _process_response(self, response, marker_elems=None):
- """
- Helper to process the xml response from AWS
- """
- body = response.read()
- #print body
- if '<Errors>' not in body:
- rs = ResultSet(marker_elems)
- h = handler.XmlHandler(rs, self)
- xml.sax.parseString(body, h)
- return rs
- else:
- raise MTurkRequestError(response.status, response.reason, body)
- @staticmethod
- def get_keywords_as_string(keywords):
- """
- Returns a comma+space-separated string of keywords from either
- a list or a string
- """
- if isinstance(keywords, list):
- keywords = ', '.join(keywords)
- if isinstance(keywords, str):
- final_keywords = keywords
- elif isinstance(keywords, unicode):
- final_keywords = keywords.encode('utf-8')
- elif keywords is None:
- final_keywords = ""
- else:
- raise TypeError("keywords argument must be a string or a list of strings; got a %s" % type(keywords))
- return final_keywords
-
- @staticmethod
- def get_price_as_price(reward):
- """
- Returns a Price data structure from either a float or a Price
- """
- if isinstance(reward, Price):
- final_price = reward
- else:
- final_price = Price(reward)
- return final_price
- @staticmethod
- def duration_as_seconds(duration):
- if isinstance(duration, datetime.timedelta):
- duration = duration.days*86400 + duration.seconds
- try:
- duration = int(duration)
- except TypeError:
- raise TypeError("Duration must be a timedelta or int-castable, got %s" % type(duration))
- return duration
- class BaseAutoResultElement:
- """
- Base class to automatically add attributes when parsing XML
- """
- def __init__(self, connection):
- pass
- def startElement(self, name, attrs, connection):
- return None
- def endElement(self, name, value, connection):
- setattr(self, name, value)
- class HIT(BaseAutoResultElement):
- """
- 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
- """
- # property helper to determine if HIT has expired
- def _has_expired(self):
- """ Has this HIT expired yet? """
- expired = False
- if hasattr(self, 'Expiration'):
- now = datetime.datetime.utcnow()
- expiration = datetime.datetime.strptime(self.Expiration, '%Y-%m-%dT%H:%M:%SZ')
- expired = (now >= expiration)
- else:
- raise ValueError("ERROR: Request for expired property, but no Expiration in HIT!")
- return expired
- # are we there yet?
- expired = property(_has_expired)
- class HITTypeId(BaseAutoResultElement):
- """
- Class to extract an HITTypeId structure from a response
- """
- pass
- class Qualification(BaseAutoResultElement):
- """
- 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.
- """
-
- pass
- class QualificationType(BaseAutoResultElement):
- """
- 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
- """
-
- pass
- class QualificationRequest(BaseAutoResultElement):
- """
- 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
- TODO: Ensure that Test and Answer attribute are treated properly if the
- qualification requires a test. These attributes are XML-encoded.
- """
-
- pass
- class Assignment(BaseAutoResultElement):
- """
- 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
- """
- def __init__(self, connection):
- BaseAutoResultElement.__init__(self, connection)
- self.answers = []
- def endElement(self, name, value, connection):
- # the answer consists of embedded XML, so it needs to be parsed independantly
- if name == 'Answer':
- answer_rs = ResultSet([('Answer', QuestionFormAnswer),])
- h = handler.XmlHandler(answer_rs, connection)
- value = connection.get_utf8_value(value)
- xml.sax.parseString(value, h)
- self.answers.append(answer_rs)
- else:
- BaseAutoResultElement.endElement(self, name, value, connection)
- class QuestionFormAnswer(BaseAutoResultElement):
- """
- Class to extract Answers from inside the embedded XML
- QuestionFormAnswers element inside the Answer element which is
- part of the Assignment structure
- 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
- """
- def __init__(self, connection):
- BaseAutoResultElement.__init__(self, connection)
- self.fields = []
- self.qid = None
- def endElement(self, name, value, connection):
- if name == 'QuestionIdentifier':
- self.qid = value
- elif name in ['FreeText', 'SelectionIdentifier', 'OtherSelectionText'] and self.qid:
- self.fields.append( value )