Repository files navigation

Falcon is a reliable,high-performance Python web framework for buildinglarge-scale app backends and microservices. It encourages the RESTarchitectural style, and tries to do as little as possible whileremaining highly effective.

Falcon apps work with any WSGI server, and run like a champ underCPython 2.7, CPython 3.4+, PyPy2.7, and PyPy3.5.

Has Falcon helped you make an awesome app? Show your support today with a one-time donation or by becoming a corporatesponsor. Backers get cool gear, an opportunity to promote their brand to Python developers, andprioritized support.

Learn how to support Falcon development

• Read the docs
• Falcon add-ons and complementary packages
• Falcon talks, podcasts, and blog posts
• falconry/user for Falcon users @ Gitter
• falconry/dev for Falcon contributors @ Gitter

"We have been using Falcon as a replacement for [framework] and we simply love the performance (three times faster) and code base size (easily half of our original [framework] code)."

"Falcon looks great so far. I hacked together a quick test for atiny server of mine and was ~40% faster with only 20 minutes ofwork."

"Falcon is rock solid and it's fast."

"I'm loving #falconframework! Super clean and simple, I finallyhave the speed and flexibility I need!"

"I feel like I'm just talking HTTP at last, with nothing in themiddle. Falcon seems like the requests of backend."

"The source code for Falcon is so good, I almost prefer it todocumentation. It basically can't be wrong."

"What other framework has integrated support for 786 TRY IT NOW ?"

Perfection is finally attained not when there is no longer anythingto add, but when there is no longer anything to take away.

- Antoine de Saint-Exupéry

We designed Falcon to support the demanding needs of large-scalemicroservices and responsive app backends. Falcon complements moregeneral Python web frameworks by providing bare-metal performance,reliability, and flexibility wherever you need it.

Fast. Same hardware, more requests. Falcon turns aroundrequests several times faster than most other Python frameworks. Foran extra speed boost, Falcon compiles itself with Cython whenavailable, and also works well withPyPy.Considering a move to another programming language? Benchmark withFalcon + PyPy first.

Reliable. We go to great lengths to avoid introducingbreaking changes, and when we do they are fully documented and onlyintroduced (in the spirit ofSemVer) with a major versionincrement. The code is rigorously tested with numerous inputs and werequire 100% coverage at all times. Six and mimeparse are the onlythird-party dependencies.

Flexible. Falcon leaves a lot of decisions and implementationdetails to you, the API developer. This gives you a lot of freedom tocustomize and tune your implementation. Due to Falcon's minimalistdesign, Python community members are free to independently innovate onFalcon add-ons and complementary packages.

Debuggable. Falcon eschews magic. It's easy to tell which inputslead to which outputs. Unhandled exceptions are never encapsulated ormasked. Potentially surprising behaviors, such as automatic request bodyparsing, are well-documented and disabled by default. Finally, when itcomes to the framework itself, we take care to keep logic paths simpleand understandable. All this makes it easier to reason about the codeand to debug edge cases in large-scale deployments.

• Highly-optimized, extensible code base
• Intuitive routing via URI templates and REST-inspired resourceclasses
• Easy access to headers and bodies through request and responseclasses
• DRY request processing via middleware components and hooks
• Idiomatic HTTP error responses
• Straightforward exception handling
• Snappy unit testing through WSGI helpers and mocks
• CPython 2.7, CPython 3.4+, PyPy2.7, and PyPy3.5 support
• ~20% speed boost under CPython when Cython is available

Falcon is used around the world by a growing number of organizations,including:

• 7ideas
• Cronitor
• EMC
• Hurricane Electric
• Leadpages
• OpenStack
• Rackspace
• Shiftgig
• tempfil.es
• Opera Software

If you are using the Falcon framework for a community or commercialproject, please consider adding your information to our wiki underWho's Using Falcon?

A number of Falcon add-ons, templates, and complementary packages areavailable for use in your projects. We've listed several of these on theFalcon wiki as a startingpoint, but you may also wish to search PyPI for additional resources.

