API Reference

This documentation was hand-written (i.e., not auto-generated from code). It covers only the parts of the library that we would expect to be useful.

Crowdlib Module

Creating HITs

create_hit_type(title, description[, reward[, time_limit[, keywords[, autopay_delay[, qualification_requirements]]]]])

Create a HITType object with which you can then create HITs. This registers your HIT type with AMT’s server. The defaults for all optional arguments are specified in your settings file.

To post a HIT, use the HITType.create_hit() method of the HITType object returned by this function:

For more explanation of these parameters, see RegisterHITType in the AMT API documentation.

Parameters:
  • title (basestring) – title to be displayed to workers on the main HIT menu
  • description (basestring) – description to be displayed to workers
  • reward (float) – amount of reward, in US dollars; default=settings.default_reward
  • time_limit (duration expression) – amount of time worker may work on the HIT after which it will be considered abandoned; same as AssignmentDurationInSeconds in the API
  • keywords (iterable of basestring) – keywords which workers may search for to find this HIT
  • autopay_delay (duration expression) – duration after an assignment is submitted, after which it will be automatically approved
  • qualification_requirements (iterable of QualificationRequirement) –
Return type:

HITType

Input Fields

Input fields are used to generate the standard form fields provided by Mechanical Turk. Each of these returns a QuestionField object, the sole purpose of which is to be passed to create_hit().

For more information, see QuestionForm in the AMT API documentation.

checkbox_field(label, id, choices[, other=None[, min_selection_count=1[, max_selection_count=∞]]])
Parameters:
  • label (basestring) – prompt shown above the checkboxes
  • id (basestring) – id by which this will be referred to in the results
  • choices (iterable of basestring) – labels of the checkboxes
  • min_selection_count (int) – minimum number of selections to allow
  • max_selection_count (int) – maximum number of selections to allow
  • other (QuestionField) – text field to use as an “other” selection
Return type:

QuestionField

combobox_field(label, id, choices[, other=None[, min_selection_count=1[, max_selection_count=∞]]])
Parameters:
  • label (basestring) – prompt shown above the combo box
  • id (basestring) – id by which this will be referred to in the results
  • choices (iterable of basestring) – labels of the combo box items
  • min_selection_count (int) – minimum number of selections to allow
  • max_selection_count (int) – maximum number of selections to allow
  • other (QuestionField) – text field to use as an “other” selection
Return type:

QuestionField

Parameters:
  • label (basestring) – prompt shown above the drop-down control
  • id (basestring) – id by which this will be referred to in the results
  • choices (iterable of basestring) – labels of the drop-down control items
Return type:

QuestionField

file_upload_field(label, id[, min_bytes=0[, max_bytes=2000000000]])
Parameters:
  • label (basestring) – prompt shown above the file upload control
  • id (basestring) – id by which this will be referred to in the results
  • min_bytes (int) – minimum allowable file size
  • max_bytes (int) – maximum allowable file size
Return type:

QuestionField

number_field(label, id[, min_value=None[, max_value=None]])
Parameters:
  • label (basestring) – prompt shown above the number field
  • id (basestring) – id by which this will be referred to in the results
  • min_value (int) – minimum value allowed
  • max_value (int) – maximum value allowed
Return type:

int

radiobutton_field(label, id, choices[, other=None])
Parameters:
  • label (basestring) – prompt shown above the radio buttons
  • id (basestring) – id by which this will be referred to in the results
  • choices (iterable of basestring) – labels of the radio buttons
  • other (QuestionField) – text field to use as an “other” selection
Return type:

QuestionField

text_field(label, id)
Parameters:
  • label (basestring) – prompt shown above the text field
  • id (basestring) – id by which this will be referred to in the results
Return type:

QuestionField

Getters

get_account_balance()
Return type:float (currency)
get_hit_type(hit_type_id)
Parameters:hit_type_id (basestring) – 30-character HIT type ID
Return type:HITType
get_hit_types(since=None, until=None, title_re=None)
Parameters:
Return type:

sequence of HITType

get_hits(since=None, until=None, title_re=None)
Parameters:
Return type:

sequence of HIT

