SurveyGizmo
===========
A Python Wrapper for
`SurveyGizmo <https://apihelp.surveygizmo.com/help>`__'s mostly restful
API service.
|Build Status| |codecov|
Requirements
------------
- **python**: 2.7, 3.4, 3.5, 3.6
Installation
------------
.. code:: sh
$ pip install SurveyGizmo
Usage
-----
Start by instantiating the SurveyGizmo object and providing some
configuration parameters. Options can also be set through the ``config``
property.
.. code:: python
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,
.. code:: python
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 <https://community.surveygizmo.com/questions/question/final-notice-surveygizmo-api-authentication-changes/>`__
on May 31, 2016. Oauth support is not currently a goal, but pull
requests are welcome.
token
~~~~~
.. code:: python
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 <https://apihelp.surveygizmo.com/help/article/link/filters>`__.
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
.. code:: python
filtered = client.api.surveyresponse.filter('datesubmitted', '<=', '2013-07-01')
filtered.list('39501')
Filtering is also chainable.
.. code:: python
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 <https://apihelp.surveygizmo.com/help/article/link/account-object>`__
- `api.accountteams <https://apihelp.surveygizmo.com/help/article/link/accountteams-object>`__
- `api.accountuser <https://apihelp.surveygizmo.com/help/article/link/accountuser-object>`__
- `api.contact <https://apihelp.surveygizmo.com/help/article/link/contact-sub-object>`__
- `api.contactlist <https://apihelp.surveygizmo.com/help/article/link/contactlist-object>`__
- `api.emailmessage <https://apihelp.surveygizmo.com/help/article/link/emailmessage-sub-object>`__
- `api.survey <https://apihelp.surveygizmo.com/help/article/link/survey-object>`__
- `api.surveycampaign <https://apihelp.surveygizmo.com/help/article/link/surveycampaign-sub-object>`__
- `api.surveyoption <https://apihelp.surveygizmo.com/help/article/link/surveyoption-sub-object>`__
- `api.surveypage <https://apihelp.surveygizmo.com/help/article/link/surveypage-sub-object>`__
- `api.surveyquestion <https://apihelp.surveygizmo.com/help/article/link/surveyquestion-sub-object>`__
- `api.surveyreport <https://apihelp.surveygizmo.com/help/article/link/surveyreport-sub-object>`__
- `api.surveyresponse <https://apihelp.surveygizmo.com/help/article/link/surveyresponse-sub-object>`__
- `api.surveystatistic <https://apihelp.surveygizmo.com/help/article/link/surveystatistic-sub-object>`__
Changelog
---------
1.2.3
~~~~~
- .. rubric:: 21 Make the 'base\_url' configurable.
:name: make-the-base_url-configurable.
- Drop explicit python 3.3 support.
1.2.2
~~~~~
- .. rubric:: 17 Added basic pagination support. Thanks @WesleyBatista!
:name: added-basic-pagination-support.-thanks-wesleybatista
1.2.1
~~~~~
- Added ``_prepare_url`` argument to API calls that overrides the
configured setting for ``prepare_url``.
1.2.0
~~~~~
- Reimplmented API import as metaclass.
- Reimplemented filtering, removed race condition.
1.1.0
~~~~~
- Added required parameters various API calls (mostly create).
1.0.0
~~~~~
1.0.0 is a reimplementation of the entire API. Tests have been added and
the package is basically stable.
- Replace all authentication methods with only token based
authentication.
- Rewrite API to use class inheritance instead of module function
wrapping.
- Remove ``preserve_filters`` option.
- Rename ``add_filter`` to just ``filter``. Filters are chainable.
0.2.0
~~~~~
0.2.0 is a forwards incompatible release, but only minorly so.
Forwards incompatible changes:
- Renamed the 'change' operations to 'update'. This is consistent with
SurveyGizmo's API naming.
- Removed the 'keep' kwarg for preserving filters bettween api funcion
calls. This is now configured with 'preserve\_filters'. Filters are
now cleared manually with ``api.clear_filters()``
- Removed the undocumented 'url\_fetch' kwarg, which prevented api
execution and instead returned the prepared url.
Backwards incompatible changes:
- Modified 'api\_version' to no longer has any effect on the client.
SurveyGizmo provides no way to meaningfully differentiate between API
versions, so this checking was unneeded and created code duplication
- Added 'prepare\_url' as a replacement for 'url\_fetch'. This forces
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.
- Added 'requests\_kwargs'. These are additional arguments passed to
``requests.get``. Useful for setting timeouts and otherwise
configuring the requests library.
- Added handling for CloudFlare 52x errors
Release Process
---------------
- Update package version in ``setup.py``
- Create git tag for version
- Upload release to PyPI
.. code:: bash
$ 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.
.. |Build Status| image:: https://travis-ci.org/ITNG/SurveyGizmo.svg?branch=master
:target: https://travis-ci.org/ITNG/SurveyGizmo
.. |codecov| image:: https://codecov.io/gh/ITNG/SurveyGizmo/branch/master/graph/badge.svg
:target: https://codecov.io/gh/ITNG/SurveyGizmo
Raw data
{
"_id": null,
"home_page": "https://github.com/ITNG/SurveyGizmo/",
"name": "SurveyGizmo",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Survey Gizmo SurveyGizmo surveygizmo",
"author": "Ryan P Kilby",
"author_email": "rpkilby@ncsu.edu",
"download_url": "https://files.pythonhosted.org/packages/6c/a8/35a500992debb95a2425757fbec05182d1ff36f43d20bc98816c092fd3f3/SurveyGizmo-1.2.3.tar.gz",
"platform": "",
"description": "SurveyGizmo\n===========\n\nA Python Wrapper for\n`SurveyGizmo <https://apihelp.surveygizmo.com/help>`__'s mostly restful\nAPI service.\n\n|Build Status| |codecov|\n\nRequirements\n------------\n\n- **python**: 2.7, 3.4, 3.5, 3.6\n\nInstallation\n------------\n\n.. code:: sh\n\n $ pip install SurveyGizmo\n\nUsage\n-----\n\nStart by instantiating the SurveyGizmo object and providing some\nconfiguration parameters. Options can also be set through the ``config``\nproperty.\n\n.. code:: python\n\n from surveygizmo import SurveyGizmo\n\n client = SurveyGizmo(\n api_version='v4'\n\n # example token from SurveyGizmo docs\n api_token = \"E4F796932C2743FEBF150B421BE15EB9\"\n api_token_secret = \"A9fGMkJ5pJF1k\"\n )\n\n # Update client options through the config property.\n client.config.api_token = \"E4F796932C2743FEBF150B421BE15EB9\"\n client.config.api_token_secret = \"A9fGMkJ5pJF1k\"\n\nCalls to the api are by object type then by function. For example,\n\n.. code:: python\n\n client.api.survey.list()\n client.api.survey.get('39501')\n client.api.survey.copy('39501', 'New title boop')\n client.api.surveyresponse.list('39501')\n\nMost resources have the list, get, create, update, copy, and delete\nactions. If SurveyGizmo's REST API does not implement an action, the\nclient will raise a ``NotImplementedError``.\n\nAuthentication\n--------------\n\nToken based authentication is the only currently supported\nauthentication method. ``user:pass`` and ``user:md5`` were\n`deprecated <https://community.surveygizmo.com/questions/question/final-notice-surveygizmo-api-authentication-changes/>`__\non May 31, 2016. Oauth support is not currently a goal, but pull\nrequests are welcome.\n\ntoken\n~~~~~\n\n.. code:: python\n\n client.config.api_token = 'E4F796932C2743FEBF150B421BE15EB9'\n client.config.api_token_secret = 'A9fGMkJ5pJF1k'\n\nAPI Filtering\n-------------\n\nSurveyGizmo's API supports filtering for ``list`` calls on surveys,\nsurvey campaigns, and survey responses. For more information, reference\nthe SurveyGizmo `filter\ndocumentation <https://apihelp.surveygizmo.com/help/article/link/filters>`__.\n\nThe filtering implementation contains no real magic and is simply a\nconvenience wrapper around the awkward filtering semantics. There is no\nenforcement of which resources can perform filtering or what types of\nproperties are being filtered for a resource.\n\nTo filter, simply\n\n.. code:: python\n\n filtered = client.api.surveyresponse.filter('datesubmitted', '<=', '2013-07-01')\n filtered.list('39501')\n\nFiltering is also chainable.\n\n.. code:: python\n\n client.api.survey.filter('createdon', '<=', '2013-04-01').list()\n ...\n\n client.api.surveyresponse \\\n .filter('datesubmitted', '<=', '2013-07-01') \\\n .filter('datesubmitted', '>', '2013-06-01') \\\n .list('39501')\n\nConfig paramaters\n-----------------\n\n- **api\\_version** - 'v3', 'v4', 'head'. Defaults to 'head'\n- **api\\_token**\n- **api\\_token\\_secret**\n- **response\\_type** - ``None``, ``'json'``, ``'pson'``, ``'xml'``,\n ``'debug'``. By default (using ``None``), the API returns a JSON\n response which is parsed by the client into a python dictionary.\n Specifying a ``response_type`` will return an unparsed body of the\n specified format.\n- **requests\\_kwargs** - Additional arguments passed to\n ``requests.get``. Useful for setting timeouts and otherwise\n configuring the requests library.\n- **prepare\\_url** - Force the client to return the url after being\n prepared instead of executing the api call. This is useful in cases\n where you need to call the api asynchronously. Defaults to 'False'\n- **handler52x** - Handler for CloudFlare's 52x errors. Expects a\n callable (e.g., ``surveygizmo.default_52xhandler``). Defaults to\n 'None'.\n\nCloudFlare 52x Errors\n---------------------\n\nAfter SurveyGizmo's move to CloudFlare, it isn't uncommon to see\nconnectivity issues where the service is temporarily unreachable. These\nerrors exist on the 52x range of HTTP status codes. To automatically\nhandle 52x errors, set a callable for ``config.handler52x``. A basic\nhandler is provided under ``surveygizmo.default_52xhandler``, which\nsimply retries the request every second until a non-52x response is\nreturned.\n\nAPI Resources\n-------------\n\n- `api.account <https://apihelp.surveygizmo.com/help/article/link/account-object>`__\n- `api.accountteams <https://apihelp.surveygizmo.com/help/article/link/accountteams-object>`__\n- `api.accountuser <https://apihelp.surveygizmo.com/help/article/link/accountuser-object>`__\n- `api.contact <https://apihelp.surveygizmo.com/help/article/link/contact-sub-object>`__\n- `api.contactlist <https://apihelp.surveygizmo.com/help/article/link/contactlist-object>`__\n- `api.emailmessage <https://apihelp.surveygizmo.com/help/article/link/emailmessage-sub-object>`__\n- `api.survey <https://apihelp.surveygizmo.com/help/article/link/survey-object>`__\n- `api.surveycampaign <https://apihelp.surveygizmo.com/help/article/link/surveycampaign-sub-object>`__\n- `api.surveyoption <https://apihelp.surveygizmo.com/help/article/link/surveyoption-sub-object>`__\n- `api.surveypage <https://apihelp.surveygizmo.com/help/article/link/surveypage-sub-object>`__\n- `api.surveyquestion <https://apihelp.surveygizmo.com/help/article/link/surveyquestion-sub-object>`__\n- `api.surveyreport <https://apihelp.surveygizmo.com/help/article/link/surveyreport-sub-object>`__\n- `api.surveyresponse <https://apihelp.surveygizmo.com/help/article/link/surveyresponse-sub-object>`__\n- `api.surveystatistic <https://apihelp.surveygizmo.com/help/article/link/surveystatistic-sub-object>`__\n\nChangelog\n---------\n\n1.2.3\n~~~~~\n\n- .. rubric:: 21 Make the 'base\\_url' configurable.\n :name: make-the-base_url-configurable.\n\n- Drop explicit python 3.3 support.\n\n1.2.2\n~~~~~\n\n- .. rubric:: 17 Added basic pagination support. Thanks @WesleyBatista!\n :name: added-basic-pagination-support.-thanks-wesleybatista\n\n1.2.1\n~~~~~\n\n- Added ``_prepare_url`` argument to API calls that overrides the\n configured setting for ``prepare_url``.\n\n1.2.0\n~~~~~\n\n- Reimplmented API import as metaclass.\n- Reimplemented filtering, removed race condition.\n\n1.1.0\n~~~~~\n\n- Added required parameters various API calls (mostly create).\n\n1.0.0\n~~~~~\n\n1.0.0 is a reimplementation of the entire API. Tests have been added and\nthe package is basically stable.\n\n- Replace all authentication methods with only token based\n authentication.\n- Rewrite API to use class inheritance instead of module function\n wrapping.\n- Remove ``preserve_filters`` option.\n- Rename ``add_filter`` to just ``filter``. Filters are chainable.\n\n0.2.0\n~~~~~\n\n0.2.0 is a forwards incompatible release, but only minorly so.\n\nForwards incompatible changes:\n\n- Renamed the 'change' operations to 'update'. This is consistent with\n SurveyGizmo's API naming.\n- Removed the 'keep' kwarg for preserving filters bettween api funcion\n calls. This is now configured with 'preserve\\_filters'. Filters are\n now cleared manually with ``api.clear_filters()``\n- Removed the undocumented 'url\\_fetch' kwarg, which prevented api\n execution and instead returned the prepared url.\n\nBackwards incompatible changes:\n\n- Modified 'api\\_version' to no longer has any effect on the client.\n SurveyGizmo provides no way to meaningfully differentiate between API\n versions, so this checking was unneeded and created code duplication\n- Added 'prepare\\_url' as a replacement for 'url\\_fetch'. This forces\n the client to return the url after being prepared instead of\n executing the api call. This is useful in cases where you need to\n call the api asynchronously.\n- Added 'requests\\_kwargs'. These are additional arguments passed to\n ``requests.get``. Useful for setting timeouts and otherwise\n configuring the requests library.\n- Added handling for CloudFlare 52x errors\n\nRelease Process\n---------------\n\n- Update package version in ``setup.py``\n- Create git tag for version\n- Upload release to PyPI\n\n .. code:: bash\n\n $ pip install -U pypandoc setuptools wheel\n $ rm -rf dist/ build/\n $ python setup.py sdist bdist_wheel upload\n\nCopyright & License\n-------------------\n\nCopyright \u00a9 2013-2016 NC State University. See LICENSE for details.\n\n.. |Build Status| image:: https://travis-ci.org/ITNG/SurveyGizmo.svg?branch=master\n :target: https://travis-ci.org/ITNG/SurveyGizmo\n.. |codecov| image:: https://codecov.io/gh/ITNG/SurveyGizmo/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/ITNG/SurveyGizmo\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "A Python Wrapper for SurveyGizmo's restful API service.",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/ITNG/SurveyGizmo/"
},
"split_keywords": [
"survey",
"gizmo",
"surveygizmo",
"surveygizmo"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5bca9f1e8d6072c22c2a6ba4c154b1410a699d42876e2ed220e42b714733a7b",
"md5": "092bb61d52a1e7e82fc447473da98a60",
"sha256": "a9aa5f8e56ac5811f04794eb479da6cef3bd38a2629dba91d4ee24e52eaaaf06"
},
"downloads": -1,
"filename": "SurveyGizmo-1.2.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "092bb61d52a1e7e82fc447473da98a60",
"packagetype": "bdist_wheel",
"python_version": "3.6",
"requires_python": null,
"size": 22194,
"upload_time": "2017-10-02T14:05:15",
"upload_time_iso_8601": "2017-10-02T14:05:15.807752Z",
"url": "https://files.pythonhosted.org/packages/b5/bc/a9f1e8d6072c22c2a6ba4c154b1410a699d42876e2ed220e42b714733a7b/SurveyGizmo-1.2.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ca835a500992debb95a2425757fbec05182d1ff36f43d20bc98816c092fd3f3",
"md5": "9fdd1617ffe4e45bfa0e89f0d934fd12",
"sha256": "39835621036d2bc61243c65d4f34cd0df745db3538b5cf315d740a8c725f9964"
},
"downloads": -1,
"filename": "SurveyGizmo-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "9fdd1617ffe4e45bfa0e89f0d934fd12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16283,
"upload_time": "2017-10-02T14:05:13",
"upload_time_iso_8601": "2017-10-02T14:05:13.875525Z",
"url": "https://files.pythonhosted.org/packages/6c/a8/35a500992debb95a2425757fbec05182d1ff36f43d20bc98816c092fd3f3/SurveyGizmo-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2017-10-02 14:05:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ITNG",
"github_project": "SurveyGizmo",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "surveygizmo"
}
JSON
