Falcon Documentation

Falcon is a high-performance Python web framework designed for building large-scale application backends and microservices. It emphasizes the REST architectural style and maintains a minimalist design to ensure high effectiveness with minimal overhead.

Key Capabilities:

• Supports ASGI, WSGI, and WebSockets.
• Provides native asyncio support.
• Avoids magic globals for routing and state management, making it highly debuggable.
• Offers stable interfaces with a strong emphasis on backwards compatibility.
• Features centralized RESTful routing and easy access to headers and bodies via request and response objects.
• Supports DRY (Don't Repeat Yourself) request processing using middleware and hooks.
• Strict adherence to RFCs with idiomatic HTTP error responses.
• Compatible with CPython 3.9+ and PyPy 3.9+.

Falcon provides several core capabilities for high-performance web development:

• Protocol Support: ASGI, WSGI, and WebSocket support.
• Async Support: Native asyncio support.
• Predictable State: No reliance on magic globals for routing and state management.
• Stability: Stable interfaces with an emphasis on backwards-compatibility.
• RESTful Routing: Simple API modeling through centralized routing.
• Optimized Core: Highly-optimized, extensible code base.
• Request/Response Handling: Easy access to headers and bodies through request and response objects.
• Extensibility: DRY request processing via middleware components and hooks.
• RFC Compliance: Strict adherence to RFCs and idiomatic HTTP error responses.
• Testing: Snappy testing with WSGI/ASGI helpers and mocks.
• Runtime Support: CPython 3.9+ and PyPy 3.9+ support.

Falcon uses the Inversion of Control (IoC) pattern to handle HTTP requests. When an HTTP request is made, Falcon passes references to request and response objects to your application's responders, middleware, and hooks.

• Use the request object to inspect incoming HTTP data (headers, body, query parameters, etc.).
• Use the response object to manipulate the outgoing HTTP response (status, headers, body, etc.).

Note that Falcon provides different object types depending on whether you are using a WSGI application (falcon.App) or an ASGI application (falcon.asgi.App), though the interfaces are designed to be highly similar to facilitate porting.

While both can insert logic into the request/response cycle, they differ in scope:

• Hooks: Applied locally to specific responders or resource classes using decorators.
• Middleware: Applied globally to all requests handled by the application.

Falcon does not attempt to protect responder code from its own errors. As of version 3.0, Falcon no longer propagates uncaught exceptions to the application server. Instead, the default Exception handler returns an HTTP 500 response and logs the exception details to wsgi.errors.

To build high-quality APIs, you should:

1. Set response variables to sane values within responders.
2. Ensure high code coverage through testing.
3. Anticipate and handle errors within responders using custom error handlers.

The Falcon framework itself is thread-safe; for every incoming request, new falcon.Request and falcon.Response objects are created. However, resource instances, middleware objects, and hooks (including custom error handlers) are shared across all requests.

To ensure your entire WSGI application is thread-safe, you must implement your resource classes, middleware, and hooks in a thread-safe manner and ensure any third-party libraries used are also thread-safe.

Falcon allows you to handle errors by raising instances of falcon.HTTPError or its subclasses (predefined errors) within responders, hooks, or middleware. When an HTTPError is raised, Falcon automatically converts it into an appropriate HTTP response with the correct status, headers, and body.

For custom error logic, you can also catch exceptions within your responder and raise a specific Falcon error, such as falcon.HTTPNotFound().

class Item:
    def __init__(self, image_store):
        self._image_store = image_store

    def on_get(self, req, resp, name):
        resp.content_type = mimetypes.guess_type(name)[0]

        try:
            resp.stream, resp.content_length = self._image_store.open(name)
        except OSError:
            # Raise a predefined error to return a 404 response
            raise falcon.HTTPNotFound()