get_hit(id)
Parameters:id (basestring) – 30-character HIT ID
Return type:HIT
get_assignment(id)
Parameters:id (basestring) – 30-character assignment ID
Return type:Assignment
get_assignments(since=None, until=None, title_re=None)
Parameters:
Return type:

sequence of Assignment

get_qualification_type(id)
Parameters:id (basestring) – qualification type ID
Return type:QualificationType
get_qualification_types()
Return type:sequence of QualificationType
get_worker(id)
Parameters:id (basestring) – worker ID
Return type:Worker
get_workers(since=None, until=None, title_re=None)
Parameters:
Return type:

sequence of Worker

Receiving results

get_current_notification_events()

Note

Notification support has not been tested recently and might be broken.

Return type:sequence of NotificationEvent
send_test_notification(url[, event_type="AssignmentSubmitted"])

Instruct the AWS server to send a test notification to the specified URL. This can be useful for testing and debugging applications that use notifications.

For more information, see SendTestEventNotification in the AMT API documentation.

Note

Notification support has not been tested recently and might be broken.

Parameters:
  • url (basestring) – URL
  • event_type (basestring) – one of "AssignmentAccepted", "AssignmentAbandoned", "AssignmentReturned", "AssignmentSubmitted", "HITReviewable", "HITExpired", "Ping"
assignment_report([assignments[, omit_columns=()[, format="excel"]]])

Create a summary report of the specified assignments in either tab-delimited (Excel-friendly) or HTML format. This is typically combined with get_assignments() like this:

assignments = get_assignments(since="11/1/2013", title_re="label some images")
print( cl.assignment_report(assignments) )

The resulting report will have the following columns:

  • Assignment ID
  • Worker ID
  • Accept Time
  • Submit Time
  • Assignment Status
  • Review Time
  • Reward Paid
  • Bonuses Paid
  • Time Spent (secs)
  • Hourly Rate
  • HIT ID
  • HIT Type ID
  • Title
  • Reward Offered
  • ... and every question ID found among the assignments, in sorted order
Parameters:
  • assignments (iterable of Assignment) – assignments to include in the report
  • omit_columns (iterable of basestring or int) – column indices or labels to omit from the report
  • format – either “excel” (tab-delimited) or “html”
Return type:

basestring

Housekeeping

requester_statistics

This special object has properties that return a wide variety of statistics about your activity on Mechanical Turk. The specific statistics are listed under RequesterStatistics. These will be cumulative totals.

Example:

>>> import crowdlib as cl, crowdlib_settings
>>> print cl.requester_statistics.average_reward_amount
0.713
Type:RequesterStatistics
requester_statistics_by_day

This special object is just like requester_statistics except that its properties return a sequence of pairs of (datetime.date, value), one for each of the last 730 days in reverse chronological order (i.e., starting with the most recent).

Example:

>>> import crowdlib as cl, crowdlib_settings
>>> for d,v in cl.requester_statistics_by_day.total_reward_payout[:7]:
...   print( "%s : $%4.2f"%(d.strftime("%m/%d/%Y"), v) )
11/28/2013 : $8.76
11/27/2013 : $7.65
11/26/2013 : $6.54
11/25/2013 : $5.43
11/24/2013 : $4.32
11/23/2013 : $3.21
11/22/2013 : $2.10
Type:RequesterStatistics
set_all_hits_unavailable()

Cause all HITs to be expired immediately. This is useful if you think you have a bug and want to stop workers from accepting HITs that may be problematic.

sync_with_amt()

Check the server for any new HITs or assignments.

This is normally done automatically, as needed. Use only if you believe HITs may have been created by something outside of this installation of CrowdLib.

Qualification requirements

create_qualification_type(name, description[, keywords=()[, test_xml=None[, initially_active=None[, retry_delay=None[, test_duration=None[, answer_key_xml=None[, auto_granted=None[, auto_granted_value=None[, is_requestable=None]]]]]]]]])
Parameters:
  • name (basestring) – name of this qualification type; shown to workers
  • description (basestring) – description of this qualification type; shown to workers
  • keywords (iterable of basestring) – keywords by which workers might find this qualification type when searching for qualification types
  • test_xml (basestring) – XML; set to None to indicate that no test is required
  • initially_active (bool) – normally True; setting to False would make this qualification type unusable
  • retry_delay (duration expression) – required time delay after failing the test before a worker may retry it again; set to None to indicate that retry is not allowed
  • test_duration (duration expression) – time limit for completing the qualification test; may ne None only if test_xml is also None
  • answer_key_xml (basestring) – XML; set to None to indicate that you will process requests manually
  • auto_granted (bool) – True if you want to grant this qualification automatically to anybody who requests it; False otherwise
  • auto_granted_value (int) – value to be assigned for qualification types that are automatically granted (auto_granted=True); ignored otherwise; may be None only if auto_granted==False
  • is_requestable (bool) – True for qualification types that involve a test or request by the worker; False for qualification types that you will assign directly