The Falconry community on Gitter is a great place to ask questions andshare your ideas. You can find us infalconry/user. We also have afalconry/dev room for discussingthe design and development of the framework itself.

Per ourCode of Conduct,we expect everyone who participates in community discussions to actprofessionally, and lead by example in encouraging constructivediscussions. Each individual in the community is responsible forcreating a positive, constructive, and productive culture.

PyPy is the fastest way to run your Falcon app.Both PyPy2.7 and PyPy3.5 are supported as of PyPy v5.10.

$ pip install falcon

Or, to install the latest beta or release candidate, if any:

$ pip install --pre falcon

Falcon also fully supportsCPython 2.7 and 3.4+.

A universal wheel is available on PyPI for the the Falcon framework.Installing it is as simple as:

$ pip install falcon

Ifujson is available, Falconwill use it to speed up media (de)serialization, error serialization,and query string parsing. Note thatujson can actually be sloweron PyPy than the standardjson module due to ctypes overhead, andso we recommend only usingujson with CPython deployments:

$ pip install ujson

Installing the Falcon wheel is a great way to get up and runningquickly in a development environment, but for an extra speed boost whendeploying your application in production, Falcon can compile itself withCython.

The following commands tell pip to install Cython, and then to invokeFalcon'ssetup.py, which will in turn detect the presence of Cythonand then compile (AKA cythonize) the Falcon framework with the system'sdefault C compiler.

$ pip install cython$ pip install --no-binary :all: falcon

If you want to verify that Cython is being invoked, simplypass -v to pip in order to echo the compilation commands:

$ pip install -v --no-binary :all: falcon

Installing on OS X

Xcode Command Line Tools are required to compile Cython. Install themwith this command:

$ xcode-select --install

The Clang compiler treats unrecognized command-line options aserrors, for example:

clang: error: unknown argument:'-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]

You might also see warnings about unused functions. You can work aroundthese issues by setting additional Clang C compiler flags as follows:

$export CFLAGS="-Qunused-arguments -Wno-unused-function"

Falcon depends on six and python-mimeparse. python-mimeparse is abetter-maintained fork of the similarly named mimeparse project.Normally the correct package will be selected by Falcon'ssetup.py.However, if you are using an alternate strategy to manage dependencies,please take care to install the correct package in order to avoiderrors.

Falcon speaks WSGI, and so in order to serve a Falcon app, you willneed a WSGI server. Gunicorn and uWSGI are some of the more popularones out there, but anything that can load a WSGI app will do.

$ pip install [gunicorn|uwsgi]

Falconlives on GitHub, making thecode easy to browse, download, fork, etc. Pull requests are always welcome! Also,please remember to star the project if it makes you happy. :)

Once you have cloned the repo or downloaded a tarball from GitHub, youcan install Falcon like this:

$cd falcon$ pip install.

Or, if you want to edit the code, first fork the main repo, clone the forkto your desktop, and then run the following to install it using symboliclinking, so that when you change your code, the changes will be automagicallyavailable to your app without having to reinstall the package:

$cd falcon$ pip install -e.

You can manually test changes to the Falcon framework by switching to thedirectory of the cloned repo and then running pytest:

$cd falcon$ pip install -r requirements/tests$ pytest tests

Or, to run the default set of tests:

$ pip install tox&& tox

See also thetox.inifile for a full list of available environments.

The docstrings in the Falcon code base are quite extensive, and werecommend keeping a REPL running while learning the framework so thatyou can query the various modules and classes as you have questions.

Online docs are available at:https://falcon.readthedocs.io

You can build the same docs locally as follows:

$ pip install tox&& tox -e docs

Once the docs have been built, you can view them by opening the followingindex page in your browser. On OS X it's as simple as:

$ open docs/_build/html/index.html

Or on Linux:

$ xdg-open docs/_build/html/index.html

Here is a simple, contrived example showing how to create a Falcon-basedAPI.

