celtic_lib 0.0.7
A python library for wrapping around the CELTIC service
License: MIT License

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