Return type:

basestring

Raises:

AMTQualificationTypeAlreadyExists

For more information on these parameters, see QualificationType in the AMT API documentation.

create_agreement_requirement(name, description, xhtml, agree_text[, keywords=()[, initially_active=True[, for_preview=False]]])
Parameters:
  • name (basestring) – name of this qualification type; shown to workers
  • description (basestring) – description of this qualification type; shown to workers
  • xhtml (basestring) – content of the agreement as XHTML; only a subset of XHTML is supported, as defined here
  • agree_text (basestring) – text shown next to the checkbox that indicates agreement (e.g., “I agree.”)
  • keywords (iterable of basestring) – keywords by which workers might find this qualification type when searching for qualification types
  • initially_active (bool) – normally True; setting to False would make this qualification type unusable
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

abandoned_requirement(max_pct[, for_preview=False])
Parameters:
  • max_pct (int) – percent, 0-100
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

adult_requirement([for_preview=False])
Parameters:for_preview (bool) – require even to preview HIT?
Return type:QualificationRequirement
approval_requirement(min_pct[, for_preview=False])
Parameters:
  • min_pct (int) – percent, 0-100
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

in_country_requirement(country[, for_preview=False])
Parameters:
  • country (basestring) – 2-digit ISO 3166 country code
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

not_in_country_requirement(country[, for_preview=False])
Parameters:
  • country (basestring) – 2-digit ISO 3166 country code
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

rejected_requirement(max_pct[, for_preview=False])
Parameters:
  • max_pct (int) – percent, 0-100
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

returned_requirement(max_pct[, for_preview=False])
Parameters:
  • max_pct (int) – percent, 0-100
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

submitted_requirement(min_pct[, for_preview=False])
Parameters:
  • min_pct (int) – percent, 0-100
  • for_preview (bool) – require even to preview HIT?
Return type:

QualificationRequirement

Settings

Settings are normally set in your crowdlib_settings.py file, which you import at the same time you import crowdlib.

import crowdlib as cl, crowdlib_settings

You can also change settings directly in your code, for example, to dynamically switch between sandbox and production or between different AWS accounts.

cl.settings.service_type = "production"

Changing the default_… settings repeatedly in your code is not recommended (increases memory consumption).

settings.service_type

Must be either "production" or "sandbox"

Type:basestring
settings.db_dir
Type:basestring
settings.aws_account_id
Type:basestring
settings.aws_account_key
Type:basestring
settings.aws_account_name
Type:basestring
settings.default_autopay_delay
Type:datetime expression or duration expression
settings.default_reward
Type:float (currency)
settings.default_currency
Type:basestring (must be “USD”)
settings.default_lifetime
Type:datetime expression or duration expression
settings.default_max_assignments
Type:int
settings.default_assignment_duration
Type:duration expression
settings.default_qualification_requirements
Type:QualificationRequirement
settings.default_keywords
Type:iterable of basestring

Types Returned

HITType

class HITType
id

30-character string used by AMT

Type:basestring
answers
Type:sequence of Answer
assignments
Type:sequence of Assignment
average_time_taken
Type:datetime.timedelta
autopay_delay
Type:datetime.timedelta
currency

must be “USD”

Type:basestring
description
Type:basestring
create_hit()

There are 5 forms of this method, corresponding to the three methods supplied by AMT (ExternalQuestion, HTMLQuestion, and QuestionForm) plus shortcuts for the latter two.

create_hit(url, height[, max_assignments[, lifetime[, requester_annotation]]])

