CELTIC Python Bindings
======================
This module contains a thin wrapper around the CELTIC service which
allows for cross-platform LTI validation.
Dependencies
------------
- `requests <https://github.com/requests/requests>`__
Tests
-----
``tox`` is used as a test runner for this library. It is configured to
run tests for py27, py35 and py36.
::
pip install tox
tox
Usage
-----
::
from celtic_lib import get_lti_validator, LTIValidatorException
LTI_LISTEN_LOCATION = "https://localhost:8000/lti"
def handle_request(request):
"""
request contains some LTI payload you just received in your application
"""
app_key = "some_long_unique_string_unique_to_this_application"
celtic_service_uri = "https://location_of_celtic_service.net/"
lti_validator = get_lti_validator(celtic_service_uri, app_key)
http_method = request.method # Will be "POST", since we are only listening on the POST endpoint
try:
status, result = lti_validator.validate_request(LTI_LISTEN_LOCATION, http_method, request.POST)
return print("Request is valid and can be trusted")
except LTIValidatorException as e:
return print("Request failed:", e.message, "|", e.status_code)
# router is an imaginary application router.
# For purposes of this is makes the handle_lti_request function handle all POST requests which are directed at LTI_LISTEN_LOCATION
router.on(LTI_LISTEN_LOCATION, "POST", handle_lti_request)
Architecture
------------
This module is fairly straightforward, it forwards any LTI request to a
secure endpoint which contains a record of the ``oauth_consumer_key``
and the ``secret_key``. This remote endpoint then validates the request,
and returns a simple response indicating its validity.
``DataRequester`` This class exposes a ``post`` method which takes the
CELTIC service endpoint, and the POST data to send it. It returns the
CELTIC response wrapped in the following interface:
::
* status_code<int>
* json()<dict>
The primary reason of this class is to allow users to swap out the
default ``DataRequester`` for their own to provide better control over
the application
``LTIValidator`` A class which handles the plumbing of the LTI
validation. It is given a CELTIC service URI, an ``app_key``, and a
``DataRequester`` instance. The user then only needs to call the
``validate_request`` method with a forwarded LTI payload to determine
the validity of it.
``LTIValidatorException`` An exception thrown when the server returns a
not-good error code about the LTI response. The exception exposes the
following data:
::
* message<string> - The error message the CELTIC server responded with
* status_code<int> - The HTTP status code the CELTIC server responded with
* errors<dict> - The response body the CELTIC service responded with
Developing
----------
To make improvements to this package, the following is required:
::
* A python environment
* [pandoc](https://pandoc.org/installing.html) is used to convert this README.md into `reStructuredText`
1. First: pip install pypandoc
2. Second: Download installer from pandoc website
