chisel 0.9.112

Light-weight WSGI application framework, schema-validated JSON APIs, and API documentation.

Chisel is a light-weight Python WSGI application framework with tools for building well-documented, schema-validated JSON web APIs. Here are Chisel’s features at a glance:

• Light-weight WSGI application framework

• Schema-validated JSON web APIs

• Schema-accurate API documentation

• Written in pure Python

• Zero dependencies

• Python 3.7+

Links

• Documentation on GitHub Pages

• Package on pypi

• Source code on GitHub

• Build on Travis CI

• Coverage on Codecov

Overview

To create a Chisel application, first create an Application object. Add functionality to your application by adding request objects to using the application’s add_request method. A Request object is itself a WSGI application with metadata such as the HTTP request method and URL path at which to serve the request.

>>> from http import HTTPStatus
...
>>> @chisel.request(urls=[('GET', None)])
... def hello_world(environ, start_response):
...     ctx = environ[chisel.Context.ENVIRON_CTX]
...     return ctx.response_text(HTTPStatus.OK, 'Hello, World!')
...
>>> application = chisel.Application()
>>> application.add_request(hello_world)
>>> application.request('GET', '/hello_world')
('200 OK', [('Content-Type', 'text/plain')], b'Hello, World!')

Schema-Validated JSON APIs

Chisel provides a built-in Request sub-class for easily implementing schema-validated JSON APIs called “actions”. To define an, action use the action decorator to wrap an action callback function. For example:

>>> @chisel.action(spec='''
... # Sum a list of numbers
... action sum_numbers
...     urls
...        GET
...
...     query
...         # The list of numbers
...         float[len > 0] numbers
...
...     output
...         # The sum of the numbers
...         float sum
... ''')
... def sum_numbers(ctx, req):
...     return {'sum': sum(req['numbers'])}
...
>>> application = chisel.Application()
>>> application.add_request(sum_numbers)
>>> application.request('GET', '/sum_numbers', query_string='numbers.0=1&numbers.1=2&numbers.2=4')
('200 OK', [('Content-Type', 'application/json')], b'{"sum":7.0}')

Each action must define an action specification using the Chisel Specification Language. The easiest way to define the action specification is to provide the “spec” argument to the action decorator as above. The action callback is passed two arguments, a request Context and the schema-validated request input object. The input request object is created by combining the request’s URL path parameters, query string parameters, and input JSON content parameters.

In the example above, notice that the code does not check the input request object before using it. This is OK in a chisel action callback because the input request object is validated prior to calling the callback. If there is a schema validation error the appropriate error code is automatically returned.

>>> status, _, content_bytes = application.request('GET', '/sum_numbers')
>>> status
'400 Bad Request'

>>> content_bytes
b'{"error":"InvalidInput","message":"Required member \'numbers\' missing (query string)"}'

API Documentation

You can add API documentation by adding the Chisel documentation application to your application using create_doc_requests and add_requests.

>>> application = chisel.Application()
>>> application.add_requests(chisel.create_doc_requests())

By default the documentation application is hosted at “/doc/”. An example of of Chisel’s documentation output is available here.