chalice README

The project's README from github.com/aws/chalice. As one markdown file: README.md.

=========== AWS Chalice

.. image:: https://img.shields.io/pypi/v/chalice.svg?style=flat :target: https://pypi.python.org/pypi/chalice/ :alt: Package Version

.. image:: https://img.shields.io/pypi/pyversions/chalice.svg?style=flat :target: https://pypi.python.org/pypi/chalice/ :alt: Python Versions

.. image:: https://readthedocs.org/projects/chalice/badge/?version=latest :target: https://aws.github.io/chalice/?badge=latest :alt: Documentation Status

.. image:: https://img.shields.io/pypi/l/chalice.svg?style=flat :target: https://github.com/aws/chalice/blob/master/LICENSE :alt: License

.. image:: https://aws.github.io/chalice/_static/img/chalice-logo-whitespace.png :target: https://aws.github.io/chalice/ :alt: Chalice Logo

Chalice is a framework for writing serverless apps in Python. It allows you to quickly create and deploy applications that use AWS Lambda. It provides:

You can create Rest APIs:

.. code-block:: python

from chalice import Chalice

app = Chalice(app_name="helloworld")

@app.route("/")
def index():
    return {"hello": "world"}

Tasks that run on a periodic basis:

.. code-block:: python

from chalice import Chalice, Rate

app = Chalice(app_name="helloworld")

# Automatically runs every 5 minutes
@app.schedule(Rate(5, unit=Rate.MINUTES))
def periodic_task(event):
    return {"hello": "world"}

You can connect a lambda function to an S3 event:

.. code-block:: python

from chalice import Chalice

app = Chalice(app_name="helloworld")

# Whenever an object is uploaded to "mybucket"
# this lambda function will be invoked.

@app.on_s3_event(bucket="mybucket")
def handler(event):
    print(
        f"Object uploaded for bucket: {event.bucket}, key: {event.key}"
    )

As well as an SQS queue:

.. code-block:: python

from chalice import Chalice

app = Chalice(app_name="helloworld")

# Invoke this lambda function whenever a message
# is sent to the ``my-queue-name`` SQS queue.

@app.on_sqs_message(queue="my-queue-name")
def handler(event):
    for record in event:
        print(f"Message body: {record.body}")

And several other AWS resources.

Once you've written your code, you just run chalice deploy and Chalice takes care of deploying your app.

::

$ chalice deploy
...
https://endpoint/api

$ curl https://endpoint/api
{"hello": "world"}

Up and running in less than 30 seconds. Give this project a try and share your feedback with us here on GitHub.

The documentation is available here <https://aws.github.io/chalice/>__.

Quickstart

.. quick-start-begin

In this tutorial, you'll use the chalice command line utility to create and deploy a basic REST API. This quickstart uses Python 3.10, but AWS Chalice supports all versions of Python supported by AWS Lambda, which includes Python 3.10 through Python 3.14.

To install Chalice, we'll first create and activate a virtual environment in python3.10::

$ python3 --version
Python 3.10.20
$ python3 -m venv .venv
$ . .venv/bin/activate

Next we'll install Chalice using pip::

$ python3 -m pip install chalice

You can verify you have chalice installed by running::

$ chalice --help
Usage: chalice [OPTIONS] COMMAND [ARGS]...
...

Credentials

Before you can deploy an application, be sure you have credentials configured. If you have previously configured your machine to run boto3 (the AWS SDK for Python) or the AWS CLI then you can skip this section.

If this is your first time configuring credentials for AWS you can follow these steps to quickly get started::

$ mkdir ~/.aws
$ cat >> ~/.aws/config
[default]
aws_access_key_id=YOUR_ACCESS_KEY_HERE
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY
region=YOUR_REGION (such as us-west-2, us-west-1, etc)

If you want more information on all the supported methods for configuring credentials, see the boto3 docs <https://docs.aws.amazon.com/boto3/latest/guide/configuration.html>__.

Creating Your Project

The next thing we'll do is use the chalice command to create a new project::

$ chalice new-project helloworld

This will create a helloworld directory. Cd into this directory. You'll see several files have been created for you::

