Typing#

Type checking support was introduced in version 4.0. While most of the library is now typed, further type annotations may be added throughout the 4.x release cycle. To improve them, we may introduce changes to the typing that do not affect runtime behavior, but may surface new or different errors with type checkers.

Note

All undocumented type aliases coming from falcon._typing are considered private to the framework itself, and not meant for annotating applications using Falcon. To that end, it is advisable to only use classes from the public interface, and public aliases from falcon.typing, e.g.:

class MyResource:
    def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
        resp.media = {'message': 'Hello, World!'}

If you still decide to reuse the private aliases anyway, they should preferably be imported inside if TYPE_CHECKING: blocks in order to avoid possible runtime errors after an update. Also, make sure to let us know which essential aliases are missing from the public interface!

Known Limitations#

Falcon’s emphasis on flexibility and performance presents certain challenges when it comes to adding type annotations to the existing code base.

One notable limitation involves using custom Request and/or Response types in callbacks that are passed back to the framework, such as when adding an error handler. For instance, the following application might unexpectedly not pass type checking:

from typing import Any

from falcon import App, HTTPInternalServerError, Request, Response

class MyRequest(Request):
    ...

def handle_os_error(req: MyRequest, resp: Response, ex: Exception,
                    params: dict[str, Any]) -> None:
    raise HTTPInternalServerError(title='OS error!') from ex

app = App(request_type=MyRequest)
app.add_error_handler(OSError, handle_os_error)

(We are working on addressing this limitation at the time of writing – please see the following GitHub issue for the progress, and possible solutions: #2372.)

Another known inconsistency is the typing of the converter interface, where certain subclasses (such as PathConverter) declare a different input type than the base convert() method. (See also the discussions and possible solutions on the GitHub issue #2396.)

Important

The above issues are only typing limitations that have no effect outside of type checking – applications will work just fine at runtime!

Public Type Aliases#

Module that defines public Falcon type definitions.

class falcon.typing.AsyncReadableIO(*args, **kwargs)[source]#: Async file-like protocol that defines only a read method, and is iterable.

Added in version 4.0.

falcon.typing.Headers#: Headers dictionary returned by the framework.

Added in version 4.0.

class falcon.typing.ReadableIO(*args, **kwargs)[source]#: File-like protocol that defines only a read method.

Added in version 4.0.

falcon.typing.SSEEmitter#: Async generator or iterator over Server-Sent Events (instances of falcon.asgi.SSEvent).

Added in version 4.0.