SurveyGizmo 1.2.3

Requirements

• python: 2.7, 3.4, 3.5, 3.6

Installation

$ pip install SurveyGizmo

Usage

Start by instantiating the SurveyGizmo object and providing some configuration parameters. Options can also be set through the config property.

from surveygizmo import SurveyGizmo

client = SurveyGizmo(
    api_version='v4'

    # example token from SurveyGizmo docs
    api_token = "E4F796932C2743FEBF150B421BE15EB9"
    api_token_secret = "A9fGMkJ5pJF1k"
)

# Update client options through the config property.
client.config.api_token = "E4F796932C2743FEBF150B421BE15EB9"
client.config.api_token_secret = "A9fGMkJ5pJF1k"

Calls to the api are by object type then by function. For example,

client.api.survey.list()
client.api.survey.get('39501')
client.api.survey.copy('39501', 'New title boop')
client.api.surveyresponse.list('39501')

Most resources have the list, get, create, update, copy, and delete actions. If SurveyGizmo’s REST API does not implement an action, the client will raise a NotImplementedError.

Authentication

Token based authentication is the only currently supported authentication method. user:pass and user:md5 were deprecated on May 31, 2016. Oauth support is not currently a goal, but pull requests are welcome.

client.config.api_token = 'E4F796932C2743FEBF150B421BE15EB9'
client.config.api_token_secret = 'A9fGMkJ5pJF1k'

API Filtering

SurveyGizmo’s API supports filtering for list calls on surveys, survey campaigns, and survey responses. For more information, reference the SurveyGizmo filter documentation.

The filtering implementation contains no real magic and is simply a convenience wrapper around the awkward filtering semantics. There is no enforcement of which resources can perform filtering or what types of properties are being filtered for a resource.

To filter, simply

filtered = client.api.surveyresponse.filter('datesubmitted', '<=', '2013-07-01')
filtered.list('39501')

Filtering is also chainable.

client.api.survey.filter('createdon', '<=', '2013-04-01').list()
...

client.api.surveyresponse \
    .filter('datesubmitted', '<=', '2013-07-01') \
    .filter('datesubmitted', '>', '2013-06-01') \
    .list('39501')

Config paramaters

• api_version - ‘v3’, ‘v4’, ‘head’. Defaults to ‘head’

• api_token

• api_token_secret

• response_type - None, 'json', 'pson', 'xml', 'debug'. By default (using None), the API returns a JSON response which is parsed by the client into a python dictionary. Specifying a response_type will return an unparsed body of the specified format.

• requests_kwargs - Additional arguments passed to requests.get. Useful for setting timeouts and otherwise configuring the requests library.

• prepare_url - Force the client to return the url after being prepared instead of executing the api call. This is useful in cases where you need to call the api asynchronously. Defaults to ‘False’

• handler52x - Handler for CloudFlare’s 52x errors. Expects a callable (e.g., surveygizmo.default_52xhandler). Defaults to ‘None’.

CloudFlare 52x Errors

After SurveyGizmo’s move to CloudFlare, it isn’t uncommon to see connectivity issues where the service is temporarily unreachable. These errors exist on the 52x range of HTTP status codes. To automatically handle 52x errors, set a callable for config.handler52x. A basic handler is provided under surveygizmo.default_52xhandler, which simply retries the request every second until a non-52x response is returned.

API Resources

• api.account

• api.accountteams

• api.accountuser

• api.contact

• api.contactlist

• api.emailmessage

• api.survey

• api.surveycampaign

• api.surveyoption

• api.surveypage

• api.surveyquestion

• api.surveyreport

• api.surveyresponse

• api.surveystatistic

Changelog

Release Process

• Update package version in setup.py

• Create git tag for version

• Upload release to PyPI

  $ pip install -U pypandoc setuptools wheel
  $ rm -rf dist/ build/
  $ python setup.py sdist bdist_wheel upload

Copyright & License

Copyright © 2013-2016 NC State University. See LICENSE for details.