Chalice

class Chalice(app_name)

This class represents a chalice application. It provides:

  • The ability to register routes using the route() method.
  • Within a view function, the ability to introspect the current request using the current_request attribute which is an instance of the Request class.
current_request

An object of type Request. This value is only set when a view function is being called. This attribute can be used to introspect the current HTTP request.

api

An object of type APIGateway. This attribute can be used to control how apigateway interprets Content-Type headers in both requests and responses.

debug

A boolean value that enables debugging. By default, this value is False. If debugging is true, then internal errors are returned back to the client. Additionally, debug log messages generated by the framework will show up in the cloudwatch logs. Example usage:

from chalice import Chalice

app = Chalice(app_name="appname")
app.debug = True
route(path, **options)

Register a view function for a particular URI path. This method is intended to be used as a decorator for a view function. For example:

from chalice import Chalice

app = Chalice(app_name="appname")

@app.route('/resource/{value}', methods=['PUT'])
def viewfunction(value):
    pass
Parameters
  • path (str) -- The path to associate with the view function. The path should only contain [a-zA-Z0-9._-] chars and curly braces for parts of the URL you would like to capture. The path should not end in a trailing slash, otherwise a validation error will be raised during deployment.
  • methods (list) -- Optional parameter that indicates which HTTP methods this view function should accept. By default, only GET requests are supported. If you only wanted to support POST requests, you would specify methods=['POST']. If you support multiple HTTP methods in a single view function (methods=['GET', 'POST']), you can check the app.current_request.method attribute to see which HTTP method was used when making the request.
  • name (str) -- Optional parameter to specify the name of the view function. You generally do not need to set this value. The name of the view function is used as the default value for the view name.
  • authorizer (Authorizer) -- Specify an authorizer to use for this view. Can be an instance of CognitoUserPoolAuthorizer, CustomAuthorizer or IAMAuthorizer.
  • content_types (str) -- A list of content types to accept for this view. By default application/json is accepted. If this value is specified, then chalice will reject any incoming request that does not match the provided list of content types with a 415 Unsupported Media Type response.
  • api_key_required (boolean) -- Optional parameter to specify whether the method required a valid API key.
  • cors -- Specify if CORS is supported for this view. This can either by a boolean value or an instance of CORSConfig. Setting this value is set to True gives similar behavior to enabling CORS in the AWS Console. This includes injecting the Access-Control-Allow-Origin header to have a value of * as well as adding an OPTIONS method to support preflighting requests. If you would like more control over how CORS is configured, you can provide an instance of CORSConfig.
authorizer(name, **options)

Register a built-in authorizer.

from chalice import Chalice, AuthResponse

app = Chalice(app_name="appname")

@app.authorizer(ttl_seconds=30)
def my_auth(auth_request):
    # Validate auth_request.token, and then:
    return AuthResponse(routes=['/'], principal_id='username')

@app.route('/', authorizer=my_auth)
def viewfunction(value):
    pass
Parameters
  • ttl_seconds -- The number of seconds to cache this response. Subsequent requests that require this authorizer will use a cached response if available. The default is 300 seconds.
  • execution_role -- An optional IAM role to specify when invoking the Lambda function associated with the built-in authorizer.

Request

class Request

A class that represents the current request. This is mapped to the app.current_request object.

@app.route('/objects/{key}', methods=['GET', 'PUT'])
def myobject(key):
    request = app.current_request
    if request.method == 'PUT':
        # handle PUT request
        pass
    elif request.method == 'GET':
        # handle GET request
        pass
query_params

A dict of the query params for the request.

headers

A dict of the request headers.

uri_params

A dict of the captured URI params.

method

The HTTP method as a string.

json_body

The parsed JSON body (json.loads(raw_body)). This value will only be non-None if the Content-Type header is application/json, which is the default content type value in chalice.

raw_body

The raw HTTP body as bytes. This is useful if you need to calculate a checksum of the HTTP body.

context

A dict of additional context information.

stage_vars

A dict of configuration for the API Gateway stage.

to_dict()

Convert the Request object to a dictionary. This is useful for debugging purposes. This dictionary is guaranteed to be JSON serializable so you can return this value from a chalice view.

Response

class Response(body, headers=None, status_code=200)

A class that represents the response for the view function. You can optionally return an instance of this class from a view function if you want complete control over the returned HTTP response.

from chalice import Chalice, Response

app = Chalice(app_name='custom-response')


@app.route('/')
def index():
    return Response(body='hello world!',
                    status_code=200,
                    headers={'Content-Type': 'text/plain'})

New in version 0.6.0.

body

The HTTP response body to send back. This value must be a string.

headers

An optional dictionary of HTTP headers to send back. This is a dictionary of header name to header value, e.g {'Content-Type': 'text/plain'}

status_code

The integer HTTP status code to send back in the HTTP response.

Authorization

Each of these classes below can be provided using the authorizer argument for an @app.route(authorizer=...) call:

