JSON APIs

action decorator

@chisel.action(action_callback=None, **kwargs)

Decorator for creating an Action object that wraps an action callback function. For example:

>>> @chisel.action(spec='''
... # Sum a list of numbers
... action sum_numbers
...     urls
...         GET
...     query
...         # The list of numbers to sum
...         int[len > 0] numbers
...     output
...         # The sum of the numbers
...         int 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=3')
('200 OK', [('Content-Type', 'application/json')], b'{"sum":6}')

Chisel actions schema-validate their input before calling the callback function. For example:

>>> status, _, response = application.request('GET', '/sum_numbers', query_string='numbers=1')
>>> status
'400 Bad Request'

>>> import json
>>> from pprint import pprint
>>> pprint(json.loads(response.decode('utf-8')))
{'error': 'InvalidInput',
 'member': 'numbers',
 'message': 'Invalid value "1" (type "str") for member "numbers", expected '
            'type "array" (query string)'}

When validate_output is True, the response dictionary is also validated against the output schema.

Parameters:

action_callback (Callable) – The action callback function

Action

class chisel.Action(action_callback, name=None, urls=(('POST', None),), types=None, spec=None, wsgi_response=False)

Bases: Request

A schema-validated, JSON API request. An Action wraps a callback function that it calls when a request occurs. Here’s an example of an action callback function:

>>> def my_action(ctx, req):
...    return {}

The first argument, “ctx”, is the Context object. The second argument is the request object which contains the schema-validated, combined path parameters, query string parameters, and JSON request content parameters.

Parameters:

• action_callback (Callable) – The action callback function

• name (str) – The action request name

• urls (list(tuple)) – The list of URL method/path tuples. The first value is the HTTP request method (e.g. ‘GET’) or None to match any. The second value is the URL path or None to use the default path. If the action’s specification contains a “urls” section, the specification’s URLs take precedence.

• types (dict) – Optional dictionary of user type models

• spec (str) – Optional action Schema Markdown specification. If a specification isn’t provided it can be provided through the “types” argument.

• wsgi_response (bool) – If True, the callback function’s response is a WSGI application function response. Default is False.

action_callback

The action callback function

property model

Get the action model

types

The user type model dictionary that contains the action model and all referenced user types

wsgi_response

If True, the callback function’s response is a WSGI application function response.

ActionError

exception chisel.ActionError(error, message=None, status=None)

An action error exception. Raise this exception within an action callback function to respond with an error.

>>> @chisel.action(spec='''
... action my_action
...     urls
...         GET
...     errors
...         AlwaysError
... ''')
... def my_action(ctx, req):
...    raise chisel.ActionError('AlwaysError')
...
>>> application = chisel.Application()
>>> application.add_request(my_action)
>>> application.request('GET', '/my_action')
('400 Bad Request', [('Content-Type', 'application/json')], b'{"error":"AlwaysError"}')

Parameters:

• error (str) – The error code

• message (str) – Optional error message

• status (HTTPStatus or str) – The HTTP response status

error

The error code

message

The error message or None

status

The HTTP response status