{"id":4531,"library":"falcon","title":"Falcon Web Framework","description":"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.","status":"active","version":"4.2.0","language":"en","source_language":"en","source_url":"https://github.com/falconry/falcon","tags":["web-framework","asgi","wsgi","api","rest","microservices","performance"],"install":[{"cmd":"pip install falcon","lang":"bash","label":"Install Falcon"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"from falcon import App","symbol":"App","correct":"import falcon\napp = falcon.App()"},{"note":"For building asynchronous (ASGI) applications, import `App` specifically from `falcon.asgi` and alias it to avoid collision with the WSGI `App`.","symbol":"ASGIApp","correct":"from falcon.asgi import App as ASGIApp\napp = ASGIApp()"},{"note":"Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).","symbol":"Request","correct":"from falcon import Request, Response"},{"note":"Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).","symbol":"Response","correct":"from falcon import Request, Response"},{"note":"HTTP status codes are exposed directly on the `falcon` module (e.g., `falcon.HTTP_200`, `falcon.HTTP_201`).","symbol":"HTTP_200","correct":"import falcon\nresp.status = falcon.HTTP_200"}],"quickstart":{"code":"import falcon\n\nclass QuoteResource:\n    def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:\n        \"\"\"Handles GET requests.\"\"\"\n        resp.status = falcon.HTTP_200\n        resp.media = {\n            'quote': \"I've always been more interested in the future than in the past.\",\n            'author': 'Grace Hopper',\n        }\n\n# Instantiate a WSGI Falcon application\napp = falcon.App()\n\n# Create an instance of our resource\nquotes = QuoteResource()\n\n# Add a route to our application\napp.add_route('/quote', quotes)\n\n# To run this, save as `app.py` and then run:\n# pip install gunicorn\n# gunicorn app:app\n# Then access via curl: curl http://127.0.0.1:8000/quote","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"4.0.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"4.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"deprecated","affected_versions":"3.0.0 and later"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}