Metadata-Version: 1.1
Name: SurveyGizmo
Version: 1.2.3
Summary: A Python Wrapper for SurveyGizmo's restful API service.
Home-page: https://github.com/ITNG/SurveyGizmo/
Author: Ryan P Kilby
Author-email: rpkilby@ncsu.edu
License: BSD License
Description-Content-Type: UNKNOWN
Description: 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
        
Keywords: Survey Gizmo SurveyGizmo surveygizmo
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
