Merge pull request #6 from janrain/v0.3.0

v0.3.0 (requests and Python 3 support)

Author: cloeperJanrain

.gitignore

@@ -1,7 +1,60 @@
-*.pyc
-__pycache__
-*.egg-info
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
 distribute-*
-build
-dist
+
+# PyInstaller
+#  Usually these files are written by a python script from a template 
+#  before PyInstaller builds the exe, so as to inject date/other infos
+#  into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
 test.log
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Virtual Environment
+venv
+

.travis.yml

@@ -0,0 +1,10 @@
+language: python
+python:
+  - "2.7"
+  - "3.2"
+  - "3.3"
+  - "3.4"
+# command to install dependencies
+install: travis_retry python setup.py install
+# command to run tests
+script: nosetests --with-doctest

CONTRIBUTING.rst

@@ -0,0 +1,26 @@
+Contributing
+============
+
+Testing
+-------
+
+If you are using a **virtualenv** run the following before running tests::
+    
+    python setup.py install
+
+To run all tests::
+
+    python setup.py nosetests --with-doctest
+
+To run only doctests::
+    
+    python setup.py nosetests --doctest-tests
+
+To run one specific test suite::
+
+    python setup.py nosetests --tests janrain.capture.test.test_api
+
+To run a specific unit test::
+
+    python setup.py nosetests \
+        --tests janrain.capture.test.test_api:TestApi.test_api_encode

MANIFEST.in

@@ -1 +1 @@
-include README.rst MANIFEST.in LICENSE distribute_setup.py
+include README.rst LICENSE MANIFEST.in distribute_setup.py

README.rst

@@ -1,46 +1,44 @@
 Janrain Python API
 ==================
 
-Python interface to the 
+[![Build Status](https://travis-ci.org/janrain/janrain-python-api.png?branch=master)](https://travis-ci.org/janrain/janrain-python-api)
+
+Python interface to the
 `Janrain Capture <http://janrain.com/products/capture/>`_ API.
 
 
 Install
 -------
 
-Download and install the most recent stable version using ``pip`` (preferred)::
+Download and install the most recent stable version using ``pip``::
 
     pip install janrain-python-api
 
-... or using (``easy_install``)::
-
-    easy_install janrain-python-api
-
 
 To use the unstable developement version, download the package by cloning the git repository::
 
     git clone https://github.com/janrain/janrain-python-api.git
     cd janrain-python-api
     python setup.py install
-    
+
 
 Basic Usage
 -----------
 
 Low-Level API Calls
 ~~~~~~~~~~~~~~~~~~~
 
-Use ``janrain.capture.Api`` to make low-level calls to the API. 
+Use ``janrain.capture.Api`` to make low-level calls to the API.
 
 .. code-block:: python
 
-    from janrain.capture import api as Api
-    
+    from janrain.capture import Api
+
     defaults = {
-        'client_id': "YOUR_CLIENT_ID", 
+        'client_id': "YOUR_CLIENT_ID",
         'client_secret': "YOUR_CLIENT_SECRET"
     }
-    
+
     api = Api("https://YOUR_APP.janraincapture.com", defaults)
     result = api.call("entity.count", type_name="user")
     print(result)
@@ -49,31 +47,64 @@ Use ``janrain.capture.Api`` to make low-level calls to the API.
 Exceptions
 ~~~~~~~~~~
 
-Exceptions are derived from ``JanrainApiException`` which includes error 
-responses from the API. A try/catch bock should wrap any functions or methods 
+Exceptions are derived from ``JanrainApiException`` which includes error
+responses from the API. A try/catch bock should wrap any functions or methods
 that call the Janrain API.
 
 .. code-block:: python
 
+    from janrain.capture import Api, ApiResponseError
+    from requests import HTTPError
+
+    defaults = {
+        'client_id': "YOUR_CLIENT_ID",
+        'client_secret': "YOUR_CLIENT_SECRET"
+    }
+
+    api = Api("https://YOUR_APP.janraincapture.com", defaults)
+
     try:
         result = api.call("entity.find", type_name="user")
-    except janrain.capture.InvalidApiCallError as error:
-        # 404 error
-        sys.exit("Invalid API Endpoint: " + error.message)
     except janrain.capture.ApiResponseError as error:
-        # API returned an error response
-        sys.exit("API Error: " + error.message)
+        # Janrain API returned an error response
+        sys.exit(str(error))
+    except HTTPError as error:
+        # Python 'requests' library returned an error
+        sys.exit(str(error))
+
+
+Argument Parser
+~~~~~~~~~~~~~~~
+
+The library includes a subclass of the Python
+`argparse <https://docs.python.org/dev/library/argparse.html>`_ configured to
+accept credentials for authenticating with the Janrain API. This can be used to
+simplify passing in credentials in custom command-line scripts.
+
+.. code-block:: python
+
+    from janrain.capture import cli
+
+    parser = cli.ApiArgumentParser()
+    args = parser.parse_args()
+    api = parser.init_api()
+
+Which can then invoke from the command-line as follows::
+
+    python myscript.py  --api-url=[YOUR_CAPTURE_URL] \
+                        --client-id=[YOUR_CLIENT_ID] \
+                        --client-secret=[YOUR_CLIENT_SECRET] \
 
 
 Command-Line Utility
 --------------------
 
 The package installs an executable named ``capture-api`` for making
-API calls from the command-line. 
+API calls from the command-line.
 
-Authenticate with the API by passing ``--api-url``, ``--client-id``, 
+Authenticate with the API by passing ``--api-url``, ``--client-id``,
 and ``--client-secret``, then pass the API call, and then any parameters to
-send to the API as key=value pairs after the ``--parameters`` argument. 
+send to the API as key=value pairs after the ``--parameters`` argument.
 
 Examples
 ~~~~~~~~
@@ -95,12 +126,18 @@ Enclose JSON values in single outer-quotes and double inner-quotes::
 
 Enclose filters in double outer-quotes and single inner-quotes::
 
-        capture-api --api-url=[YOUR_CAPTURE_URL] \
+    capture-api --api-url=[YOUR_CAPTURE_URL] \
                 --client-id=[YOUR_CLIENT_ID] \
                 --client-secret=[YOUR_CLIENT_SECRET] \
                 entity.find --parameters type_name=user \
                 filter="email = 'demo@janrain.com' and birthday is null"
 
 ----
 
+Versioning
+----------
+This software follows Semantic Versioning convention.
+http://semver.org/
+
+
 Copyright © 2014 Janrain, Inc. All Rights Reserved.

janrain/capture/__init__.py

@@ -1,7 +1,7 @@
 from janrain.capture.api import Api
 from janrain.capture.exceptions import *
 
-VERSION = (0, 2, 4)
+VERSION = (0, 3, 0)
 
 def get_version():
     return "%s.%s.%s" % (VERSION[0], VERSION[1], VERSION[2])