# things.py# Let's get this party started!importfalcon# 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.classThingsResource(object):defon_get(self,req,resp):"""Handles GET requests"""resp.status=falcon.HTTP_200# This is the default statusresp.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 appsapp=falcon.API()# Resources are represented by long-lived class instancesthings=ThingsResource()# things will handle all requests to the '/things' URL pathapp.add_route('/things',things)

You can run the above example using any WSGI server, such as uWSGI orGunicorn. For example:

$ pip install gunicorn$ gunicorn things:app

Then, in another terminal:

$ curl localhost:8000/things

Here is a more involved example that demonstrates reading headers andquery parameters, handling errors, and working with request and responsebodies.

importjsonimportloggingimportuuidfromwsgirefimportsimple_serverimportfalconimportrequestsclassStorageEngine(object):defget_things(self,marker,limit):return [{'id':str(uuid.uuid4()),'color':'green'}]defadd_thing(self,thing):thing['id']=str(uuid.uuid4())returnthingclassStorageError(Exception):@staticmethoddefhandle(ex,req,resp,params):description= ('Sorry, couldn\'t write your thing to the ''database. It worked on my box.')raisefalcon.HTTPError(falcon.HTTP_725,'Database Error',description)classSinkAdapter(object):engines= {'ddg':'https://duckduckgo.com','y':'https://search.yahoo.com/search',    }def__call__(self,req,resp,engine):url=self.engines[engine]params= {'q':req.get_param('q',True)}result=requests.get(url,params=params)resp.status=str(result.status_code)+' '+result.reasonresp.content_type=result.headers['content-type']resp.body=result.textclassAuthMiddleware(object):defprocess_request(self,req,resp):token=req.get_header('Authorization')account_id=req.get_header('Account-ID')challenges= ['Token type="Fernet"']iftokenisNone:description= ('Please provide an auth token ''as part of the request.')raisefalcon.HTTPUnauthorized('Auth token required',description,challenges,href='http://docs.example.com/auth')ifnotself._token_is_valid(token,account_id):description= ('The provided auth token is not valid. ''Please request a new token and try again.')raisefalcon.HTTPUnauthorized('Authentication required',description,challenges,href='http://docs.example.com/auth')def_token_is_valid(self,token,account_id):returnTrue# Suuuuuure it's valid...classRequireJSON(object):defprocess_request(self,req,resp):ifnotreq.client_accepts_json:raisefalcon.HTTPNotAcceptable('This API only supports responses encoded as JSON.',href='http://docs.examples.com/api/json')ifreq.methodin ('POST','PUT'):if'application/json'notinreq.content_type:raisefalcon.HTTPUnsupportedMediaType('This API only supports requests encoded as JSON.',href='http://docs.examples.com/api/json')classJSONTranslator(object):# NOTE: Starting with Falcon 1.3, you can simply# use req.media and resp.media for this instead.defprocess_request(self,req,resp):# req.stream corresponds to the WSGI wsgi.input environ variable,# and allows you to read bytes from the request body.## See also: PEP 3333ifreq.content_lengthin (None,0):# Nothing to doreturnbody=req.stream.read()ifnotbody:raisefalcon.HTTPBadRequest('Empty request body','A valid JSON document is required.')try:req.context['doc']=json.loads(body.decode('utf-8'))except (ValueError,UnicodeDecodeError):raisefalcon.HTTPError(falcon.HTTP_753,'Malformed JSON','Could not decode the request body. The ''JSON was incorrect or not encoded as ''UTF-8.')defprocess_response(self,req,resp,resource):if'result'notinresp.context:returnresp.body=json.dumps(resp.context['result'])defmax_body(limit):defhook(req,resp,resource,params):length=req.content_lengthiflengthisnotNoneandlength>limit:msg= ('The size of the request is too large. The body must not ''exceed '+str(limit)+' bytes in length.')raisefalcon.HTTPRequestEntityTooLarge('Request body is too large',msg)returnhookclassThingsResource(object):def__init__(self,db):self.db=dbself.logger=logging.getLogger('thingsapp.'+__name__)defon_get(self,req,resp,user_id):marker=req.get_param('marker')or''limit=req.get_param_as_int('limit')or50try:result=self.db.get_things(marker,limit)exceptExceptionasex:self.logger.error(ex)description= ('Aliens have attacked our base! We will ''be back as soon as we fight them off. ''We appreciate your patience.')raisefalcon.HTTPServiceUnavailable('Service Outage',description,30)# An alternative way of doing DRY serialization would be to# create a custom class that inherits from falcon.Request. This# class could, for example, have an additional 'doc' property# that would serialize to JSON under the covers.## NOTE: Starting with Falcon 1.3, you can simply# use resp.media for this instead.resp.context['result']=resultresp.set_header('Powered-By','Falcon')resp.status=falcon.HTTP_200@falcon.before(max_body(64*1024))defon_post(self,req,resp,user_id):try:# NOTE: Starting with Falcon 1.3, you can simply# use req.media for this instead.doc=req.context['doc']exceptKeyError:raisefalcon.HTTPBadRequest('Missing thing','A thing must be submitted in the request body.')proper_thing=self.db.add_thing(doc)resp.status=falcon.HTTP_201resp.location='/%s/things/%s'% (user_id,proper_thing['id'])# Configure your WSGI server to load "things.app" (app is a WSGI callable)app=falcon.API(middleware=[AuthMiddleware(),RequireJSON(),JSONTranslator(),])db=StorageEngine()things=ThingsResource(db)app.add_route('/{user_id}/things',things)# If a responder ever raised an instance of StorageError, pass control to# the given handler.app.add_error_handler(StorageError,StorageError.handle)# Proxy some things to another service; this example shows how you might# send parts of an API off to a legacy system that hasn't been upgraded# yet, or perhaps is a single cluster that all data centers have to share.sink=SinkAdapter()app.add_sink(sink,r'/search/(?P<engine>ddg|y)\Z')# Useful for debugging problems in your API; works with pdb.set_trace(). You# can also use Gunicorn to host your app. Gunicorn can be configured to# auto-restart workers when it detects a code change, and it also works# with pdb.if__name__=='__main__':httpd=simple_server.make_server('127.0.0.1',8000,app)httpd.serve_forever()

