The no-nonsense, minimalist web services and app backend framework for Python developers with a focu...
The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:
.. raw:: html
[![Falcon web framework logo](https://raw.githubusercontent.com/falconry/falcon/master/logo/banner.jpg)](https://falconframework.org)
|Docs| |Build Status| |codecov.io|
__ is a reliable, high-performance Python web framework for building large-scale app backends and microservices. It encourages the REST architectural style, and tries to do as little as possible while remaining highly effective.
Falcon apps work with any
_ server, and run like a champ under CPython 3.5+ and PyPy 3.5+ (3.6+ required for ASGI).
.. Patron list starts here. For Python package, we substitute this section with: Support Falcon Development
.. raw:: html
[![CERT Gouvernemental Luxembourg](https://falconframework.org/img/sponsors/govcert.png)](https://www.govcert.lu/)
.. raw:: html
[![LIKALO](https://falconframework.org/img/sponsors/likalo.svg)](https://www.likalo.com/) [![Examination RU](https://falconframework.org/img/sponsors/rabota.jpg)](https://www.kontrolnaya-rabota.ru/s/) [![Luhnar Site Accelerator](https://falconframework.org/img/sponsors/luhnar-dark.svg)](https://www.luhnar.com/)
.. raw:: html
.. Patron list ends here (see the comment above this section).
Has Falcon helped you make an awesome app? Show your support today with a one-time donation or by becoming a patron. Supporters get cool gear, an opportunity to promote their brand to Python developers, and prioritized support.
Learn how to support Falcon development <https:></https:>
Read the docs <https:></https:>
Falcon add-ons and complementary packages <https:></https:>
Falcon talks, podcasts, and blog posts <https:></https:>
_ @ Gitter
falconry/user for Falcon users <https:></https:>
_ @ Gitter
falconry/dev for Falcon contributors <https:></https:>
"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 a tiny server of mine and was ~40% faster with only 20 minutes of work."
"Falcon is rock solid and it's fast."
"I'm loving #falconframework! Super clean and simple, I finally have the speed and flexibility I need!"
"I feel like I'm just talking HTTP at last, with nothing in the middle. Falcon seems like the requests of backend."
"The source code for Falcon is so good, I almost prefer it to documentation. 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 anything to 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-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
__. 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
__) with a major version increment. The code is rigorously tested with numerous inputs and we require 100% coverage at all times. Falcon does not depend on any external Python packages.
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 <https:></https:>
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.
Falcon is used around the world by a growing number of organizations, including:
If you are using the Falcon framework for a community or commercial project, please consider adding your information to our wiki under
Who's Using Falcon? <https:></https:>
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 <https:></https:>
_ 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
_. We also have a
falconry/dev <https:></https:> ```_ room for discussing the design and development of the framework itself. Per our
Code of Conduct https:
\_, we expect everyone who participates in community discussions to act professionally, and lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture. ## Installation PyPy ^^^^
\_\_ is the fastest way to run your Falcon app. PyPy3.5+ is supported as of PyPy v5.10. .. code:: bash
$ pip install falcon
Or, to install the latest beta or release candidate, if any: .. code:: bash
$ pip install --pre falcon
CPython ^^^^^^^ Falcon also fully supports
\_\_ 3.5+. A universal wheel is available on PyPI for the the Falcon framework. Installing it is as simple as: .. code:: bash
$ pip install falcon
Installing the Falcon wheel is a great way to get up and running quickly in a development environment, but for an extra speed boost when deploying your application in production, Falcon can compile itself with Cython. Note, however, that Cython is currently incompatible with the falcon.asgi module. The following commands tell pip to install Cython, and then to invoke Falcon's
, which will in turn detect the presence of Cython and then compile (AKA cythonize) the Falcon framework with the system's default C compiler. .. code:: bash
$ pip install cython $ pip install --no-binary :all: falcon
If you want to verify that Cython is being invoked, simply pass
to pip in order to echo the compilation commands: .. code:: bash
$ pip install -v --no-binary :all: falcon
**Installing on OS X** Xcode Command Line Tools are required to compile Cython. Install them with this command: .. code:: bash
$ xcode-select --install
The Clang compiler treats unrecognized command-line options as errors, for example: .. code:: bash
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 around these issues by setting additional Clang C compiler flags as follows: .. code:: bash
$ export CFLAGS="-Qunused-arguments -Wno-unused-function"
Dependencies ^^^^^^^^^^^^ Falcon does not require the installation of any other packages, although if Cython has been installed into the environment, it will be used to optimize the framework as explained above. ## WSGI Server Falcon speaks
\_; see also below). In order to serve a Falcon app, you will need a WSGI server. Gunicorn and uWSGI are some of the more popular ones out there, but anything that can load a WSGI app will do. .. code:: bash
$ pip install [gunicorn|uwsgi]
## ASGI Server In order to serve a Falcon ASGI app, you will need an ASGI server. Uvicorn is a popular choice: .. code:: bash
$ pip install uvicorn
## Source Code Falcon
lives on GitHub https:
\_, making the code 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, you can install Falcon like this: .. code:: bash
$ cd falcon $ pip install .
Or, if you want to edit the code, first fork the main repo, clone the fork to your desktop, and then run the following to install it using symbolic linking, so that when you change your code, the changes will be automagically available to your app without having to reinstall the package: .. code:: bash
$ cd falcon $ pip install --no-use-pep517 -e .
You can manually test changes to the Falcon framework by switching to the directory of the cloned repo and then running pytest: .. code:: bash
$ cd falcon $ pip install -r requirements/tests $ pytest tests
Or, to run the default set of tests: .. code:: bash
$ pip install tox && tox
See also the
\_ file for a full list of available environments. ## Read the Docs 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. Online docs are available at: https://falcon.readthedocs.io You can build the same docs locally as follows: .. code:: bash
$ pip install tox && tox -e docs
Once the docs have been built, you can view them by opening the following index 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
## Getting Started Here is a simple, contrived example showing how to create a Falcon-based WSGI app (the ASGI version is included further down): .. code:: python
You can run the above example directly using the included wsgiref server: .. code:: bash
$ pip install falcon $ python things.py
Then, in another terminal: .. code:: bash
$ curl localhost:8000/things
The ASGI version of the example is similar: .. code:: python
You can run the ASGI version with uvicorn or any other ASGI server: .. code:: bash
$ pip install falcon uvicorn $ uvicorn things_asgi:app
## A More Complex Example (WSGI) Here is a more involved example that demonstrates reading headers and query parameters, handling errors, and working with request and response bodies. Note that this example assumes that the
\_ package has been installed. (For the equivalent ASGI app, see:
A More Complex Example (ASGI)
\_). .. code:: python
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 using any WSGI server, such as uWSGI or Gunicorn. For example: .. code:: bash
$ pip install requests gunicorn $ gunicorn things:app
On Windows you can run Gunicorn and uWSGI via WSL, or you might try Waitress: .. code:: bash
$ pip install requests waitress $ waitress-serve --port=8000 things:app
To test this example go to the another terminal and run: .. code:: bash
$ http localhost:8000/1/things authorization:custom-token
To visualize the application configuration the :ref:
can be used: .. code:: bash
## A More Complex Example (ASGI) Here's the ASGI version of the app from above. Note that it uses the
\_ package in lieu of
\_. .. code:: python
You can run the ASGI version with any ASGI server, such as uvicorn:
.. code:: bash
$ pip install falcon httpx uvicorn $ uvicorn things\_advanced\_asgi:app
Thanks for your interest in the project! We welcome pull requests from developers of all skill levels. To get started, simply fork the master branch on GitHub to your personal account and then clone the fork into your development 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 our
next milestone <https:></https:>
_. If you see one you'd like to work on, please leave a quick comment so that we don't end up with duplicated effort. Thanks in advance!
Please note that all contributors and maintainers of this project are subject to our
Code of Conduct <https:></https:>
Before submitting a pull request, please ensure you have added/updated the appropriate tests (and that all existing tests still pass with your changes), and that your coding style follows PEP 8 and doesn't cause pyflakes to complain.
Commit messages should be formatted using
AngularJS conventions <https:></https:>
Google's style guide <https:></https:>
__, with the additional requirement of prefixing inline comments using your GitHub nick and an appropriate prefix:
The core Falcon project maintainers are:
Please don't hesitate to reach out if you have any questions, or just need a little help getting started. You can find us in
_ on Gitter.
Copyright 2013-2020 by Individual and corporate contributors as noted in the individual source files.
Falcon image courtesy of
John O'Neill <https:></https:>
Licensed under the Apache License, Version 2.0 (the "License"); you may not use any portion of the Falcon framework except in compliance with the License. Contributors agree to license their work under the same License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed 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 and limitations under the License.
.. |Docs| image:: https://readthedocs.org/projects/falcon/badge/?version=stable :target: https://falcon.readthedocs.io/en/stable/?badge=stable :alt: Falcon web framework docs .. |Runner| image:: https://a248.e.akamai.net/assets.github.com/images/icons/emoji/runner.png :width: 20 :height: 20 .. |Build Status| image:: https://travis-ci.org/falconry/falcon.svg :target: https://travis-ci.org/falconry/falcon .. |codecov.io| image:: https://codecov.io/gh/falconry/falcon/branch/master/graphs/badge.svg :target: http://codecov.io/gh/falconry/falcon