External URL. You provide a URL to web webpage which will be displayed inside an IFRAME with the given height. For more information, see ExternalQuestion in the AMT API documentation. Also note that you should use a web page with an https:// (SSL) URL. Because the AMT site is https, many browsers will block the IFRAME containing your web page if it is at an http:// (non-SSL) URL. Although AMT does not require an https://` URL, failure to use one would make your HIT inaccessable to many workers.

You provide... You get... Use if...
URL on your web server Maximum control You have a reliable web server with SSL and you need the freedom to change the contents of a HIT even after it has been posted.
create_hit(html, height[, max_assignments[, lifetime[, requester_annotation]]])

HTML document. You provide a complete HTML file which AMT will host and display inside an IFRAME with the given height. It must contain JavaScript code to ensure that the assignment ID is submitted back to the server and (ideally) warn workers when they are viewing your HIT in preview mode. For more information, see HTMLQuestion in the AMT API documentation.

You provide... You get... Use if...
Complete HTML document with some required JavaScript Ability to use any JavaScript and CSS you want Your HIT requires some fancy JavaScript or formatting or you just prefer to code your HIT interface in HTML but the shortcut form of this (below) is insufficient
create_hit(body, height[, onload[, style[, max_assignments[, lifetime[, requester_annotation]]]]])

HTML body. This is a shortcut for the previous option. You provide a HTML form body which CrowdLib will inserts into a template that supplies the boilerplate HTML and JavaScript for handling the assignment ID and dealing with preview mode. You can also provide a snippet of JavaScript (executed at the end of window.onload) or CSS (added to the end of the <style> section). Other JavaScript that you want to add may be added in <script> tags within the body.

You provide... You get... Use if...
Simple HTML code for form and, optionally, some CSS or JavaScript Ability to use any JavaScript and CSS you want Your HIT requires some fancy JavaScript or formatting or you just prefer to code your HIT interface in HTML
create_hit(xml[, max_assignments[, lifetime[, requester_annotation]]])

XML. You provide XML conforming to AMT’s QuestionForm specification.

You provide... You get... Use if...
QuestionForm XML document conforming to AMT’s specification Canned input fields You want to use AMT’s canned input fields but the shortcut form of this (below) does not cover what you need
create_hit(fields[, max_assignments[, lifetime[, requester_annotation]]])

Input fields. This is a shortcut for the previous option. You provide a list of input fields. This list may also contain strings, which will be displayed to the worker as instructions. If any of the strings or input field labels contain simple XHTML tags, they will be interpreted as XHTML.

You provide... You get... Use if...
Simple objects created with CrowdLib, optionally including limited formatting in XHTML Canned input fields You want to use AMT’s canned input fields

Default arguments come from your crowdlib_settings file.

Parameters:
  • url (basestring) – URL of a web page with your HIT UI; should be https:// (SSL); if plain http:// (non-SSL) were used, some browsers would not display it.
  • height (int) – height of the IFRAME in which your web page will be displayed
  • fields (iterable of QuestionField) – one QuestionField for each question in the HIT.
  • html (basestring) – complete HTML document
  • body (basestring) – complete HTML document
  • onload (basestring) – JavaScript code to be executed at the end of the window.onload handler; other JavaScript code can be included in <onload> tags within the body.
  • style (basestring) – CSS code
  • xml (basestring) – QuestionForm XML element
  • max_assignments (int) – number of judgments requested; up to this many workers may do this same HIT
  • lifetime (datetime expression or duration expression) – time or duration after which this HIT will expire, i.e., become unavailable to be accepted by workers
  • requester_annotation (basestring) – arbitrary string which you can use to track the HIT; it will be stored on AMT’s servers and returned with results, but will never be shown to workers.
Return type:

HIT

HIT

class HIT
id

30-character string used by AMT

Type:basestring
answers
Type:sequence of Answer
assignments
Type:sequence of Assignment
creation_time

various formats accepted

Type:datetime.datetime
expiration_time

WRITABLE PROPERTY – Set to a time or duration in the future to extend the HIT.

Type:datetime.datetime (when getting) or any datetime expression or duration expression (when setting)
hit_status
Type:basestring
hit_type
Type:HITType
hourly_rate

currency

Type:float
is_available
Type:bool
max_assignments

WRITABLE PROPERTY – Set to a value greater than the current value of max_assignments to extend the HIT.