Thanks for your interest in the project! We welcome pull requests fromdevelopers of all skill levels. To get started, simply fork the master branchon GitHub to your personal account and then clone the fork into yourdevelopment environment.

If you would like to contribute but don't already have something in mind,we invite you to take a look at the issues listed under ournext milestone.If you see one you'd like to work on, please leave a quick comment so that we don'tend up with duplicated effort. Thanks in advance!

Please note that all contributors and maintainers of this project are subject to ourCode of Conduct.

Before submitting a pull request, please ensure you have added/updatedthe appropriate tests (and that all existing tests still pass with yourchanges), and that your coding style follows PEP 8 and doesn't causepyflakes to complain.

Commit messages should be formatted usingAngularJSconventions.

Comments followGoogle's style guide,with the additional requirement of prefixing inline comments using yourGitHub nick and an appropriate prefix:

• TODO(riker): Damage report!
• NOTE(riker): Well, that's certainly good to know.
• PERF(riker): Travel time to the nearest starbase?
• APPSEC(riker): In all trust, there is the possibility for betrayal.

The core Falcon project maintainers are:

• Kurt Griffiths, Project Lead (kgriffs on GH, Gitter, and Twitter)
• John Vrbanac (jmvrbanac on GH and Gitter, andjvrbanac on Twitter)
• Vytautas Liuolia (vytas7 on GH and Gitter)
• Nick Zaccardi (nZac on GH and Gitter)

Please don't hesitate to reach out if you have any questions, or just need alittle help getting started. You can find us infalconry/dev on Gitter.

See also:CONTRIBUTING.md

Copyright 2013-2018 by Individual and corporate contributors asnoted in the individual source files.

Falcon image courtesy ofJohnO'Neill.

Licensed under the Apache License, Version 2.0 (the "License"); you maynot use any portion of the Falcon framework except in compliance withthe License. Contributors agree to license their work under the sameLicense. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.