Falcon

Unburdening APIs for over 0.00 x 10-2 centuries.

As featured in TalkPython Episode #129

Get started Pledge today Contribute
# sample.py

import falcon

class QuoteResource:
    def on_get(self, req, resp):
        """Handles GET requests"""
        quote = {
            'quote': (
                "I've always been more interested in "
                "the future than in the past."
            ),
            'author': 'Grace Hopper'
        }

        resp.media = quote

api = falcon.API()
api.add_route('/quote', QuoteResource())
$ pip install falcon
$ gunicorn sample:api

Design

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

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

Reliable. We go to great lengths to avoid introducing breaking changes, and when we do they are fully documented and only introduced (in the spirit of SemVer) with a major version increment. The code is rigorously tested with numerous inputs and we require 100% coverage at all times. Six and mimeparse are the only third-party dependencies.

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

Debuggable. Falcon eschews magic. It's easy to tell which inputs lead to which outputs. Unhandled exceptions are never encapsulated or masked. Potentially surprising behaviors, such as automatic request body parsing, are well-documented and disabled by default. Finally, when it comes to the framework 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 in large-scale deployments.

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

Features

  • Highly-optimized, extensible code base
  • Intuitive routing via URI templates and REST-inspired resource classes
  • Easy access to headers and bodies through request and response classes
  • 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.6-2.7 and 3.3+, or PyPy 2.7 and 3.5+
  • Cython support for an extra speed boost under CPython

Don't lower your expectations to meet your performance. Raise your level of performance to meet your expectations. Expect the best of yourself, and then do what is necessary to make it a reality.

Benchmarks

To give you a feel for Falcon's performance, we've included the results of running a simple benchmark across several popular Python web frameworks.

Please note, however, that this benchmark is by no means comprehensive; it is only meant to provide a rough performance comparison between the given frameworks, and to demonstrate the baseline per-request overhead each framework incurs on an application.

As with any benchmark, you should take these numbers with a grain of salt. You should always run your own tests against your specific use case to discover what best suits your needs.

Scenario. The benchmark acts as a WSGI server and performs a GET request directly on each framework's PEP-3333 app. Requests are not sent over the network, since the performance of a given network or web server is not related to the performance of the WSGI frameworks themselves. Regardless, each app parses a route template with a single embedded parameter, reads a query parameter and a header from the request data, sets an x-header on the response, and finally returns a 10 KiB body, randomly generated.

Method. 50,000 iterations were executed per trial (100,000 for the PyPy tests), and the best time was recorded for each framework over 20 trials. The order in which the frameworks were tested was randomized for each trial. Also, garbage collection was enabled as it would be in a production environment, and a full collection was forcefully triggered before each trial. Finally, results were calculated using the Decimal class, and rounded to the nearest whole number.

Platform. Benchmarks were executed by running the corresponding Docker images on a Google Compute Engine instance (Intel Skylake, 1vCPU, 2 GB RAM), running Ubuntu 17.10 with all system packages updated to their latest versions as of Jan 2018. The frameworks were tested on several different versions of Python.

CPython 2.7.14

CPython 3.6.4

PyPy2 5.10.0

PyPy3 5.10.1

Extended Test

Falcon was also benchmarked under CPython 3.6 with a more realistic scenario, in which the routing table had multiple entries, the query string contained percent-encoded characters, and several complex response headers were set in the response. Note that even when Falcon is doing more work, it still is able to outperform other frameworks, which are only doing the bare minimum to construct a response.

In order to be great, you just have to care. You have to care about your world, community, and equality.

Community

Falcon is an Apache-licensed community project, built and supported by stylish volunteers from around the world.

PyCon 2016 Sprints

Check out the Falcon talks, podcasts, and blog posts wiki page to learn more about the project, and to add your own resources.

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

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

Per our Code of Conduct, we expect everyone who participates in community discussions to act professionally. Please lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture.

Kurt Griffiths (kgriffs on GH, Gitter, and Twitter) is the original creator and primary maintainer of the Falcon framework. Kurt is generously assisted by John Vrbanac (jmvrbanac on GH and Gitter, and jvrbanac on Twitter), a long-time friend of the project, who helps review pull requests, run PyCon sprints, and maintain ecosystem projects, such as falcon-example.

We are all inventors, each sailing out on a voyage of discovery, guided each by a private chart, of which there is no duplicate. The world is all gates, all opportunities.

Support Falcon Development

Falcon is an Apache-licensed community project, and is free to use. However, the large amount of time and effort needed to maintain the project and develop new features is not sustainable without the generous financial support of community members like you.

Please consider helping us secure the future of the Falcon framework with a one-time or recurring donation.

Thank you for your support!

One-time Donations

Your generous one-time donation helps Falcon's creator and lead maintainer, Kurt Griffiths (kgriffs), dedicate more of his personal time toward supporting the community, developing great new features, and improving the documentation.

Pledge $10 or more and receive a thank-you gift of a totally rad glow-in-the-dark Falcon button to put on your backpack or wherever you like (DM @kgriffs on Twitter or Gitter and Kurt will hook you up). If you donate $50 or more, we'll also throw in one of our great-looking T-shirts to thank you for your generous support.

Donations of any amount can be made through these channels:

Recurring Pledges

Recurring pledges come with some great perks, such as having your name listed in the BACKERS.md file, having your logo displayed on this website and in the docs, awesome T-shirts and glow-in-the-dark buttons, plus access to prioritized support from Falcon's creator, Kurt Griffiths.

Recurring pledges not only support Kurt Griffiths' (kgriffs) work on Falcon, but also help subsidize the cost for John Vrbanac (jmvrbanac) and other community leaders to maintain ecosystem projects and to engage with the community at PyCon and other venues.

Thank you for your generous support of open source software!

Has Falcon helped you make an awesome app? Show your support by becoming a patron.