Falcon is a high-performance Python framework for building cloud APIs. It encourages the REST architectural style, and tries to do as little as possible while remaining highly effective.
Light. Only the essentials are included, with six and mimeparse being the only dependencies outside the standard library. We work to keep the code lean, making Falcon easier to test, optimize, and deploy.
Flexible. Falcon can be deployed in a variety of ways, depending on your needs. The framework speaks WSGI, and works great with Python 2.6 and 2.7, PyPy, and Python 3.3/3.4. There's no tight coupling with any async framework, leaving you free to mix-and-match what you need.
Installing on OS X Mavericks with Xcode 5.1
Xcode Command Line Tools are required to compile Cython. Install them with this command:
The Xcode 5.1 CLang compiler treats unrecognized command-line options as
errors; this can cause problems under Python 2.6, for example:
You can work around errors caused by unused arguments by setting some
environment variables:
To test across all supported Python versions:
The docstrings in the Falcon code base are quite extensive, and we recommend keeping a REPL running while learning the framework so that you can query the various modules and classes as you have questions.
You can also check out Marconi's WSGI driver to get a feel for how you might leverage Falcon in a real-world app.
Finally, you can always ask questions in #falconframework on freenode. The community is very friendly and helpful.
Here is a simple, contrived example showing how to create a Falcon-based API.
You can run the above example using any WSGI server, such as uWSGI
or Gunicorn. For example:
Then, in another terminal:
Perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away.
- Antoine de Saint-Exupéry
Design Goals
Fast. Cloud APIs need to turn around requests quickly, and make efficient use of hardware. This is particularly important when serving many concurrent requests. Falcon processes requests several times faster than other popular web frameworks.Light. Only the essentials are included, with six and mimeparse being the only dependencies outside the standard library. We work to keep the code lean, making Falcon easier to test, optimize, and deploy.
Flexible. Falcon can be deployed in a variety of ways, depending on your needs. The framework speaks WSGI, and works great with Python 2.6 and 2.7, PyPy, and Python 3.3/3.4. There's no tight coupling with any async framework, leaving you free to mix-and-match what you need.
Features
- Intuitive routing via URI templates and resource classes
- Easy access to headers and bodies through request and response classes
- Idiomatic HTTP error responses via a handy exception base class
- DRY request processing using global, resource, and method hooks
- Snappy unit testing through WSGI helpers and mocks
- 20% speed boost when Cython is available
- Python 2.6, Python 2.7, PyPy and Python 3.3/3.4 support
- Speed, speed, and more speed!
Install
$ pip install cython falcon
Xcode Command Line Tools are required to compile Cython. Install them with this command:
$ xcode-select --install
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
$ export CFLAGS=-Qunused-arguments
$ export CPPFLAGS=-Qunused-arguments
$ pip install cython falcon
Test
$ pip install nose && nosetests
$ pip install tox && tox
Usage
We have started documenting the library at http://falcon.readthedocs.org and we would of course greatly appreciate pull requests to help accelerate that effort.The docstrings in the Falcon code base are quite extensive, and we recommend keeping a REPL running while learning the framework so that you can query the various modules and classes as you have questions.
You can also check out Marconi's WSGI driver to get a feel for how you might leverage Falcon in a real-world app.
Finally, you can always ask questions in #falconframework on freenode. The community is very friendly and helpful.
Here is a simple, contrived example showing how to create a Falcon-based API.
# things.py
# Let's get this party started
import falcon
# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
def on_get(self, req, resp):
"""Handles GET requests"""
resp.status = falcon.HTTP_200 # This is the default status
resp.body = ('\nTwo things awe me most, the starry sky '
'above me and the moral law within me.\n'
'\n'
' ~ Immanuel Kant\n\n')
# falcon.API instances are callable WSGI apps
app = falcon.API()
# Resources are represented by long-lived class instances
things = ThingsResource()
# things will handle all requests to the '/things' URL path
app.add_route('/things', things)
$ pip install gunicorn
$ gunicorn things:app
$ curl localhost:8000/things
from https://github.com/racker/falcon