crowdflower
===========

Client library for interacting with the
`CrowdFlower <http://www.crowdflower.com/>`__
`API <http://success.crowdflower.com/customer/portal/articles/1288323-api-documentation>`__
with Python.

Installation
------------

Install from PyPI:

::

    easy_install -U crowdflower

Or install the latest version GitHub:

::

    git clone https://github.com/chbrown/crowdflower.git
    cd crowdflower
    python setup.py develop

Import examples
---------------

Import:

::

    import crowdflower

CrowdFlower API keys are 20 characters long; the one below is just
random characters.

::

    conn = crowdflower.Connection('LbcxvIlE3x1M8F6TT5hN')

The library will default to an environment variable called
``CROWDFLOWER_API_KEY`` if none is specified here:

::

    conn = crowdflower.Connection()

If you want to cache job responses, like judgments, properties, and
tags, you can initialize the connection with a cache.
``cache='filesystem'`` is the only option currently supported, and
serializes JSON files to ``/tmp/crowdflower/*``.

::

    conn = crowdflower.Connection(cache='filesystem')

More examples
-------------

Loop through all your jobs and print the titles:

::

    for job in conn.jobs():
        print job.properties['title']

Create a new job with some new units:

::

    data = [
        {'id': '1', 'name': 'Chris Narenz', 'gender_gold': 'male'},
        {'id': '2', 'name': 'George Henckels'},
        {'id': '3', 'name': 'Maisy Ester'},
    ]
    job = conn.upload(data)
    job.update({
        'title': 'Gender labels',
        'included_countries': ['US', 'GB'],  # Limit to the USA and United Kingdom
        'payment_cents': 5,
        'judgments_per_unit': 2,
        'instructions': <some instructions html>,
        'cml': <some layout cml>,
        'options': {
            'front_load': 1, # quiz mode = 1; turn off with 0
        }
    })
    job.gold_add('gender', 'gender_gold')

    print job

References
----------

This package uses `kennethreitz <https://github.com/kennethreitz>`__'s
`Requests <http://docs.python-requests.org/en/latest/api/>`__ to
communicate with the CrowdFlower API over HTTP. Requests is `Apache2
licensed <http://docs.python-requests.org/en/latest/user/intro/#apache2-license>`__.

License
-------

Copyright © 2014 Christopher Brown. `MIT
Licensed <https://raw.github.com/chbrown/crowdflower/master/LICENSE>`__.
