o ckF[p@s0ddlZddlZddlZddlmZddlmZddlmZddl Zddl m Z ddl m Z ddlmZddlmZmZmZGd d d e ZGd d d e ZGd ddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZdS)N)handler)config)Price)AWSQueryConnection)EC2ResponseError) ResultSet) QuestionFormExternalQuestion HTMLQuestionc@eZdZdZdS)MTurkRequestErrorzError for MTurk RequestsN__name__ __module__ __qualname____doc__rr7/usr/lib/python3/dist-packages/boto/mturk/connection.pyr #sr cs~eZdZdZ      dwfdd ZddZd d Z dxd d Zdyd dZdyddZ dyddZ  dzddZ d{ddZ ddde jddddddde jddddddddfddZddZ  ! d|d#d$Zed%d&Zd'd(Z ! d}d*d+Zdyd,d-Z  ! d~d/d0Zdyd1d2Zdyd3d4Zdyd5d6Zd7d8Zdyd9d:Zdyd;d<Zdyd=d>Zd?d@ZdAdBZ  d{dCdDZ!ddFdGZ"dHdIZ#dJdKZ$dLdMZ%dNdOZ&       P ddQdRZ'dSdTZ(dUdVZ)ddXdYZ*        ddZd[Z+d\d]Z, ^ "  dd_d`Z- " ddadbZ.ddcddZ/ dydedfZ0 ddgdhZ1didjZ2dkdlZ3dydmdnZ4dydodpZ5edqdrZ6edsdtZ7edudvZ8Z9S)MTurkConnectionz 2014-08-15NTrcs^| stddrtdddkrd} nd} | |_tt|j||||||||| | | | | d dS)NMTurksandboxTruez$mechanicalturk.sandbox.amazonaws.comzmechanicalturk.amazonaws.com)security_token profile_name)r has_optiongetdebugsuperr__init__)selfaws_access_key_idaws_secret_access_key is_secureportproxy proxy_port proxy_user proxy_passhostrhttps_connection_factoryrr __class__rrr,s  zMTurkConnection.__init__cCsdgS)Nmturkr)rrrr_required_auth_capabilityAsz)MTurkConnection._required_auth_capabilitycCsi}|d|dtfdtfgS) GetAccountBalanceAvailableBalance OnHoldBalance)_process_requestr)rparamsrrrget_account_balanceDs z#MTurkConnection.get_account_balancec Cst||||d}|t|d|r|||d<|dur+||} | |d<|dur6|||d|dtfgS)z 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 )Title DescriptionAssignmentDurationInSecondsRewardKeywordsNAutoApprovalDelayInSecondsRegisterHITType HITTypeId) dictduration_as_secondsupdaterget_price_as_price get_as_paramsget_keywords_as_stringr2r<) rtitle descriptionrewarddurationkeywordsapproval_delayqual_reqr3drrrregister_hit_typeLs  z!MTurkConnection.register_hit_typecC||d|d|S)zx Performs a SetHITTypeNotification operation to set email notification for a specified HIT type EmailSetHITTypeNotification_set_notification)rhit_typeemail event_typesrrrset_email_notificationh z&MTurkConnection.set_email_notificationcCrL)zw Performs a SetHITTypeNotification operation to set REST notification for a specified HIT type RESTrNrO)rrQurlrSrrrset_rest_notificationprUz%MTurkConnection.set_rest_notificationcCrL)a  Performs a SetHITTypeNotification operation so set SQS notification for a specified HIT type. Queue URL is of form: https://queue.amazonaws.com// and can be found when looking at the details for a Queue in the AWS Console SQSrNrO)rrQ queue_urlrSrrrset_sqs_notificationxs z$MTurkConnection.set_sqs_notificationPingcCs||d|d||S)zx Performs a SendTestEventNotification operation with REST notification for a specified HIT type rVSendTestEventNotificationrO)rrQrWrStest_event_typerrrsend_test_event_notifications z,MTurkConnection.send_test_event_notificationc Cs~d|i}||tjjjjdd}|r|||di} d} |D] } || | d| | f<q|| |r9|d|i|||S)zy Common operation to set notification or send a test event notification for a specified HIT type r<T) Destination TransportVersionActive EventTypezNotification.%d.%s TestEventType)botor, notificationNotificationMessageNOTIFICATION_VERSIONbuild_list_paramsr?r2) rrQ transport destination request_typerSr^r3notification_paramsnotification_rest_paramsnumkeyrrrrPs$   z!MTurkConnection._set_notification)daysrecCsx|||d}|duo| du}|durK|duo| du}|s |r$td|r)|g} t| }t|tr5|}nt|tr=|}nt|trD|}||d<n|sQtd||d<|r^|||re||d<n1t |}t | }|| }t ||||d}||d | dur|| }||d <||| dur| |d <|dur|||r| ||d |d |dtfgS)z Creates a new HIT. Returns a ResultSet See: http://docs.amazonwebservices.com/AWSMechTurk/2012-03-25/AWSMturkAPI/ApiReference_CreateHITOperation.html )LifetimeInSecondsMaxAssignmentsNzkMust specify question (single Question instance) or questions (list or QuestionForm instance), but not bothQuestionz|Must not specify question (single Question instance) or questions (list or QuestionForm instance) when specifying hit_layout HITLayoutIdr<)r5r6r9r7r8r:RequesterAnnotation ResponseGroup CreateHITHIT)r> ValueErrorr isinstancer r get_as_xmlr?rArrBr@r=rkr2r|)rrQquestion hit_layoutlifetimemax_assignmentsrCrDrGrErFrH annotation questionsqualifications layout_paramsresponse_groupsr3neitherbothquestion_paramfinal_keywords final_pricefinal_durationadditional_paramsrJrrr create_hits\         zMTurkConnection.create_hitcC||d}|d|S)a  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 )HITIdr<ChangeHITTypeOfHITr2)rhit_idrQr3rrrchange_hit_type_of_hit s  z&MTurkConnection.change_hit_type_of_hit Reviewable Expiration Ascending cCs:|||||d}|dur|d|i|d|dtfgS)z 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. )Status SortProperty SortDirectionPageSize PageNumberNr<GetReviewableHITsr|)r?r2r|)rrQstatussort_bysort_direction page_size page_numberr3rrrget_reviewable_hitssz#MTurkConnection.get_reviewable_hitscCs&||t||}ttd|dS)z Given a page size (records per page) and a total number of records, return the page numbers to be retrieved. re)boollistrange)r total_recordspagesrrr _get_pages.szMTurkConnection._get_pagescsLdjd}t|j}fdd}|}t||}tj|S)aD 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. d)rcsj|dS)N)rr) search_hitspagerrrrCsz.MTurkConnection.get_all_hits..)rintTotalNumResultsr itertoolsimapchain from_iterable)r search_rsr get_page_hits page_numshit_setsrrr get_all_hits7s     zMTurkConnection.get_all_hits CreationTimecCs4||||d}|r|||d|d|dtfgS)aI 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. )rrrrrz SearchHITsr|rkr2r|)rrrrrrr3rrrrHs zMTurkConnection.search_hitscCs4d|i}|r |||d|d|dtfdtfgS)a_ 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. AssignmentIdrz GetAssignment Assignmentr|)rkr2rr|)r assignment_idrr3rrrget_assignment\szMTurkConnection.get_assignment SubmitTimec CsF|||||d}|dur||d<|r|||d|d|dtfgS)ad 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 )rrrrrNAssignmentStatusrzGetAssignmentsForHITr)rkr2r) rrrrrrrrr3rrrget_assignmentsyszMTurkConnection.get_assignmentscC d|i}|r ||d<|d|S)r.rRequesterFeedbackApproveAssignmentrrrfeedbackr3rrrapprove_assignment z"MTurkConnection.approve_assignmentcCr)r.rrRejectAssignmentrrrrrreject_assignmentrz!MTurkConnection.reject_assignmentcCr)r.rrApproveRejectedAssignmentrrrrrapprove_rejected_assignmentrz+MTurkConnection.approve_rejected_assignmentcC||d}|d|dtfgS)a Generates and returns a temporary URL to an uploaded file. The temporary URL is used to retrieve the file as an answer to a FileUploadAnswer question, it is valid for 60 seconds. Will have a FileUploadURL attribute as per the API Reference. )rQuestionIdentifierGetFileUploadURL FileUploadURL)r2r)rrquestion_identifierr3rrrget_file_upload_urls  z#MTurkConnection.get_file_upload_urlcCs.d|i}|r |||d|d|dtfgS)r.rrzGetHITr|rrrrr3rrrget_hitszMTurkConnection.get_hitcCr)aU 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. rRevertSetHITAsReviewingr)rrrevertr3rrr set_reviewings  zMTurkConnection.set_reviewingcCs&d|i}|r |||d|d|S)an 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. rrz DisableHITrkr2rrrr disable_hits zMTurkConnection.disable_hitcCd|i}|d|S)a 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. r DisposeHITrrrr3rrr dispose_hits zMTurkConnection.dispose_hitcCr)aI 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. rForceExpireHITrrrrr expire_hits zMTurkConnection.expire_hitcCsT|dur|dus|dur|durtdd|i}|r||d<|r$||d<|d|S)a 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. NzOMust specify either assignments_increment or expiration_increment, but not bothrMaxAssignmentsIncrementExpirationIncrementInSeconds ExtendHIT)r}r2)rrassignments_incrementexpiration_incrementr3rrr extend_hits zMTurkConnection.extend_hit OperationcCr)z 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' )AboutHelpTypeHelpr)rabout help_typer3rrrget_help4s  zMTurkConnection.get_helpcCs0|dd}||d<||d<||d<|d|S)a 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. BonusAmountreWorkerIdrReason GrantBonus)rAr2)r worker_idr bonus_pricereasonr3rrr grant_bonus?s  zMTurkConnection.grant_bonuscCr)z: Block a worker from working on my tasks. rr BlockWorkerrrrrr3rrr block_workerP  zMTurkConnection.block_workercCr)z< Unblock a worker from working on my tasks. r UnblockWorkerrrrrrunblock_workerXrzMTurkConnection.unblock_workercCs$||d}|||d|d|S)z1 Send a text message to workers. )Subject MessageTextr NotifyWorkersr)r worker_idssubject message_textr3rrrnotify_workers`s  zMTurkConnection.notify_workersFc Cs|||d} |dur|| d<|dur%t|tsJ| dusJ|| d<| dur-| | d<|dur=t|tr;|| d<nt| rM|dusEJd| d<| | d <|rV||| d <|d | d tfgS) am 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. )Namer6QualificationTypeStatusNRetryDelayInSecondsTestTestDurationInSeconds AnswerKeyT AutoGrantedAutoGrantedValuer9CreateQualificationTypeQualificationType)r~rr basestring TypeErrorrBr2r) rnamerDrrG retry_delaytest answer_keyanswer_key_xml test_duration auto_grantedauto_granted_valuer3rrrcreate_qualification_typejs6-     z)MTurkConnection.create_qualification_typecCsd|i}|d|dtfgS)NQualificationTypeIdGetQualificationTyperr2rrqualification_type_idr3rrrget_qualification_typesz&MTurkConnection.get_qualification_typecsLd}t|j}fdd}|}t||}tj|S)Nrcsj|dS)N)r'rr))get_qualifications_for_qualification_typerrr'rrrrszFMTurkConnection.get_all_qualifications_for_qual_type..)r)rrrrrrr)rr' search_qualrget_page_qualsr qual_setsrr*r$get_all_qualifications_for_qual_types     z4MTurkConnection.get_all_qualifications_for_qual_typercCs |||d}|d|dtfgS)N)r#rr%GetQualificationsForQualificationType Qualificationr2r0)rr'rrr3rrrr)sz9MTurkConnection.get_qualifications_for_qualification_typec Csd|i} |dur || d<|dur|| d<|dur|| d<|dur-t|ts'J|| d<|dur5|| d<|durEt|trC|| d<nt|durM|| d<| durU| | d <|d | d tfgS) Nr#r6rrrrrrrUpdateQualificationTyper)r~rrrrr2r) rr'rDrrrrrr r!r3rrrupdate_qualification_types.    z)MTurkConnection.update_qualification_typecCr)TODO: Document.r#DisposeQualificationTyperr&rrrdispose_qualification_types z*MTurkConnection.dispose_qualification_typerc Cs(|||||||d}|d|dtfgS)r4)QueryrrrrMustBeRequestableMustBeOwnedByCallerSearchQualificationTypesrr%) rqueryrrrrmust_be_requestablemust_be_owned_by_callerr3rrrsearch_qualification_typessz*MTurkConnection.search_qualification_typescCs$|||||d}|d|dtfgS)r4)r#rrrrGetQualificationRequestsQualificationRequest)r2r@)rr'rrrrr3rrrget_qualification_requestssz*MTurkConnection.get_qualification_requestscCr)r4)QualificationRequestId IntegerValueGrantQualificationr)rqualification_request_id integer_valuer3rrrgrant_qualifications z#MTurkConnection.grant_qualificationcC|||d}|d|S)r4) SubjectIdr#rRevokeQualificationr)r subject_idr'rr3rrrrevoke_qualification!  z$MTurkConnection.revoke_qualificationcCs||||d}|d|S)N)r#rrCSendNotificationAssignQualificationr)rr'rvaluesend_notificationr3rrrassign_qualification)s  z$MTurkConnection.assign_qualificationcCr)r4)r#rIGetQualificationScorer0r1)rr'rr3rrrget_qualification_score1s z'MTurkConnection.get_qualification_scorecCrH)r4)r#rIrCUpdateQualificationScorer)rr'rrPr3rrrupdate_qualification_score8rMz*MTurkConnection.update_qualification_scorecCs$||d<|jd|dd}|||S)= Helper to process the xml response from AWS rNPOST)verb) make_request_process_response)rrnr3 marker_elemsresponserrrr2@s z MTurkConnection._process_requestcCs^|}|jdkr t|d|dvr't|}t||}tj |||St |j |j |)rWzutf-8) readrprintdecoderr XmlHandlerxmlsax parseStringr rr)rr]r\bodyrshrrrr[Hs  z!MTurkConnection._process_responsecCs^t|tr d|}t|tr|}|St|tr|d}|S|dur'd}|Stdt|)zk Returns a comma+space-separated string of keywords from either a list or a string z, r_NzAkeywords argument must be a string or a list of strings; got a %s)r~rjoinstrunicodeencodertype)rGrrrrrBWs    z&MTurkConnection.get_keywords_as_stringcCst|tr |}|St|}|S)zO Returns a Price data structure from either a float or a Price )r~r)rErrrrr@is z"MTurkConnection.get_price_as_pricecCsJt|tjr|jd|j}zt|}W|Sty$tdt|w)NiQz4Duration must be a timedelta or int-castable, got %s)r~datetime timedeltartsecondsrrro)rFrrrr>ts   z#MTurkConnection.duration_as_seconds) NNTNNNNNNrNNN)NNNN)Nr\)NN)Nrrrrre)rrrreN)NrrrreN)r)NNNNNNFre)rre)NNNNNNNN)NrrrreTT)rrrre)re)reT):rrr APIVersionrr-r4rKrTrXr[r_rPrprqrrr staticmethodrrrrrrrrrrrrrrrrrrrr r"r(r.r)r3r6r>rArGrLrRrTrVr2r[rBr@r> __classcell__rrr*rr(s      (   V    *        O  ,         rc@s(eZdZdZddZddZddZdS) BaseAutoResultElementzE Base class to automatically add attributes when parsing XML cCdSrsrr connectionrrrrzBaseAutoResultElement.__init__cCrxrsr)rrattrsrzrrr startElementr{z"BaseAutoResultElement.startElementcCst|||dSrs)setattrrrrPrzrrr endElementsz BaseAutoResultElement.endElementN)rrrrrr}rrrrrrws  rwc@s eZdZdZddZeeZdS)r|z 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 cCs<d}t|drtj}tj|jd}||k}|Std)z Has this HIT expired yet? Frz%Y-%m-%dT%H:%M:%SZz>ERROR: Request for expired property, but no Expiration in HIT!)hasattrrputcnowstrptimerr})rexpirednow expirationrrr _has_expireds  zHIT._has_expiredN)rrrrrpropertyrrrrrr|s r|c@r )rzE Class to extract an FileUploadURL structure from a response Nr rrrrrrc@r )r<zA Class to extract an HITTypeId structure from a response Nr rrrrr<rr<c@r )r0z 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. Nr rrrrr0r0c@r )rz 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 Nr rrrrrrrc,eZdZdZfddZfddZZS)r@z 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 ctt||g|_dSrs)rr@ranswersryr*rrr zQualificationRequest.__init__cb|dkr%tdtfg}t||}||}tj|||j |dSt t | |||dSNAnswer) rQuestionFormAnswerrrcget_utf8_valuerdrerfrappendrr@rrrrPrz answer_rsrir*rrr  zQualificationRequest.endElementrrrrrrrvrrr*rr@ r@cr)rz 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 crrs)rrrrryr*rrrrzAssignment.__init__crr) rrrrcrrdrerfrrrrrrr*rrrrzAssignment.endElementrrrr*rrrrcs(eZdZdZfddZddZZS)ra: 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 cs tt||g|_d|_dSrs)rrrfieldsqidryr*rrrs zQuestionFormAnswer.__init__cCs8|dkr ||_dS|dvr|jr|j|dSdSdS)Nr)FreeTextSelectionIdentifierOtherSelectionText)rrrrrrrrs  zQuestionFormAnswer.endElementrrrr*rrs r) xml.saxrdrprrgrrboto.mturk.pricerboto.mturk.notificationboto.connectionrboto.exceptionrboto.resultsetrboto.mturk.questionrr r r robjectrwr|rr<r0rr@rrrrrrs8      ]