$ cd helloworld
$ ls -la
drwxr-xr-x   .chalice
-rw-r--r--   app.py
-rw-r--r--   requirements.txt

You can ignore the .chalice directory for now, the two main files we'll focus on is app.py and requirements.txt.

Let's take a look at the app.py file:

.. code-block:: python

from chalice import Chalice

app = Chalice(app_name='helloworld')


@app.route('/')
def index():
    return {'hello': 'world'}

The new-project command created a sample app that defines a single view, /, that when called will return the JSON body {"hello": "world"}.

Deploying

Let's deploy this app. Make sure you're in the helloworld directory and run chalice deploy::

$ chalice deploy
Creating deployment package.
Creating IAM role: helloworld-dev
Creating lambda function: helloworld-dev
Creating Rest API
Resources deployed:
  - Lambda ARN: arn:aws:lambda:us-west-2:123456789012:function:helloworld-dev
  - Rest API URL: https://abcd.execute-api.us-west-2.amazonaws.com/api/

You now have an API up and running using API Gateway and Lambda::

$ curl https://abcd.execute-api.us-west-2.amazonaws.com/api/
{"hello": "world"}

Try making a change to the returned dictionary from the index() function. You can then redeploy your changes by running chalice deploy.

.. quick-start-end

Next Steps

You've now created your first app using chalice. You can make modifications to your app.py file and rerun chalice deploy to redeploy your changes.

At this point, there are several next steps you can take.

If you're done experimenting with Chalice and you'd like to cleanup, you can use the chalice delete command, and Chalice will delete all the resources it created when running the chalice deploy command.

::

$ chalice delete
Deleting Rest API: abcd4kwyl4
Deleting function arn:aws:lambda:region:123456789012:function:helloworld-dev
Deleting IAM Role helloworld-dev

Feedback

We'd also love to hear from you. Please create any GitHub issues for additional features you'd like to see over at https://github.com/aws/chalice/issues.

chalice (aws/chalice)

aws-lambda
Searching Database…

11.1K ·GitHub
Chalice
What is this?Chalice is a Python framework for writing serverless apps: you write ordinary Python functions, and it creates and deploys the AWS Lambda functions and REST APIs behind them.
Is it a framework or a command-line tool?Both: it ships a decorator-based Python framework for wiring functions up to AWS services, plus the chalice command line tool that creates, deploys, and manages your app.
How do I get a first app deployed?Set your AWS credentials, run chalice new-project myapp to scaffold a project, edit the generated app.py, then run chalice deploy — the README says you can be up and running in less than 30 seconds.
What do I need in place before I can try it?An AWS account with credentials (access key, secret key, region) configured in ~/.aws/config, the same setup boto3 uses. Other than Python itself, nothing extra is required to start.
Is it locked to AWS?It is tied to AWS: everything Chalice builds — Lambda functions, API Gateway routes, S3, SNS and SQS integrations — lives in your AWS account, not on other clouds or your own servers.
What does a minimal Chalice app look like?A few lines of Python: create a Chalice app object and decorate a function with @app.route('/'). Whatever dict that function returns becomes the JSON response served through API Gateway.
Besides HTTP endpoints, what can trigger a function?Scheduled jobs via @app.schedule (Rate(5, unit=Rate.MINUTES) fires every 5 minutes), S3 uploads via @app.ons3event(bucket=...), and SQS messages via @app.onsqsmessage(queue=...), plus other AWS resources.
Do I have to write IAM policies for my functions myself?No. Chalice generates IAM policies automatically from what your app does, so you do not hand-maintain role documents.
What does chalice deploy actually create, and how do I undo it?It packages your code, creates an IAM role and a Lambda function, and sets up the REST API, printing their ARNs and the public API URL. chalice delete later removes every resource deploy created.
What are similar projects?Zappa, examples, serverless, awesome-aws, encore, apisix, kubespray, faas
Which topics is it in?faas, aws-lambda, lambda, iam, api-gateway, python3, serverless, infrastructure, aws, deployment, cloud-native, microservices
Creator
aws
Size
9.1 MB
Stars
11.1K
Updated
CommitOct 15
Age
10y
Commits · 90 Days