crowdflower.client

exception crowdflower.client.ApiError

API error class, wraps HTTP exceptions and such.

class crowdflower.client.Client(key)

CrowdFlower API client. Requires API key for authentication.

TODO: Trust data model types in order to provide general methods instead of specialized do_this and do_that methods.

Parameters:key – CrowdFlower API key. Required for authentication.
add_job_tag(job_id, tag)

Add tag to job.

call(path, data=None, headers={}, query={}, method='get', files=None, as_json=True)

Data may be str (unicode) or bytes. Unicode strings will be encoded to UTF-8 bytes.

Parameters:
  • data (str, bytes or dict) – Byte data for POST
  • headers (dict) – Additional headers
  • query (dict) – Additional query parameters
  • method (str) – GET, POST, PUT or DELETE
  • files (dict) – Files to upload
  • as_json (bool) – Handle response as json, defaults to True
Returns:

JSON dictionary
Return type:

dict
cancel_unit(job_id, unit_id)

Cancel unit.

convert_job_test_questions(job_id)

Convert uploaded gold to test questions.

copy_job(job_id, all_units, gold)

Copy Job job_id to a new job.

Parameters:
  • all_units – If true, all of this job’s units will be copied to the new job.
  • gold – If true, only golden units will be copied to the new job.
Returns:

crowdflower.job.Job
create_job(attrs)

Create new job with attrs, where attributes of most interest are:

  • title
  • instructions
  • cml
  • js
  • css

Other R/W attributes:

  • auto_order
  • auto_order_threshold
  • auto_order_timeout
  • fields
  • confidence_fields
  • custom_key
  • excluded_countries
  • gold_per_assignment
  • included_countries
  • judgments_per_unit
  • language
  • max_judgments_per_unit
  • max_judgments_per_contributor
  • min_unit_confidence
  • options
  • pages_per_assignment
  • problem
  • send_judgments_webhook
  • state
  • units_per_assignment
  • webhook_uri
Parameters:attrs (dict) – JSON dictionary of attributes for new job
Returns:Newly created Job
Return type:crowdflower.job.Job
debit_order(job, units_count, channels)

Create a debit order for Job with units_count at channels.

delete_job(job_id)

Delete job job_id from CrowdFlower.

get_job(job_id)

Get Job job_id

Parameters:job_id (int) – Id of crowdflower job to get
Returns:Crowdflower job
Return type:crowdflower.job.Job
get_job_channels(job_id)

Get available and enabled channels for job_id.

# A response JSON dictionary
{
    "enabled_channels": [
        "amt"
    ],
    "available_channels": [
        "amt",
        "sama",
        "gambit",
        "mob",
        "iphone"
    ]
}
get_job_tags(job_id)

Get tags for job.

get_jobs()

Get Jobs connected to this client and key.

Returns:an iterator of CrowdFlower jobs
Return type:iter of crowdflower.job.Job
get_judgment(job, judgment_id)

Get Judgment judgment_id for job.

get_judgmentaggregates(job)

Get JudgmentAggregates for job.

Note

Return value from judgments.json seems to be a dictionary, where the keys are Unit ids and values an aggregate of a sort. The aggregate lacks documentation at https://crowdflower.com/docs-api , so this code is very very likely to break in the future.

get_order(job, order_id)

Get Order by order_id for Job job.

get_report(job, type_='json')

Download and uncompress reports. Returns a list of Units.

get_unit(job, unit_id)

Get Unit unit_id for Job.

get_units(job)

Get unit promises for Job.

paged_call(*args, **kwgs)

Generate paged calls to API end points, wraps _call(). Provide sentinel in order to stop paging at desired point. If sentinel is a function, it should accept latest response as argument.

This can not yield items from response, since some responses are dictionaries, while others are lists.

Parameters:
  • page – Page to start at, defaults to 1.
  • limit – Limit pages to limit items, defaults to 100.
  • sentinel – Sentinel value for iter().
set_job_channels(job_id, channels)

Enable channels for job_id.

Parameters:
  • job_id – Id of job to set channels for
  • channels – a list of channels to enable
set_job_tags(job_id, tags)

Set tags for job.

unit_from_json(data)

Create a new Unit instance from JSON data.

update_job(job_id, attrs)

Update Job job_id with attrs

Parameters:
  • job_id (int) – Id of crowdflower job to update
  • attrs (dict) – JSON dictionary of attributes to update
upload_job(data, job_id=None, force=False)

Upload given data as JSON.

Parameters:
  • data (collections.abc.Iterable) – Iterable of JSON serializable objects
  • job_id (int) – Id of a crowdflower job to update (optional)
  • force (bool) – If True force adding units even if the columns do not match existing data
Returns:

crowdflower.job.Job instance
Return type:

crowdflower.job.Job
upload_job_file(file, type_=None, job_id=None, force=False)

Upload a file like object or open a file for reading and upload.

Caller is responsible for handling context on file like objects. Type must be provided with data as there is no information to make a guess from. If file like object provides text (unicode) data, it will be encoded to UTF-8 bytes.

If explicit type_ is not provided and the file is a string containing a filename to open, will make a guess with mimetypes. Returns a new Job instance related to the uploaded data.

If type information is not given and guessing did not work, will raise a ValueError.

Parameters:
  • file (str or file) – A file like object or a filename string, contains UTF-8 encoded data
  • type (str) – Explicit type, required for file like objects
  • job_id (int) – Id of a crowdflower job to update (optional)
  • force (bool) – If True force adding units even if the columns do not match existing data
Returns:

crowdflower.job.Job instance
Return type:

crowdflower.job.Job
class crowdflower.client.PathFactory(client, name=())

Magic attribute/item syntax for making calls.