Type:int
num_available
Type:int
num_completed
Type:int
num_pending
Type:int
num_reviewable
Type:int
num_submitted
Type:int
question_xml

XML

Type:basestring
requester_annotation
Type:basestring
workers
Type:sequence of Worker

Assignment

class Assignment
id

30-character string used by AMT

Type:basestring
accept_time
Type:datetime.datetime
answers
Type:sequence of Answer
approval_time

various formats accepted

Type:datetime.datetime
approve([feedback=None])
Parameters:feedback (basestring) – message that will be visible to workers (e.g., "Thanks for the careful attention to detail!")
assignment_status
Type:basestring
autopay_time

various formats accepted

Type:datetime.datetime
bonuses_paid
Type:Bonus
bonuses_paid_total_amount

currency

Type:float
grant_bonus(amount, reason)
Parameters:
  • amount (float) – currency
  • reason (basestring) – message to the worker
hit
Type:HIT
hourly_rate

currency

Type:float
is_final
Type:bool
is_paid
Type:bool
is_rejected
Type:bool
reject([feedback])
Parameters:feedback (basestring) – message shown to worker
rejection_time

various formats accepted

Type:datetime.datetime
requester_feedback
Type:basestring
submit_time

various formats accepted

Type:datetime.datetime
time_spent
Type:datetime.timedelta
worker
Type:Worker

Worker

class Worker
id
Type:basestring
approval_rate

percent, 0-100

Type:int
assignments
Type:sequence of Assignment
block(reason)
Parameters:reason (basestring) – reason for blocking (e.g., “poor quality”); stored locally by CrowdLib; not retrievable from AMT
bonuses_paid
Type:Bonus
hit_types
Type:sequence of HITType
hits
Type:sequence of HIT
hourly_rate

currency

Type:float
is_blocked
Type:bool
reason_blocked
Type:basestring
send_message(subject, message)

Send an email to the worker through AMT. It will come from the email address associated with your AMT account.

Parameters:
unblock(reason)
Parameters:reason (basestring) – reason for unblocking the worker; not visible to the worker; not stored by CrowdLib; not retrievable from AMT

Answer

class Answer
id
Type:basestring
answer_type
Type:basestring
assignment
Type:Assignment
question_id
Type:basestring
text
Type:basestring
choices
Type:sequence of basestring
index
Type:int
content

Content of the uploaded file. This is only valid for file upload questions.

Type:str or buffer
key
Type:basestring
save(filename)

Save the uploaded file locally. This is only valid for file upload questions.

Parameters:filename (basestring) – path
size

Size of the uploaded file. This is only valid for file upload questions.

Type:int

QualificationType

class QualificationType
id
Type:basestring
answer_key_xml

XML

Type:basestring
auto_granted
Type:bool
auto_granted_value
Type:int
create_requirement(comparator, value)
Parameters:
  • comparator (basestring) – “=”, “<”, “>”, “>=”, “<=”, or ”!=”
  • value (int) – integer value
Return type:

QualificationRequirement

creation_time

various formats accepted

Type:datetime.datetime
description
Type:basestring
is_active
Type:bool
is_requestable
Type:bool
keywords
Type:sequence of basestring
name
Type:basestring
retry_delay
Type:datetime.timedelta
time_limit
Type:datetime.timedelta
test_xml

XML

Type:basestring

QualificationRequirement

class QualificationRequirement
comparator

"=", "<", ">", ">=", "<=", or "!="

Type:basestring
qualification_type_id

Only the qualification type ID is returned because for AMT’s built-in qualification types (e.g., approval rate, etc.), there is no corresponding QualificationType object.

Type:basestring
required_to_preview
Type:bool
value

2-character ISO 3166 country code

Type:int or str

NotificationEvent

Note

Notification support has not been tested recently and might be broken.

class NotificationEvent
event_type

One of the following: "AssignmentAccepted", "AssignmentAbandoned", "AssignmentReturned", "AssignmentSubmitted", "HITReviewable", "HITExpired", "Ping" (only used in conjunction with send_test_notification())

Type:basestring
event_time
Type:datetime.datetime
hit
Type:HIT
hit_type
Type:HITType
assignment
Type:Assignment
class Bonus
payment_time

various formats accepted

Type:datetime.datetime
amount