authorizer = CognitoUserPoolAuthorizer(
    'MyPool', header='Authorization',
    provider_arns=['arn:aws:cognito:...:userpool/name'])

@app.route('/user-pools', methods=['GET'], authorizer=authorizer)
def authenticated():
    return {"secure": True}
class CognitoUserPoolAuthorizer(name, provider_arns, header='Authorization')

New in version 0.8.1.

name

The name of the authorizer.

provider_arns

The Cognito User Pool arns to use.

header

The header where the auth token will be specified.

class IAMAuthorizer

New in version 0.8.3.

class CustomAuthorizer(name, authorizer_uri, ttl_seconds, header='Authorization')

New in version 0.8.1.

name

The name of the authorizer.

authorizer_uri

The URI of the lambda function to use for the custom authorizer. This usually has the form arn:aws:apigateway:{region}:lambda:path/2015-03-01/functions/{lambda_arn}/invocations.

ttl_seconds

The number of seconds to cache the returned policy from a custom authorizer.

header

The header where the auth token will be specified.

Built-in Authorizers

These classes are used when defining built-in authoriers in Chalice.

class AuthRequest(auth_type, token, method_arn)

An instance of this class is passed as the first argument to an authorizer defined via @app.authorizer(). You generally do not instantiate this class directly.

auth_type

The type of authentication

token

The authorization token. This is usually the value of the Authorization header.

method_arn

The ARN of the API gateway being authorized.

class AuthResponse(routes, principal_id, context=None)
routes

A list of authorized routes. Each element in the list can either by a string route such as "/foo/bar" or an instance of AuthRoute. If you specify the URL as a string, then all supported HTTP methods will be authorized. If you want to specify which HTTP methods are allowed, you can use AuthRoute.

principal_id

The principal id of the user.

context

An optional dictionary of key value pairs. This dictionary will be accessible in the app.current_request.context in all subsequent authorized requests for this user.

class AuthRoute(path, methods)

This class be used in the routes attribute of a AuthResponse instance to get fine grained control over which HTTP methods are allowed for a given route.

path

The allowed route specified as a string

methods

A list of allowed HTTP methods.

APIGateway

class APIGateway

This class is used to control how API Gateway interprets Content-Type headers in both requests and responses.

There is a single instance of this class attached to each Chalice object under the api attribute.

default_binary_types

The value of default_binary_types are the Content-Types that are considered binary by default. This value should not be changed, instead you should modify the binary_types list to change the behavior of a content type. Its value is: application/octet-stream, application/x-tar, application/zip, audio/basic, audio/ogg, audio/mp4, audio/mpeg, audio/wav, audio/webm, image/png, image/jpg, image/gif, video/ogg, video/mpeg, video/webm.

binary_types

The value of binary_types controls how API Gateway interprets requests and responses as detailed below.

If an incoming request has a Content-Type header value that is present in the binary_types list it will be assumed that its body is a sequence of raw bytes. You can access these bytes by accessing the app.current_request.raw_body property.

If an outgoing response from Chalice has a header Content-Type that matches one of the binary_types its body must be a bytes type object. It is important to note that originating request must have the Accept header for the same type as the Content-Type on the response. Otherwise a 400 error will be returned.

Implementation note: API Gateway and Lambda communicate through a JSON event which is encoded using UTF-8. The raw bytes are temporarily encoded using

base64 when being passed between API Gateway and Labmda. In the worst case this encoding can cause the binary body to be inflated up to 4/3 its original size. Lambda only accepts an event up to 6mb, which means even if your binary data was not quite at that limit, with the base64 encoding it may exceed that limit. This will manifest as a 502 Bad Gateway error.

CORS

class CORSConfig(allow_origin='*', allow_headers=None, expose_headers=None, max_age=None, allow_credentials=None)

CORS configuration to attach to a route.

from chalice import CORSConfig
cors_config = CORSConfig(
    allow_origin='https://foo.example.com',
    allow_headers=['X-Special-Header'],
    max_age=600,
    expose_headers=['X-Special-Header'],
    allow_credentials=True
)

@app.route('/custom_cors', methods=['GET'], cors=cors_config)
def supports_custom_cors():
    return {'cors': True}

New in version 0.8.1.

allow_origin

The value of the Access-Control-Allow-Origin to send in the response. Keep in mind that even though the Access-Control-Allow-Origin header can be set to a string that is a space separated list of origins, this behavior does not work on all clients that implement CORS. You should only supply a single origin to the CORSConfig object. If you need to supply multiple origins you will need to define a custom handler for it that accepts OPTIONS requests and matches the Origin header against a whitelist of origins. If the match is succssful then return just their Origin back to them in the Access-Control-Allow-Origin header.

allow_headers

The list of additional allowed headers. This list is added to list of built in allowed headers: Content-Type, X-Amz-Date, Authorization, X-Api-Key, X-Amz-Security-Token.

expose_headers

A list of values to return for the Access-Control-Expose-Headers:

max_age

The value for the Access-Control-Max-Age

allow_credentials

A boolean value that sets the value of Access-Control-Allow-Credentials.