- Notifications
You must be signed in to change notification settings - Fork953
The no-magic web API and microservices framework for Python developers, with an emphasis on reliability and performance at scale.
License
falconry/falcon
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Falcon is a minimalist ASGI/WSGI framework forbuilding mission-critical REST APIs and microservices, with a focus onreliability, correctness, and performance at scale.
When it comes to building HTTP APIs, other frameworks weigh you down with tonsof dependencies and unnecessary abstractions. Falcon cuts to the chase with aclean design that embraces HTTP and the REST architectural style.
Falcon apps work with anyWSGIorASGI server, and run like achamp under CPython 3.8+ and PyPy 3.8+.
- Read the docs(FAQ -getting help -reference)
- Falcon add-ons and complementary packages
- Falcon articles, talks and podcasts
- falconry/user for Falcon users @ Gitter
- falconry/dev for Falcon contributors @ Gitter
"Falcon is rock solid and it's fast."
"We have been using Falcon as a replacement for [another framework] andwe simply love the performance (three times faster) and code base size (easilyhalf of our [original] code)."
"I'm loving #falconframework! Super clean and simple, I finallyhave the speed and flexibility I need!"
"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."
"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 ?"
Falcon tries to do as little as possible while remaining highly effective.
- ASGI, WSGI, and WebSocket support
- Native
asynciosupport - No reliance on magic globals for routing and state management
- Stable interfaces with an emphasis on backwards-compatibility
- Simple API modeling through centralized RESTful routing
- Highly-optimized, extensible code base
- Easy access to headers and bodies through request and responseclasses
- DRY request processing via middleware components and hooks
- Strict adherence to RFCs
- Idiomatic HTTP error responses
- Straightforward exception handling
- Snappy testing with WSGI/ASGI helpers and mocks
- CPython 3.8+ and PyPy 3.8+ support
Has Falcon helped you make an awesome app? Show your support today with aone-time donation or by becoming a patron.Supporters get cool gear, an opportunity to promote their brand to Pythondevelopers, and prioritized support.
Thanks!
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.
Reliable. We go to great lengths to avoid introducing breaking changes, andwhen we do they are fully documented and only introduced (in the spirit ofSemVer) with a major version increment. The code isrigorously tested with numerous inputs and we require 100% coverage at alltimes. Falcon has no dependencies outside the standard library, helpingminimize your app's attack surface while avoiding transitive bugs and breakingchanges.
Debuggable. Falcon eschews magic. It's easy to tell which inputs lead towhich outputs. Unhandled exceptions are never encapsulated or masked.Potentially surprising behaviors, such as automatic request body parsing, arewell-documented and disabled by default. Finally, when it comes to theframework itself, we take care to keep logic paths simple and understandable.All this makes it easier to reason about the code and to debug edge cases inlarge-scale deployments.
Fast. Same hardware, more requests. Falcon turns around requestssignificantly faster than other popular Python frameworks like Django andFlask. For an extra speed boost, Falcon compiles itself with Cython whenavailable, and also works well withPyPy. Considering amove to another programming language? Benchmark with Falcon+PyPy first!
Flexible. Falcon leaves a lot of decisions and implementation details toyou, the API developer. This gives you a lot of freedom to customize and tuneyour implementation. It also helps you understand your apps at a deeper level,making them easier to tune, debug, and refactor over the long run. Falcon'sminimalist design provides space for Python community members to independentlyinnovate onFalcon add-ons and complementary packages.
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.PyPy3.8+ is supported as of PyPy v7.3.7+.
$ pip install falcon
Or, to install the latest beta or release candidate, if any:
$ pip install --pre falcon
Falcon also fully supportsCPython 3.8+.
The latest stable version of Falcon can be installed directly from PyPI:
$ pip install falcon
Or, to install the latest beta or release candidate, if any:
$ pip install --pre falcon
In order to provide an extra speed boost, Falcon automatically compiles itselfwithCython under anyPEP 517-compliant installer.
For your convenience, wheels containing pre-compiled binaries are availablefrom PyPI for the majority of common platforms. Even if a binary build for yourplatform of choice is not available,pip will pick a pure-Python wheel.You can also cythonize Falcon for your environment; see ourInstallation docsfor more information on this and other advanced options.
Falcon does not require the installation of any other packages.
Falcon speaksWSGI (orASGI; see also below). In order toserve a Falcon app, you will need a WSGI server. Gunicorn and uWSGI are some ofthe more popular ones out there, but anything that can load a WSGI app will do.
$ pip install [gunicorn|uwsgi]In order to serve a Falcon ASGI app, you will need an ASGI server. Uvicornis a popular choice:
$ pip install uvicorn
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$ FALCON_DISABLE_CYTHON=Y 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 testsOr, to run the default set of tests:
$ pip install tox&& toxSee 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 docsOnce 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-basedWSGI app (the ASGI version is included further down):
# examples/things.py# Let's get this party started!fromwsgiref.simple_serverimportmake_serverimportfalcon# 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:defon_get(self,req,resp):"""Handles GET requests"""resp.status=falcon.HTTP_200# This is the default statusresp.content_type=falcon.MEDIA_TEXT# Default is JSON, so overrideresp.text= ('\nTwo things awe me most, the starry sky ''above me and the moral law within me.\n''\n'' ~ Immanuel Kant\n\n')# falcon.App instances are callable WSGI apps...# in larger applications the app is created in a separate fileapp=falcon.App()# Resources are represented by long-lived class instancesthings=ThingsResource()# things will handle all requests to the '/things' URL pathapp.add_route('/things',things)if__name__=='__main__':withmake_server('',8000,app)ashttpd:print('Serving on port 8000...')# Serve until process is killedhttpd.serve_forever()
You can run the above example directly using the included wsgiref server:
$ pip install falcon$ python things.py
Then, in another terminal:
$ curl localhost:8000/things
The ASGI version of the example is similar:
# examples/things_asgi.pyimportfalconimportfalcon.asgi# 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:asyncdefon_get(self,req,resp):"""Handles GET requests"""resp.status=falcon.HTTP_200# This is the default statusresp.content_type=falcon.MEDIA_TEXT# Default is JSON, so overrideresp.text= ('\nTwo things awe me most, the starry sky ''above me and the moral law within me.\n''\n'' ~ Immanuel Kant\n\n')# falcon.asgi.App instances are callable ASGI apps...# in larger applications the app is created in a separate fileapp=falcon.asgi.App()# 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 ASGI version with uvicorn or any other ASGI server:
$ pip install falcon uvicorn$ uvicorn things_asgi:app
Here is a more involved example that demonstrates reading headers and queryparameters, handling errors, and working with request and response bodies.Note that this example assumes that therequests package has been installed.
(For the equivalent ASGI app, see:A More Complex Example (ASGI)).
# examples/things_advanced.pyimportjsonimportloggingimportuuidfromwsgirefimportsimple_serverimportfalconimportrequestsclassStorageEngine: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):# TODO: Log the error, clean up, etc. before raisingraisefalcon.HTTPInternalServerError()classSinkAdapter: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.text=result.textclassAuthMiddleware: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(title='Auth token required',description=description,challenges=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(title='Authentication required',description=description,challenges=challenges,href='http://docs.example.com/auth')def_token_is_valid(self,token,account_id):returnTrue# Suuuuuure it's valid...classRequireJSON:defprocess_request(self,req,resp):ifnotreq.client_accepts_json:raisefalcon.HTTPNotAcceptable(description='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(title='This API only supports requests encoded as JSON.',href='http://docs.examples.com/api/json')classJSONTranslator:# NOTE: Normally you would simply use req.media and resp.media for# this particular use case; this example serves only to illustrate# what is possible.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(title='Empty request body',description='A valid JSON document is required.')try:req.context.doc=json.loads(body.decode('utf-8'))except (ValueError,UnicodeDecodeError):description= ('Could not decode the request body. The ''JSON was incorrect or not encoded as ''UTF-8.')raisefalcon.HTTPBadRequest(title='Malformed JSON',description=description)defprocess_response(self,req,resp,resource,req_succeeded):ifnothasattr(resp.context,'result'):returnresp.text=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.HTTPContentTooLarge(title='Request body is too large',description=msg)returnhookclassThingsResource: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(title='Service Outage',description=description,retry_after=30)# NOTE: Normally you would use resp.media for this sort of thing;# this example serves only to demonstrate how the context can be# used to pass arbitrary values between middleware components,# hooks, and resources.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:doc=req.context.docexceptAttributeError:raisefalcon.HTTPBadRequest(title='Missing thing',description='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.App(middleware=[AuthMiddleware(),RequireJSON(),JSONTranslator(),])db=StorageEngine()things=ThingsResource(db)app.add_route('/{user_id}/things',things)# If a responder ever raises 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()
Again this code uses wsgiref, but you can also run the above example usingany WSGI server, such as uWSGI or Gunicorn. For example:
$ pip install requests gunicorn$ gunicorn things:app
On Windows you can run Gunicorn and uWSGI via WSL, or you might try Waitress:
$ pip install requests waitress$ waitress-serve --port=8000 things:app
To test this example, open another terminal and run:
$ http localhost:8000/1/things authorization:custom-token
You can also view the application configuration from the CLI via thefalcon-inspect-app script that is bundled with the framework:
falcon-inspect-app things_advanced:app
Here's the ASGI version of the app from above. Note that it uses thehttpx package in lieu ofrequests.
# examples/things_advanced_asgi.pyimportjsonimportloggingimportuuidimportfalconimportfalcon.asgiimporthttpxclassStorageEngine:asyncdefget_things(self,marker,limit):return [{'id':str(uuid.uuid4()),'color':'green'}]asyncdefadd_thing(self,thing):thing['id']=str(uuid.uuid4())returnthingclassStorageError(Exception):@staticmethodasyncdefhandle(ex,req,resp,params):# TODO: Log the error, clean up, etc. before raisingraisefalcon.HTTPInternalServerError()classSinkAdapter:engines= {'ddg':'https://duckduckgo.com','y':'https://search.yahoo.com/search', }asyncdef__call__(self,req,resp,engine):url=self.engines[engine]params= {'q':req.get_param('q',True)}asyncwithhttpx.AsyncClient()asclient:result=awaitclient.get(url,params=params)resp.status=result.status_coderesp.content_type=result.headers['content-type']resp.text=result.textclassAuthMiddleware:asyncdefprocess_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(title='Auth token required',description=description,challenges=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(title='Authentication required',description=description,challenges=challenges,href='http://docs.example.com/auth')def_token_is_valid(self,token,account_id):returnTrue# Suuuuuure it's valid...classRequireJSON:asyncdefprocess_request(self,req,resp):ifnotreq.client_accepts_json:raisefalcon.HTTPNotAcceptable(description='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(description='This API only supports requests encoded as JSON.',href='http://docs.examples.com/api/json')classJSONTranslator:# NOTE: Normally you would simply use req.get_media() and resp.media for# this particular use case; this example serves only to illustrate# what is possible.asyncdefprocess_request(self,req,resp):# NOTE: Test explicitly for 0, since this property could be None in# the case that the Content-Length header is missing (in which case we# can't know if there is a body without actually attempting to read# it from the request stream.)ifreq.content_length==0:# Nothing to doreturnbody=awaitreq.stream.read()ifnotbody:raisefalcon.HTTPBadRequest(title='Empty request body',description='A valid JSON document is required.')try:req.context.doc=json.loads(body.decode('utf-8'))except (ValueError,UnicodeDecodeError):description= ('Could not decode the request body. The ''JSON was incorrect or not encoded as ''UTF-8.')raisefalcon.HTTPBadRequest(title='Malformed JSON',description=description)asyncdefprocess_response(self,req,resp,resource,req_succeeded):ifnothasattr(resp.context,'result'):returnresp.text=json.dumps(resp.context.result)defmax_body(limit):asyncdefhook(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.HTTPContentTooLarge(title='Request body is too large',description=msg)returnhookclassThingsResource:def__init__(self,db):self.db=dbself.logger=logging.getLogger('thingsapp.'+__name__)asyncdefon_get(self,req,resp,user_id):marker=req.get_param('marker')or''limit=req.get_param_as_int('limit')or50try:result=awaitself.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(title='Service Outage',description=description,retry_after=30)# NOTE: Normally you would use resp.media for this sort of thing;# this example serves only to demonstrate how the context can be# used to pass arbitrary values between middleware components,# hooks, and resources.resp.context.result=resultresp.set_header('Powered-By','Falcon')resp.status=falcon.HTTP_200@falcon.before(max_body(64*1024))asyncdefon_post(self,req,resp,user_id):try:doc=req.context.docexceptAttributeError:raisefalcon.HTTPBadRequest(title='Missing thing',description='A thing must be submitted in the request body.')proper_thing=awaitself.db.add_thing(doc)resp.status=falcon.HTTP_201resp.location='/%s/things/%s'% (user_id,proper_thing['id'])# The app instance is an ASGI callableapp=falcon.asgi.App(middleware=[# AuthMiddleware(),RequireJSON(),JSONTranslator(),])db=StorageEngine()things=ThingsResource(db)app.add_route('/{user_id}/things',things)# If a responder ever raises 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')
You can run the ASGI version with any ASGI server, such as uvicorn:
$ pip install falcon httpx uvicorn$ uvicorn things_advanced_asgi:app
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, Gitter, and Twitter)
- Vytautas Liuolia (vytas7 on GH and Gitter, andvliuolia on Twitter)
- Nick Zaccardi (nZac on GH and Gitter)
- Federico Caselli (CaselIT 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-2025 by Individual and corporate contributors asnoted in the individual source files.
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.
About
The no-magic web API and microservices framework for Python developers, with an emphasis on reliability and performance at scale.