amount of bonus, in US dollars

Type:float

RequesterStatistics

class RequesterStatistics

Example: cumulative

>>> import crowdlib as cl, crowdlib_settings
>>> print cl.requester_statistics.average_reward_amount
0.713

For more information on the semantics of each statistic, see GetRequesterStatistic in the AMT API documentation.

average_reward_amount

currency

Type:float
estimated_fee_liability

currency

Type:float
estimated_reward_liability

currency

Type:float
estimated_total_liability

currency

Type:float
number_assignments_abandoned
Type:int
number_assignments_accepted
Type:int
number_assignments_approved
Type:int
number_assignments_available
Type:int
number_assignments_pending
Type:int
number_assignments_rejected
Type:int
number_assignments_returned
Type:int
number_hits_assignable_last_night
Type:int
number_hits_completed
Type:int
number_hits_created
Type:int
number_hits_reviewable
Type:int
percent_assignments_approved

percent, 0-100

Type:int
percent_assignments_rejected

percent, 0-100

Type:int
total_bonus_fee_payout

currency

Type:float
total_bonus_payout

currency

Type:float
total_fee_payout

currency

Type:float
total_reward_and_fee_payout

currency

Type:float
total_reward_fee_payout

currency

Type:float
total_reward_payout

currency

Type:float

Exceptions

exception QuestionXMLError

The question XML had an error. If you passed in a QuestionForm XML structure, it probably had an error.

exception HITNotFoundException
hit_id
Type:basestring
exception HITTypeNotFoundException
hit_type_id
Type:basestring
exception AssignmentNotFoundException
assignment_id
Type:basestring
exception QualificationTypeNotFoundException
qualification_type_id
Type:basestring
exception WorkerNotFoundException
worker_id
Type:basestring
exception AMTDataError

The data received from AMT was not consistent. This could happen if a counter in one place (e.g., # of assignments) did not match the data actually returned (e.g., assignment records). It could be due to a bug in CrowdLib, a misunderstanding of the meaning of the counters, or a glitch on AMT’s servers.

exception XMLProcessingException

Indicates that CrowdLib received something unexpected from the AMT server. This is probably not due to the XML you passed in.

exception AMTQualificationTypeAlreadyExists

When attempting to create a QualificationType, AMT reported that there is already a QualificationType with the same name registered. Most likely, some other attribute was different. Try changing the name slightly.

name
Type:basestring
code

Error code received from AMT

Type:basestring
msg

Message received from AMT

Type:basestring
operation

Operation that we were trying to execute on the AMT server

Type:basestring
exception AMTRequestFailed
code

Error code received from AMT

Type:basestring
msg

Message received from AMT

Type:basestring
operation

Operation that we were trying to execute on the AMT server

Type:basestring
exception CrowdLibBaseException

Base class of all of the above exception types. This currently serves no purpose and may be removed in the future.

Referring to time

datetime expression

A datetime expression is either a datetime.datetime object like this:

  • datetime.datetime(2013, 2, 15, 14, 25, 0)

... or a string in any of the following formats:

  • "2/15/2013 2:25 PM"
  • "2-15-2013 2:25 PM"
  • "2-15-2013 14:25"
  • "2-15-2013 14:25:00"
  • "2013-02-15 14:25"
  • "2013-02-15 14:25:00"

These are internally converted to datetime.datetime objects using to_datetime().

to_datetime(datetime_value)
Parameters:datetime_value (datetime.datetime or basestring) – datetime expression
Return type:datetime.datetime

date expression

A date expression is either a datetime.date object or a string in any of the following formats:

  • "2013-02-15"
  • "02-15-2013"
  • "02/15/2013"

These are internally converted to datetime.date objects using to_date().

to_date(date_value)
Parameters:date_value (datetime.date or basestring) – date expression
Return type:datetime.date

duration expression

A duration expression is either a datetime.timedelta object, a number of seconds (int or float), or a string in any of the following formats:

  • "45 minutes"
  • "1 hour"
  • "12 hours"
  • "1 day"
  • "3 days"
  • "1 week"

These are internally converted to datetime.timedelta objects using to_duration().

to_duration(duration_value)
Parameters:duration_value (datetime.timedelta, int, or basestring) – duration expression
Return type:datetime.timedelta