Falcon Web Framework

4.2.0 · active · verified Sun Apr 12

Falcon is a minimalist, high-performance Python web API framework for building REST APIs and microservices. It provides a clean design that embraces HTTP and the REST architectural style, with a strong focus on reliability, correctness, and speed. The current version, 4.2.0, primarily contains typing enhancements and performance optimizations, including support for free-threaded CPython 3.14. Falcon supports both synchronous (WSGI) and asynchronous (ASGI) applications and typically follows a stable release cadence with regular updates.

Warnings

breaking Falcon 4.0 dropped support for Python 3.5-3.7. Applications must use Python 3.8 or newer (Falcon 4.2.0 requires Python 3.9+). It also removed many functions, classes, and compatibility shims previously deprecated in the 3.x series.
Fix: Upgrade your Python environment to 3.9+ and carefully review the Falcon 4.0 changelog for specific removals and breaking changes. Pay attention to deprecation warnings when upgrading from 3.x to 4.x.
breaking Falcon 4.0 changed the behavior of media type parsing, specifically regarding the vendored `python-mimeparse` library and `req.client_prefers`. It also changed how media types with different values for the same parameters are considered.
Fix: Review your application's media type handling, especially if you rely on `req.client_prefers` or custom media handlers. Ensure your media types and their parameters are parsed as expected.
gotcha A single instance of each resource class is shared among all requests processed by a given worker. This means that any instance variables on your resource classes are shared across concurrent requests.
Fix: Ensure that your resource classes are thread-safe. Avoid storing mutable per-request state directly as instance attributes on the resource. Instead, use `req` and `resp` objects for per-request data, or ensure proper synchronization if shared state is intentionally modified.
gotcha Falcon does not automatically consume request bodies. For `application/json` or `application/x-www-form-urlencoded` content types, you must explicitly call `req.get_media()` or access `req.media` to parse the body. For other content types or direct stream access, use `req.stream`.
Fix: Always use `req.get_media()` or `req.media` (for common types) or `req.stream` to read the request body in your responders. For example, `data = req.get_media()` to parse JSON or form data.
deprecated As of Falcon 3.0, uncaught exceptions that do not inherit from `falcon.HTTPError` or `falcon.HTTPStatus` will no longer propagate to the application server. Instead, a default `HTTP 500` response will be returned, and details will be logged to `wsgi.errors`.
Fix: Implement custom error handlers using `app.add_error_handler()` for specific exception types you wish to handle differently, or for a general `Exception` to override the default 500 behavior.

Install

pip install falcon Install Falcon

Imports

App
```
import falcon
app = falcon.App()
```
While `from falcon import App` works, the idiomatic way for WSGI apps is `import falcon; app = falcon.App()` as `falcon` is the primary module. For ASGI apps, use `from falcon.asgi import App as ASGIApp`.
ASGIApp
```
from falcon.asgi import App as ASGIApp
app = ASGIApp()
```
For building asynchronous (ASGI) applications, import `App` specifically from `falcon.asgi` and alias it to avoid collision with the WSGI `App`.
Request
```
from falcon import Request, Response
```
Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).
Response
```
from falcon import Request, Response
```
Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).
HTTP_200
```
import falcon
resp.status = falcon.HTTP_200
```
HTTP status codes are exposed directly on the `falcon` module (e.g., `falcon.HTTP_200`, `falcon.HTTP_201`).

Quickstart

This quickstart demonstrates a simple WSGI Falcon application. It defines a resource with an `on_get` method to handle GET requests to the `/quote` endpoint, returning a JSON response. The `falcon.App()` instance is then created and the resource is attached to a route. To serve this application, a WSGI server like Gunicorn is typically used. For ASGI applications, `falcon.asgi.App` and `async` responder methods would be used.

import falcon

class QuoteResource:
    def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
        """Handles GET requests."""
        resp.status = falcon.HTTP_200
        resp.media = {
            'quote': "I've always been more interested in the future than in the past.",
            'author': 'Grace Hopper',
        }

# Instantiate a WSGI Falcon application
app = falcon.App()

# Create an instance of our resource
quotes = QuoteResource()

# Add a route to our application
app.add_route('/quote', quotes)

# To run this, save as `app.py` and then run:
# pip install gunicorn
# gunicorn app:app
# Then access via curl: curl http://127.0.0.1:8000/quote

view raw JSON →