The Falcon Web Framework<a class="headerlink" href="#the-falcon-web-framework" title="Permalink to this heading">¶

async deserialize_async(stream, content_type, content_length) → object[source]¶

Deserialize the falcon.Request body.

This method is similar to deserialize() except that it is asynchronous. The default implementation adapts the synchronous deserialize() method via io.BytesIO. For improved performance, media handlers should override this method.

Note

By default, the deserialize() method raises an instance of NotImplementedError. Therefore, child classes must either override deserialize() or deserialize_async() in order to be compatible with ASGI apps.

Parameters

stream (object) – Asynchronous file-like object to deserialize.
content_type (str) – Type of request content.
content_length (int) – Length of request content.

Returns

A deserialized object.

Return type

exhaust_stream = False¶

Whether to exhaust the input stream upon finishing deserialization.

Exhausting the stream may be useful for handlers that do not necessarily consume the whole stream, but the deserialized media object is complete and does not involve further streaming.

Tip

In order to use your custom media handler in a Falcon app, you’ll have to add an instance of your class to the app’s media handlers (specified in RequestOptions and ResponseOptions, respectively).

Handlers Mapping ¶

class falcon.media.Handlers(initial=None)[source]¶: A dict-like object that manages Internet media type handlers.

Media Type Constants ¶

The falcon module provides a number of constants for common media type strings, including the following:

falcon.MEDIA_JSON
falcon.MEDIA_MSGPACK
falcon.MEDIA_MULTIPART
falcon.MEDIA_URLENCODED
falcon.MEDIA_YAML
falcon.MEDIA_XML
falcon.MEDIA_HTML
falcon.MEDIA_JS
falcon.MEDIA_TEXT
falcon.MEDIA_JPEG
falcon.MEDIA_PNG
falcon.MEDIA_GIF

Multipart Forms¶

Body Part Type
Parser Configuration
Parsing Options
Parsing Errors

Falcon features easy and efficient access to submitted multipart forms by using MultipartFormHandler to handle the multipart/form-data media type. This handler is enabled by default, allowing you to use req.get_media() to iterate over the body parts in a form:

form = req.get_media()
for part in form:
    if part.content_type == 'application/json':
        # Body part is a JSON document, do something useful with it
        resp.media = part.get_media()
    elif part.name == 'datafile':
        while True:
            # Do something with the uploaded data (file)
            chunk = part.stream.read(8192)
            if not chunk:
                break
            feed_data(chunk)
    elif part.name == 'imagedata':
        # Store this body part in a file.
        filename = os.path.join(UPLOAD_PATH, part.secure_filename)
        with open(filename, 'wb') as dest:
            part.stream.pipe(dest)
    else:
        # Do something else
        form_data[part.name] = part.text

form = await req.get_media()
async for part in form:
    if part.content_type == 'application/json':
        # Body part is a JSON document, do something useful with it
        resp.media = await part.get_media()
    elif part.name == 'datafile':
        # Do something with the uploaded data (file)
        async for chunk in part.stream:
            await feed_data(chunk)
    elif part.name == 'imagedata':
        # Store this body part in a file.
        filename = os.path.join(UPLOAD_PATH, part.secure_filename)
        async with aiofiles.open(filename, 'wb') as dest:
            await part.stream.pipe(dest)
    else:
        # Do something else
        form_data[part.name] = await part.text

Note

Rather than being read in and buffered all at once, the request stream is only consumed on-demand, while iterating over the body parts in the form.

For each part, you can choose whether to read the whole part into memory, write it out to a file, or upload it to the cloud. Falcon offers straightforward support for all of these scenarios.

Body Part Type ¶

class falcon.media.multipart.BodyPart(stream, headers, parse_options)[source]¶

Represents a body part in a multipart form.

Note

BodyPart is meant to be instantiated directly only by the MultipartFormHandler parser.

content_type¶

Value of the Content-Type header, or the multipart form default text/plain if the header is missing.

Type: str

data¶

Property that acts as a convenience alias for get_data().

# Equivalent to: content = part.get_data()
content = part.data

The await keyword must still be added when referencing the property:

# Equivalent to: content = await part.get_data()
content = await part.data

Type: bytes

name¶

The name parameter of the Content-Disposition header. The value of the “name” parameter is the original field name from the submitted HTML form.

Note

According to RFC 7578, section 4.2, each part MUST include a Content-Disposition header field of type “form-data”, where the name parameter is mandatory.

However, Falcon will not raise any error if this parameter is missing; the property value will be None in that case.

Type: str

filename¶

File name if the body part is an attached file, and None otherwise.

Type: str

secure_filename¶

The sanitized version of filename using only the most common ASCII characters for maximum portability and safety wrt using this name as a filename on a regular file system.

If filename is empty or unset when referencing this property, an instance of MultipartParseError will be raised.

Parser Configuration ¶

Similar to falcon.App's req_options and resp_options, instantiating a MultipartFormHandler also fills its parse_options attribute with a set of sane default values suitable for many use cases out of the box. If you need to customize certain form parsing aspects of your application, the preferred way is to directly modify the properties of this attribute on the media handler (parser) in question:

import falcon
import falcon.media

handler = falcon.media.MultipartFormHandler()

# Assume text fields to be encoded in latin-1 instead of utf-8
handler.parse_options.default_charset = 'latin-1'

# Allow an unlimited number of body parts in the form
handler.parse_options.max_body_part_count = 0

# Afford parsing msgpack-encoded body parts directly via part.get_media()
extra_handlers = {
    falcon.MEDIA_MSGPACK: falcon.media.MessagePackHandler(),
}
handler.parse_options.media_handlers.update(extra_handlers)

In order to use your customized handler in an app, simply replace the default handler for multipart/form-data with the new one:

app = falcon.App()

# handler is instantiated and configured as per the above snippet
app.req_options.media_handlers[falcon.MEDIA_MULTIPART] = handler

app = falcon.asgi.App()

# handler is instantiated and configured as per the above snippet
app.req_options.media_handlers[falcon.MEDIA_MULTIPART] = handler

Tip

For more information on customizing media handlers, see also: Replacing the Default Handlers.

Parsing Options ¶

class falcon.media.multipart.MultipartParseOptions[source]¶

Defines a set of configurable multipart form parser options.

An instance of this class is exposed via the MultipartFormHandler.parse_options attribute. The handler’s options are also passed down to every BodyPart it instantiates.

Parsing Errors ¶

class falcon.media.multipart.MultipartParseError(description=None, **kwargs)[source]¶

Represents a multipart form parsing error.

This error may refer to a malformed or truncated form, usage of deprecated or unsupported features, or form parameters exceeding limits configured in MultipartParseOptions.

MultipartParseError instances raised in this module always include a short human-readable description of the error.

The cause of this exception, if any, is stored in the __cause__ attribute using the “raise … from” form when raising.

Parameters: source_error (Exception) – The source exception that was the cause of this one.

Redirection¶

Falcon defines a set of exceptions that can be raised within a middleware method, hook, or responder in order to trigger a 3xx (Redirection) response to the client. Raising one of these classes short-circuits request processing in a manner similar to raising an instance or subclass of HTTPError.

exception falcon.HTTPMovedPermanently(location, headers=None)[source]¶

301 Moved Permanently.

The 301 (Moved Permanently) status code indicates that the target resource has been assigned a new permanent URI.

Note

For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the 308 (Permanent Redirect) status code can be used instead.

(See also: RFC 7231, Section 6.4.2)

Parameters: location (str) – URI to provide as the Location header in the response.

exception falcon.HTTPFound(location, headers=None)[source]¶

302 Found.

The 302 (Found) status code indicates that the target resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client ought to continue to use the effective request URI for future requests.

Note

For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the 307 (Temporary Redirect) status code can be used instead.

(See also: RFC 7231, Section 6.4.3)

Parameters: location (str) – URI to provide as the Location header in the response.

exception falcon.HTTPSeeOther(location, headers=None)[source]¶

303 See Other.

The 303 (See Other) status code indicates that the server is redirecting the user agent to a different resource, as indicated by a URI in the Location header field, which is intended to provide an indirect response to the original request.

A 303 response to a GET request indicates that the origin server does not have a representation of the target resource that can be transferred over HTTP. However, the Location header in the response may be dereferenced to obtain a representation for an alternative resource. The recipient may find this alternative useful, even though it does not represent the original target resource.

Note

The new URI in the Location header field is not considered equivalent to the effective request URI.

(See also: RFC 7231, Section 6.4.4)

Parameters: location (str) – URI to provide as the Location header in the response.

exception falcon.HTTPTemporaryRedirect(location, headers=None)[source]¶

307 Temporary Redirect.

The 307 (Temporary Redirect) status code indicates that the target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. Since the redirection can change over time, the client ought to continue using the original effective request URI for future requests.

Note

This status code is similar to 302 (Found), except that it does not allow changing the request method from POST to GET.

(See also: RFC 7231, Section 6.4.7)

Parameters: location (str) – URI to provide as the Location header in the response.

exception falcon.HTTPPermanentRedirect(location, headers=None)[source]¶

308 Permanent Redirect.

The 308 (Permanent Redirect) status code indicates that the target resource has been assigned a new permanent URI.

Note

This status code is similar to 301 (Moved Permanently), except that it does not allow changing the request method from POST to GET.

(See also: RFC 7238, Section 3)

Parameters: location (str) – URI to provide as the Location header in the response.

Middleware¶

Short-Circuiting
Exception Handling

Middleware components provide a way to execute logic before the framework routes each request, after each request is routed but before the target responder is called, or just before the response is returned for each request.

Note

Unlike hooks, middleware methods apply globally to the entire App.

Components are registered with the middleware kwarg when instantiating Falcon’s App class. A middleware component is simply a class that implements one or more of the event handler methods defined below.

Falcon’s middleware interface is defined as follows:

class ExampleMiddleware:
    def process_request(self, req, resp):
        """Process the request before routing it.

        Note:
            Because Falcon routes each request based on req.path, a
            request can be effectively re-routed by setting that
            attribute to a new value from within process_request().

        Args:
            req: Request object that will eventually be
                routed to an on_* responder method.
            resp: Response object that will be routed to
                the on_* responder.
        """

    def process_resource(self, req, resp, resource, params):
        """Process the request after routing.

        Note:
            This method is only called when the request matches
            a route to a resource.

        Args:
            req: Request object that will be passed to the
                routed responder.
            resp: Response object that will be passed to the
                responder.
            resource: Resource object to which the request was
                routed.
            params: A dict-like object representing any additional
                params derived from the route's URI template fields,
                that will be passed to the resource's responder
                method as keyword arguments.
        """

    def process_response(self, req, resp, resource, req_succeeded):
        """Post-processing of the response (after routing).

        Args:
            req: Request object.
            resp: Response object.
            resource: Resource object to which the request was
                routed. May be None if no route was found
                for the request.
            req_succeeded: True if no exceptions were raised while
                the framework processed and routed the request;
                otherwise False.
        """

# A middleware instance can then be added to the Falcon app init
from falcon import App

app = App(middleware=[ExampleMiddleware()])

The ASGI middleware interface is similar to WSGI, but also supports the standard ASGI lifespan events. However, because lifespan events are an optional part of the ASGI specification, they may or may not fire depending on your ASGI server.

class ExampleMiddleware:
    async def process_startup(self, scope, event):
        """Process the ASGI lifespan startup event.

        Invoked when the server is ready to start up and
        receive connections, but before it has started to
        do so.

        To halt startup processing and signal to the server that it
        should terminate, simply raise an exception and the
        framework will convert it to a "lifespan.startup.failed"
        event for the server.

        Args:
            scope (dict): The ASGI scope dictionary for the
                lifespan protocol. The lifespan scope exists
                for the duration of the event loop.
            event (dict): The ASGI event dictionary for the
                startup event.
        """

    async def process_shutdown(self, scope, event):
        """Process the ASGI lifespan shutdown event.

        Invoked when the server has stopped accepting
        connections and closed all active connections.

        To halt shutdown processing and signal to the server
        that it should immediately terminate, simply raise an
        exception and the framework will convert it to a
        "lifespan.shutdown.failed" event for the server.

        Args:
            scope (dict): The ASGI scope dictionary for the
                lifespan protocol. The lifespan scope exists
                for the duration of the event loop.
            event (dict): The ASGI event dictionary for the
                shutdown event.
        """

    async def process_request(self, req, resp):
        """Process the request before routing it.

        Note:
            Because Falcon routes each request based on req.path, a
            request can be effectively re-routed by setting that
            attribute to a new value from within process_request().

        Args:
            req: Request object that will eventually be
                routed to an on_* responder method.
            resp: Response object that will be routed to
                the on_* responder.
        """

    async def process_resource(self, req, resp, resource, params):
        """Process the request after routing.

        Note:
            This method is only called when the request matches
            a route to a resource.

        Args:
            req: Request object that will be passed to the
                routed responder.
            resp: Response object that will be passed to the
                responder.
            resource: Resource object to which the request was
                routed.
            params: A dict-like object representing any additional
                params derived from the route's URI template fields,
                that will be passed to the resource's responder
                method as keyword arguments.
        """

    async def process_response(self, req, resp, resource, req_succeeded):
        """Post-processing of the response (after routing).

        Args:
            req: Request object.
            resp: Response object.
            resource: Resource object to which the request was
                routed. May be None if no route was found
                for the request.
            req_succeeded: True if no exceptions were raised while
                the framework processed and routed the request;
                otherwise False.
        """

    async def process_request_ws(self, req, ws):
        """Process a WebSocket handshake request before routing it.

        Note:
            Because Falcon routes each request based on req.path, a
            request can be effectively re-routed by setting that
            attribute to a new value from within process_request().

        Args:
            req: Request object that will eventually be
                passed into an on_websocket() responder method.
            ws: The WebSocket object that will be passed into
                on_websocket() after routing.
        """

    async def process_resource_ws(self, req, ws, resource, params):
        """Process a WebSocket handshake request after routing.

        Note:
            This method is only called when the request matches
            a route to a resource.

        Args:
            req: Request object that will be passed to the
                routed responder.
            ws: WebSocket object that will be passed to the
                routed responder.
            resource: Resource object to which the request was
                routed.
            params: A dict-like object representing any additional
                params derived from the route's URI template fields,
                that will be passed to the resource's responder
                method as keyword arguments.
        """

# A middleware instance can then be added to the Falcon app init
from falcon.asgi import App

app = App(middleware=[ExampleMiddleware()])

It is also possible to implement a middleware component that is compatible with both ASGI and WSGI apps. This is done by applying an *_async postfix to distinguish the two different versions of each middleware method, as in the following example:

class ExampleMiddleware:
    def process_request(self, req, resp):
        """Process WSGI request using synchronous logic.

        Note that req and resp are instances of falcon.Request and
        falcon.Response, respectively.
        """

    async def process_request_async(self, req, resp):
        """Process ASGI request using asynchronous logic.

        Note that req and resp are instances of falcon.asgi.Request and
        falcon.asgi.Response, respectively.
        """

Tip

Because process_request executes before routing has occurred, if a component modifies req.path in its process_request method, the framework will use the modified value to route the request.

For example:

# Route requests based on the host header.
req.path = '/' + req.host + req.path

Tip

The process_resource method is only called when the request matches a route to a resource. To take action when a route is not found, a sink may be used instead.

Tip

In order to pass data from a middleware function to a resource function use the req.context and resp.context objects. These context objects are intended to hold request and response data specific to your app as it passes through the framework.

Each component’s process_request, process_resource, and process_response methods are executed hierarchically, as a stack, following the ordering of the list passed via the middleware kwarg of falcon.App or falcon.asgi.App. For example, if a list of middleware objects are passed as [mob1, mob2, mob3], the order of execution is as follows:

mob1.process_request
    mob2.process_request
        mob3.process_request
            mob1.process_resource
                mob2.process_resource
                    mob3.process_resource
            <route to resource responder method>
        mob3.process_response
    mob2.process_response
mob1.process_response

Note that each component need not implement all process_* methods; in the case that one of the three methods is missing, it is treated as a noop in the stack. For example, if mob2 did not implement process_request and mob3 did not implement process_response, the execution order would look like this:

mob1.process_request
    _
        mob3.process_request
            mob1.process_resource
                mob2.process_resource
                    mob3.process_resource
            <route to responder method>
        _
    mob2.process_response
mob1.process_response

Short-Circuiting ¶

A process_request or process_resource middleware method may short-circuit further request processing by setting falcon.Response.complete to True, e.g.:

resp.complete = True

After the method returns, setting this flag will cause the framework to skip any remaining process_request and process_resource methods, as well as the responder method that the request would have been routed to. However, any process_response middleware methods will still be called.

In a similar manner, setting falcon.Response.complete to True from within a process_resource method will short-circuit further request processing at that point.

In the example below, you can see how request processing will be short-circuited once falcon.Response.complete has been set to True, i.e., the framework will prevent mob3.process_request, all process_resource methods, as well as the routed responder method from processing the request. However, all process_response methods will still be called:

mob1.process_request
    mob2.process_request  # resp.complete = True
        <skip mob3.process_request>
        <skip mob1/mob2/mob3.process_resource>
        <skip route to resource responder method>
        mob3.process_response
    mob2.process_response
mob1.process_response

This feature affords use cases in which the response may be pre-constructed, such as in the case of caching.

Exception Handling ¶

If one of the process_request middleware methods raises an exception, it will be processed according to the exception type. If the type matches a registered error handler, that handler will be invoked and then the framework will begin to unwind the stack, skipping any lower layers. The error handler may itself raise an instance of HTTPError or HTTPStatus, in which case the framework will use the latter exception to update the resp object.

Note

By default, the framework installs two handlers, one for HTTPError and one for HTTPStatus. These can be overridden via add_error_handler().

Regardless, the framework will continue unwinding the middleware stack. For example, if mob2.process_request were to raise an error, the framework would execute the stack as follows:

mob1.process_request
    mob2.process_request
        <skip mob1/mob2 process_resource>
        <skip mob3.process_request>
        <skip mob3.process_resource>
        <skip route to resource responder method>
        mob3.process_response
    mob2.process_response
mob1.process_response

As illustrated above, by default, all process_response methods will be executed, even when a process_request, process_resource, or on_* resource responder raises an error. This behavior is controlled by the App class’s independent_middleware keyword argument.

Finally, if one of the process_response methods raises an error, or the routed on_* responder method itself raises an error, the exception will be handled in a similar manner as above. Then, the framework will execute any remaining middleware on the stack.

CORS¶

Cross Origin Resource Sharing (CORS) is an additional security check performed by modern browsers to prevent unauthorized requests between different domains.

When developing a web API, it is common to also implement a CORS policy. Therefore, Falcon provides an easy way to enable a simple CORS policy via a flag passed to falcon.App or falcon.asgi.App.

By default, Falcon’s built-in CORS support is disabled, so that any cross-origin requests will be blocked by the browser. Passing cors_enable=True will cause the framework to include the necessary response headers to allow access from any origin to any route in the app. Individual responders may override this behavior by setting the Access-Control-Allow-Origin header explicitly.

Whether or not you implement a CORS policy, we recommend also putting a robust AuthN/Z layer in place to authorize individual clients, as needed, to protect sensitive resources.

Directly passing the falcon.CORSMiddleware middleware to the application allows customization of the CORS policy applied. The middleware allows customizing the allowed origins, if credentials should be allowed and if additional headers can be exposed.

Usage¶

import falcon

# Enable a simple CORS policy for all responses
app = falcon.App(cors_enable=True)

# Alternatively, enable CORS policy for example.com and allow
# credentials
app = falcon.App(middleware=falcon.CORSMiddleware(
    allow_origins='example.com', allow_credentials='*'))

import falcon.asgi

# Enable a simple CORS policy for all responses
app = falcon.asgi.App(cors_enable=True)

# Alternatively, Enable CORS policy for example.com and allow
# credentials
app = falcon.asgi.App(middleware=falcon.CORSMiddleware(
    allow_origins='example.com', allow_credentials='*'))

Note

Passing the cors_enable parameter set to True should be seen as mutually exclusive with directly passing an instance of CORSMiddleware to the application’s initializer.

CORSMiddleware¶

class falcon.CORSMiddleware(allow_origins: Union[str, Iterable[str]] = '*', expose_headers: Optional[Union[str, Iterable[str]]] = None, allow_credentials: Optional[Union[str, Iterable[str]]] = None)[source]¶

CORS Middleware.

This middleware provides a simple out-of-the box CORS policy, including handling of preflighted requests from the browser.

Hooks¶

Before Hooks
After Hooks

Falcon supports before and after hooks. You install a hook simply by applying one of the decorators below, either to an individual responder or to an entire resource.

For example, consider this hook that validates a POST request for an image resource:

def validate_image_type(req, resp, resource, params):
    if req.content_type not in ALLOWED_IMAGE_TYPES:
        msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
        raise falcon.HTTPBadRequest(title='Bad request', description=msg)

You would attach this hook to an on_post responder like so:

@falcon.before(validate_image_type)
def on_post(self, req, resp):
    pass

Or, suppose you had a hook that you would like to apply to all responders for a given resource. In that case, you would simply decorate the resource class:

@falcon.before(extract_project_id)
class Message:
    def on_post(self, req, resp, project_id):
        pass

    def on_get(self, req, resp, project_id):
        pass

Note

When decorating an entire resource class, all method names that resemble responders, including suffixed (see also add_route()) ones, are decorated. If, for instance, a method is called on_get_items, but it is not meant for handling GET requests under a route with the suffix items, the easiest workaround for preventing the hook function from being applied to the method is renaming it not to clash with the responder pattern.

Note also that you can pass additional arguments to your hook function as needed:

def validate_image_type(req, resp, resource, params, allowed_types):
    if req.content_type not in allowed_types:
        msg = 'Image type not allowed.'
        raise falcon.HTTPBadRequest(title='Bad request', description=msg)

@falcon.before(validate_image_type, ['image/png'])
def on_post(self, req, resp):
    pass

Falcon supports using any callable as a hook. This allows for using a class instead of a function:

class Authorize:
    def __init__(self, roles):
        self._roles = roles

    def __call__(self, req, resp, resource, params):
        pass

@falcon.before(Authorize(['admin']))
def on_post(self, req, resp):
    pass

Falcon middleware components can also be used to insert logic before and after requests. However, unlike hooks, middleware components are triggered globally for all requests.

Tip

In order to pass data from a hook function to a resource function use the req.context and resp.context objects. These context objects are intended to hold request and response data specific to your app as it passes through the framework.

Before Hooks¶

falcon.before(action, *args, is_async=False, **kwargs)[source]¶

Execute the given action function before the responder.

The params argument that is passed to the hook contains only the fields from the URI template path; it does not include query string values.

Hooks may inject extra params as needed. For example:

def do_something(req, resp, resource, params):
    try:
        params['id'] = int(params['id'])
    except ValueError:
        raise falcon.HTTPBadRequest(title='Invalid ID',
                                    description='ID was not valid.')

    params['answer'] = 42

Parameters

action (callable) – A function of the form func(req, resp, resource, params), where resource is a reference to the resource class instance associated with the request and params is a dict of URI template field names, if any, that will be passed into the resource responder as kwargs.
*args – Any additional arguments will be passed to action in the order given, immediately following the req, resp, resource, and params arguments.

Keyword Arguments

is_async (bool) –
Set to True for ASGI apps to provide a hint that the decorated responder is a coroutine function (i.e., that it is defined with async def) or that it returns an awaitable coroutine object.

Normally, when the function source is declared using async def, the resulting function object is flagged to indicate it returns a coroutine when invoked, and this can be automatically detected. However, it is possible to use a regular function to return an awaitable coroutine object, in which case a hint is required to let the framework know what to expect. Also, a hint is always required when using a cythonized coroutine function, since Cython does not flag them in a way that can be detected in advance, even when the function is declared using async def.
**kwargs – Any additional keyword arguments will be passed through to action.

After Hooks¶

falcon.after(action, *args, is_async=False, **kwargs)[source]¶

Execute the given action function after the responder.

Parameters

action (callable) – A function of the form func(req, resp, resource), where resource is a reference to the resource class instance associated with the request
*args – Any additional arguments will be passed to action in the order given, immediately following the req, resp and resource arguments.

Keyword Arguments

is_async (bool) –
Set to True for ASGI apps to provide a hint that the decorated responder is a coroutine function (i.e., that it is defined with async def) or that it returns an awaitable coroutine object.

Normally, when the function source is declared using async def, the resulting function object is flagged to indicate it returns a coroutine when invoked, and this can be automatically detected. However, it is possible to use a regular function to return an awaitable coroutine object, in which case a hint is required to let the framework know what to expect. Also, a hint is always required when using a cythonized coroutine function, since Cython does not flag them in a way that can be detected in advance, even when the function is declared using async def.
**kwargs – Any additional keyword arguments will be passed through to action.

Routing¶

Default Behavior
Field Converters
Built-in Converters
Custom Converters
Custom Routers
Suffixed Responders
Default Router
Routing Utilities
Custom HTTP Methods

Falcon uses resource-based routing to encourage a RESTful architectural style. Each resource is represented by a class that is responsible for handling all of the HTTP methods that the resource supports.

For each HTTP method supported by the resource, the class implements a corresponding Python method with a name that starts with on_ and ends in the lowercased HTTP method name (e.g., on_get(), on_patch(), on_delete(), etc.)

Note

Resources in Falcon are represented by a single class instance that is created at application startup when the routes are configured. This minimizes routing overhead and simplifies the implementation of resource classes. In the case of WSGI apps, this also means that resource classes must be implemented in a thread-safe manner (see also: Is Falcon thread-safe?).

Falcon routes incoming requests (including WebSocket handshakes) to resources based on a set of URI templates. If the path requested by the client matches the template for a given route, the request is then passed on to the associated resource for processing.

Here’s a quick example to show how all the pieces fit together:

import json

import falcon


class ImagesResource:

    def on_get(self, req, resp):
        doc = {
            'images': [
                {
                    'href': '/images/1eaf6ef1-7f2d-4ecc-a8d5-6e8adba7cc0e.png'
                }
            ]
        }

        # Create a JSON representation of the resource; this could
        #   also be done automatically by assigning to resp.media
        resp.text = json.dumps(doc, ensure_ascii=False)

        # The following line can be omitted because 200 is the default
        # status returned by the framework, but it is included here to
        # illustrate how this may be overridden as needed.
        resp.status = falcon.HTTP_200


app = falcon.App()

images = ImagesResource()
app.add_route('/images', images)

import json

import falcon
import falcon.asgi


class ImagesResource:

    async def on_get(self, req, resp):
        doc = {
            'images': [
                {
                    'href': '/images/1eaf6ef1-7f2d-4ecc-a8d5-6e8adba7cc0e.png'
                }
            ]
        }

        # Create a JSON representation of the resource; this could
        #   also be done automatically by assigning to resp.media
        resp.text = json.dumps(doc, ensure_ascii=False)

        # The following line can be omitted because 200 is the default
        # status returned by the framework, but it is included here to
        # illustrate how this may be overridden as needed.
        resp.status = falcon.HTTP_200


app = falcon.asgi.App()

images = ImagesResource()
app.add_route('/images', images)

If no route matches the request, control then passes to a default responder that simply raises an instance of HTTPRouteNotFound. By default, this error will be rendered as a 404 response for a regular HTTP request, and a 403 response with a 3404 close code for a WebSocket handshake. This behavior can be modified by adding a custom error handler (see also this FAQ topic).

On the other hand, if a route is matched but the resource does not implement a responder for the requested HTTP method, the framework invokes a default responder that raises an instance of HTTPMethodNotAllowed. This class will be rendered by default as a 405 response for a regular HTTP request, and a 403 response with a 3405 close code for a WebSocket handshake.

Falcon also provides a default responder for OPTIONS requests that takes into account which methods are implemented for the target resource.

Default Behavior ¶

Falcon’s default routing engine is based on a decision tree that is first compiled into Python code, and then evaluated by the runtime. By default, the decision tree is compiled only when the router handles the first request. See CompiledRouter for more details.

The falcon.App.add_route() and falcon.asgi.App.add_route() methods are used to associate a URI template with a resource. Falcon then maps incoming requests to resources based on these templates.

Falcon’s default router uses Python classes to represent resources. In practice, these classes act as controllers in your application. They convert an incoming request into one or more internal actions, and then compose a response back to the client based on the results of those actions. (See also: Tutorial: Creating Resources)

           ┌────────────┐
request  → │            │
           │ Resource   │ ↻ Orchestrate the requested action
           │ Controller │ ↻ Compose the result
response ← │            │
           └────────────┘

Each resource class defines various “responder” methods, one for each HTTP method the resource allows. Responder names start with on_ and are named according to which HTTP method they handle, as in on_get(), on_post(), on_put(), etc.

Note

If your resource does not support a particular HTTP method, simply omit the corresponding responder and Falcon will use a default responder that raises an instance of HTTPMethodNotAllowed when that method is requested. Normally this results in sending a 405 response back to the client.

Responders must always define at least two arguments to receive Request and Response objects, respectively:

def on_post(self, req, resp):
    pass

For ASGI apps, the responder must be a coroutine function:

async def on_post(self, req, resp):
    pass

The Request object represents the incoming HTTP request. It exposes properties and methods for examining headers, query string parameters, and other metadata associated with the request. A file-like stream object is also provided for reading any data that was included in the body of the request.

The Response object represents the application’s HTTP response to the above request. It provides properties and methods for setting status, header and body data. The Response object also exposes a dict-like context property for passing arbitrary data to hooks and middleware methods.

Note

Rather than directly manipulate the Response object, a responder may raise an instance of either HTTPError or HTTPStatus. Falcon will convert these exceptions to appropriate HTTP responses. Alternatively, you can handle them yourself via add_error_handler().

In addition to the standard req and resp parameters, if the route’s template contains field expressions, any responder that desires to receive requests for that route must accept arguments named after the respective field names defined in the template.

A field expression consists of a bracketed field name. For example, given the following template:

/user/{name}

A PUT request to '/user/kgriffs' would cause the framework to invoke the on_put() responder method on the route’s resource class, passing 'kgriffs' via an additional name argument defined by the responder:

# Template fields correspond to named arguments or keyword
#   arguments, following the usual req and resp args.
def on_put(self, req, resp, name):
    pass

# Template fields correspond to named arguments or keyword
#   arguments, following the usual req and resp args.
async def on_put(self, req, resp, name):
    pass

Because field names correspond to argument names in responder methods, they must be valid Python identifiers.

Individual path segments may contain one or more field expressions, and fields need not span the entire path segment. For example:

/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
/serviceRoot/People('{name}')

(See also the Falcon tutorial for additional examples and a walkthrough of setting up routes within the context of a sample application.)

Field Converters ¶

Falcon’s default router supports the use of field converters to transform a URI template field value. Field converters may also perform simple input validation. For example, the following URI template uses the int converter to convert the value of tid to a Python int, but only if it has exactly eight digits:

/teams/{tid:int(8)}

If the value is malformed and can not be converted, Falcon will reject the request with a 404 response to the client.

Converters are instantiated with the argument specification given in the field expression. These specifications follow the standard Python syntax for passing arguments. For example, the comments in the following code show how a converter would be instantiated given different argument specifications in the URI template:

# IntConverter()
app.add_route(
    '/a/{some_field:int}',
    some_resource
)

# IntConverter(8)
app.add_route(
    '/b/{some_field:int(8)}',
    some_resource
)

# IntConverter(8, min=10000000)
app.add_route(
    '/c/{some_field:int(8, min=10000000)}',
    some_resource
)

(See also how UUIDConverter is used in Falcon’s ASGI tutorial: Images Resource(s).)

Built-in Converters ¶

Identifier	Class	Example
`int`	`IntConverter`	`/teams/{tid:int(8)}`
`uuid`	`UUIDConverter`	`/diff/{left:uuid}...{right:uuid}`
`dt`	`DateTimeConverter`	`/logs/{day:dt("%Y-%m-%d")}`

class falcon.routing.IntConverter(num_digits=None, min=None, max=None)[source]¶

Converts a field value to an int.

Identifier: int

Keyword Arguments

num_digits (int) – Require the value to have the given number of digits.
min (int) – Reject the value if it is less than this number.
max (int) – Reject the value if it is greater than this number.

convert(value)[source]¶

Convert a URI template field value to another format or type.

Parameters

value (str) – Original string to convert.

Returns

Converted field value, or None if the field: can not be converted.

Return type

class falcon.routing.UUIDConverter[source]¶

Converts a field value to a uuid.UUID.

Identifier: uuid

In order to be converted, the field value must consist of a string of 32 hexadecimal digits, as defined in RFC 4122, Section 3. Note, however, that hyphens and the URN prefix are optional.

convert(value)[source]¶

Convert a URI template field value to another format or type.

Parameters

value (str) – Original string to convert.

Returns

Converted field value, or None if the field: can not be converted.

Return type

class falcon.routing.DateTimeConverter(format_string='%Y-%m-%dT%H:%M:%SZ')[source]¶

Converts a field value to a datetime.

Identifier: dt

Keyword Arguments: format_string (str) – String used to parse the field value into a datetime. Any format recognized by strptime() is supported (default '%Y-%m-%dT%H:%M:%SZ').

convert(value)[source]¶

Convert a URI template field value to another format or type.

Parameters

value (str) – Original string to convert.

Returns

Converted field value, or None if the field: can not be converted.

Return type

Custom Converters ¶

Custom converters can be registered via the converters router option. A converter is simply a class that implements the BaseConverter interface:

class falcon.routing.BaseConverter[source]¶

Abstract base class for URI template field converters.

abstract convert(value)[source]¶

Convert a URI template field value to another format or type.

Parameters

value (str) – Original string to convert.

Returns

Converted field value, or None if the field: can not be converted.

Return type

Custom Routers ¶

A custom routing engine may be specified when instantiating falcon.App() or falcon.asgi.App(). For example:

router = MyRouter()
app = App(router=router)

Custom routers may derive from the default CompiledRouter engine, or implement a completely different routing strategy (such as object-based routing).

A custom router is any class that implements the following interface:

class MyRouter:
    def add_route(self, uri_template, resource, **kwargs):
        """Adds a route between URI path template and resource.

        Args:
            uri_template (str): A URI template to use for the route
            resource (object): The resource instance to associate with
                the URI template.

        Keyword Args:
            suffix (str): Optional responder name suffix for this
                route. If a suffix is provided, Falcon will map GET
                requests to ``on_get_{suffix}()``, POST requests to
                ``on_post_{suffix}()``, etc. In this way, multiple
                closely-related routes can be mapped to the same
                resource. For example, a single resource class can
                use suffixed responders to distinguish requests for
                a single item vs. a collection of those same items.
                Another class might use a suffixed responder to handle
                a shortlink route in addition to the regular route for
                the resource.

            **kwargs (dict): Accepts any additional keyword arguments
                that were originally passed to the falcon.App.add_route()
                method. These arguments MUST be accepted via the
                double-star variadic pattern (**kwargs), and ignore any
                unrecognized or unsupported arguments.
        """

    def find(self, uri, req=None):
        """Search for a route that matches the given partial URI.

        Args:
            uri(str): The requested path to route.

        Keyword Args:
             req(Request): The Request object that will be passed to
                the routed responder. The router may use `req` to
                further differentiate the requested route. For
                example, a header may be used to determine the
                desired API version and route the request
                accordingly.

                Note:
                    The `req` keyword argument was added in version
                    1.2. To ensure backwards-compatibility, routers
                    that do not implement this argument are still
                    supported.

        Returns:
            tuple: A 4-member tuple composed of (resource, method_map,
                params, uri_template), or ``None`` if no route matches
                the requested path.

        """

Suffixed Responders ¶

While Falcon encourages the REST architectural style, it is flexible enough to accomodate other paradigms. Consider the task of building an API for a calculator which can both add and subtract two numbers. You could implement the following:

class Add():
    def on_get(self, req, resp):
        resp.text = str(req.get_param_as_int('x') + req.get_param_as_int('y'))
        resp.status = falcon.HTTP_200


class Subtract():
    def on_get(self, req, resp):
        resp.text = str(req.get_param_as_int('x') - req.get_param_as_int('y'))
        resp.status = falcon.HTTP_200


add = Add()
subtract = Subtract()
app = falcon.App()
app.add_route('/add', add)
app.add_route('/subtract', subtract)

However, this approach highlights a situation in which grouping by resource may not make sense for your domain. In this context, adding and subtracting don’t seem to conceptually map to two separate resource collections. Instead of separating them based on the idea of “getting” different resources from each, we might want to group them based on the attributes of their function (i.e., take two numbers, do something to them, return the result).

With Suffixed Responders, we can do just that, rewriting the example above in a more procedural style:

class Calculator():
    def on_get_add(self, req, resp):
        resp.text = str(req.get_param_as_int('x') + req.get_param_as_int('y'))
        resp.status = falcon.HTTP_200

    def on_get_subtract(self, req, resp):
        resp.text = str(req.get_param_as_int('x') - req.get_param_as_int('y'))
        resp.status = falcon.HTTP_200


calc = Calculator()
app = falcon.App()
app.add_route('/add', calc, suffix='add')
app.add_route('/subtract', calc, suffix='subtract')

In the second iteration, using Suffixed Responders, we’re able to group responders based on their actions rather than the data they represent. This gives us added flexibility to accomodate situations in which a purely RESTful approach simply doesn’t fit.

Default Router ¶

class falcon.routing.CompiledRouter[source]¶

Fast URI router which compiles its routing logic to Python code.

Generally you do not need to use this router class directly, as an instance is created by default when the falcon.App class is initialized.

The router treats URI paths as a tree of URI segments and searches by checking the URI one segment at a time. Instead of interpreting the route tree for each look-up, it generates inlined, bespoke Python code to perform the search, then compiles that code. This makes the route processing quite fast.

The compilation process is delayed until the first use of the router (on the first routed request) to reduce the time it takes to start the application. This may noticeably delay the first response of the application when a large number of routes have been added. When adding the last route to the application a compile flag may be provided to force the router to compile immediately, thus avoiding any delay for the first response.

Note

When using a multi-threaded web server to host the application, it is possible that multiple requests may be routed at the same time upon startup. Therefore, the framework employs a lock to ensure that only a single compilation of the decision tree is performed.

Routing Utilities ¶

The falcon.routing module contains the following utilities that may be used by custom routing engines.

falcon.routing.map_http_methods(resource, suffix=None)[source]¶

Map HTTP methods (e.g., GET, POST) to methods of a resource object.

Parameters: resource – An object with responder methods, following the naming convention on_*, that correspond to each method the resource supports. For example, if a resource supports GET and POST, it should define on_get(self, req, resp) and on_post(self, req, resp).
Keyword Arguments: suffix (str) – Optional responder name suffix for this route. If a suffix is provided, Falcon will map GET requests to on_get_{suffix}(), POST requests to on_post_{suffix}(), etc.
Returns: A mapping of HTTP methods to explicitly defined resource responders.
Return type: dict

falcon.routing.set_default_responders(method_map, asgi=False)[source]¶

Map HTTP methods not explicitly defined on a resource to default responders.

Parameters

method_map – A dict with HTTP methods mapped to responders explicitly defined in a resource.
asgi (bool) – True if using an ASGI app, False otherwise (default False).

falcon.routing.compile_uri_template(template)[source]¶

Compile the given URI template string into a pattern matcher.

This function can be used to construct custom routing engines that iterate through a list of possible routes, attempting to match an incoming request against each route’s compiled regular expression.

Each field is converted to a named group, so that when a match is found, the fields can be easily extracted using re.MatchObject.groupdict().

This function does not support the more flexible templating syntax used in the default router. Only simple paths with bracketed field expressions are recognized. For example:

/
/books
/books/{isbn}
/books/{isbn}/characters
/books/{isbn}/characters/{name}

Warning

If the template contains a trailing slash character, it will be stripped.

Note that this is different from the default behavior of add_route() used with the default CompiledRouter.

The strip_url_path_trailing_slash request option is not considered by compile_uri_template().

Parameters: template (str) – The template to compile. Note that field names are restricted to ASCII a-z, A-Z, and the underscore character.
Returns: (template_field_names, template_regex)
Return type: tuple

Deprecated since version 3.1.

falcon.app_helpers.prepare_middleware(middleware, independent_middleware=False, asgi=False)[source]¶

Check middleware interfaces and prepare the methods for request handling.

Note

This method is only applicable to WSGI apps.

Parameters

middleware (iterable) – An iterable of middleware objects.

Keyword Arguments

independent_middleware (bool) – True if the request and response middleware methods should be treated independently (default False)
asgi (bool) – True if an ASGI app, False otherwise (default False)

Returns

A tuple of prepared middleware method tuples

Return type

tuple

falcon.app_helpers.prepare_middleware_ws(middleware)[source]¶

Check middleware interfaces and prepare WebSocket methods for request handling.

Note

This method is only applicable to ASGI apps.

Parameters: middleware (iterable) – An iterable of middleware objects.
Returns: A two-item (request_mw, resource_mw) tuple, where request_mw is an ordered list of process_request_ws() methods, and resource_mw is an ordered list of process_resource_ws() methods.
Return type: tuple

Custom HTTP Methods ¶

While not normally advised, some applications may need to support non-standard HTTP methods, in addition to the standard HTTP methods like GET and PUT. To support custom HTTP methods, use one of the following methods:

Ideally, if you don’t use hooks in your application, you can easily add the custom methods in your application setup by overriding the value of falcon.constants.COMBINED_METHODS. For example:
```
import falcon.constants
falcon.constants.COMBINED_METHODS += ['FOO', 'BAR']
```
Due to the nature of hooks, if you do use them, you’ll need to define the FALCON_CUSTOM_HTTP_METHODS environment variable as a comma-delimited list of custom methods. For example:
```
$ export FALCON_CUSTOM_HTTP_METHODS=FOO,BAR
```

Once you have used the appropriate method, your custom methods should be active. You then can define request methods like any other HTTP method:

# Handle the custom FOO method
def on_foo(self, req, resp):
    pass

# Handle the custom FOO method
async def on_foo(self, req, resp):
    pass

Inspect Module¶

Using Inspect Functions
Inspect Functions Reference
Router Inspection
Information Classes
Visitor Classes

This module can be used to inspect a Falcon application to obtain information about its registered routes, middleware objects, static routes, sinks and error handlers. The entire application can be inspected at once using the inspect_app() function. Additional functions are available for inspecting specific aspects of the app.

A falcon-inspect-app CLI script is also available; it uses the inspect module to print a string representation of an application, as demonstrated below:

# my_module exposes the application as a variable named "app"
$ falcon-inspect-app my_module:app

Falcon App (WSGI)
• Routes:
    ⇒ /foo - MyResponder:
       ├── DELETE - on_delete
       ├── GET - on_get
       └── POST - on_post
    ⇒ /foo/{id} - MyResponder:
       ├── DELETE - on_delete_id
       ├── GET - on_get_id
       └── POST - on_post_id
    ⇒ /bar - OtherResponder:
       ├── DELETE - on_delete_id
       ├── GET - on_get_id
       └── POST - on_post_id
• Middleware (Middleware are independent):
    → MyMiddleware.process_request
      → OtherMiddleware.process_request

        ↣ MyMiddleware.process_resource
          ↣ OtherMiddleware.process_resource

              ├── Process route responder

          ↢ OtherMiddleware.process_response
        ↢ CORSMiddleware.process_response
• Static routes:
    ↦ /tests/ /path/to/tests [/path/to/test/index.html]
    ↦ /falcon/ /path/to/falcon
• Sinks:
    ⇥ /sink_cls SinkClass
    ⇥ /sink_fn sinkFn
• Error handlers:
    ⇜ RuntimeError my_runtime_handler

The example above shows how falcon-inspect-app simply outputs the value returned by the AppInfo.to_string() method. In fact, here is a simple script that returns the same output as the falcon-inspect-app command:

from falcon import inspect
from my_module import app

app_info = inspect.inspect_app(app)

# Equivalent to print(app_info.to_string())
print(app_info)

A more verbose description of the app can be obtained by passing verbose=True to AppInfo.to_string(), while the default routes added by the framework can be included by passing internal=True. The falcon-inspect-app command supports the --verbose and --internal flags to enable these options.

Using Inspect Functions¶

The values returned by the inspect functions are class instances that contain the relevant information collected from the application. These objects facilitate programmatic use of the collected data.

To support inspection of applications that use a custom router, the module provides a register_router() function to register a handler function for the custom router class. Inspection of the default CompiledRouter class is handled by the inspect_compiled_router() function.

The returned information classes can be explored using the visitor pattern. To create the string representation of the classes the StringVisitor visitor is used. This class is instantiated automatically when calling str() on an instance or when using the to_string() method.

Custom visitor implementations can subclass InspectVisitor and use the InspectVisitor.process() method to visit the classes.

Inspect Functions Reference¶

This module defines the following inspect functions.

falcon.inspect.inspect_app(app: App) → AppInfo[source]¶

Inspects an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: The information regarding the application. Call to_string() on the result to obtain a human-friendly representation.
Return type: AppInfo

falcon.inspect.inspect_routes(app: App) → List[RouteInfo][source]¶

Inspects the routes of an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: A list of route descriptions for the application.
Return type: List[RouteInfo]

falcon.inspect.inspect_middleware(app: App) → MiddlewareInfo[source]¶

Inspects the middleware components of an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: Information about the app’s middleware components.
Return type: MiddlewareInfo

falcon.inspect.inspect_static_routes(app: App) → List[StaticRouteInfo][source]¶

Inspects the static routes of an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: A list of static routes that have been added to the application.
Return type: List[StaticRouteInfo]

falcon.inspect.inspect_sinks(app: App) → List[SinkInfo][source]¶

Inspects the sinks of an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: A list of sinks used by the application.
Return type: List[SinkInfo]

falcon.inspect.inspect_error_handlers(app: App) → List[ErrorHandlerInfo][source]¶

Inspects the error handlers of an application.

Parameters: app (falcon.App) – The application to inspect. Works with both falcon.App and falcon.asgi.App.
Returns: A list of error handlers used by the application.
Return type: List[ErrorHandlerInfo]

Router Inspection¶

The following functions enable route inspection.

falcon.inspect.register_router(router_class)[source]¶

Register a function to inspect a particular router.

This decorator registers a new function for a custom router class, so that it can be inspected with the function inspect_routes(). An inspection function takes the router instance used by the application and returns a list of RouteInfo. Eg:

@register_router(MyRouterClass)
def inspect_my_router(router):
    return [RouteInfo('foo', 'bar', '/path/to/foo.py:42', [])]

Parameters: router_class (Type) – The router class to register. If already registered an error will be raised.

falcon.inspect.inspect_compiled_router(router: CompiledRouter) → List[RouteInfo][source]¶

Walk an instance of CompiledRouter to return a list of defined routes.

Default route inspector for CompiledRouter.

Parameters: router (CompiledRouter) – The router to inspect.
Returns: A list of RouteInfo.
Return type: List[RouteInfo]

Information Classes¶

Information returned by the inspect functions is represented by these classes.

class falcon.inspect.AppInfo(routes: List[RouteInfo], middleware: MiddlewareInfo, static_routes: List[StaticRouteInfo], sinks: List[SinkInfo], error_handlers: List[ErrorHandlerInfo], asgi: bool)[source]¶

Describes an application.

Parameters

routes (List[RouteInfo]) – The routes of the application.
middleware (MiddlewareInfo) – The middleware information in the application.
static_routes (List[StaticRouteInfo]) – The static routes of this application.
sinks (List[SinkInfo]) – The sinks of this application.
error_handlers (List[ErrorHandlerInfo]) – The error handlers of this application.
asgi (bool) – Whether or not this is an ASGI application.

to_string(verbose=False, internal=False, name='') → str[source]¶

Return a string representation of this class.

Parameters

verbose (bool, optional) – Adds more information. Defaults to False.
internal (bool, optional) – Also include internal falcon route methods and error handlers. Defaults to False.
name (str, optional) – The name of the application, to be output at the beginning of the text. Defaults to 'Falcon App'.

Returns

A string representation of the application.

Return type

class falcon.inspect.RouteInfo(path: str, class_name: str, source_info: str, methods: List[RouteMethodInfo])[source]¶

Describes a route.

Parameters

path (str) – The path of this route.
class_name (str) – The class name of the responder of this route.
source_info (str) – The source path where this responder was defined.
methods (List[RouteMethodInfo]) – List of methods defined in the route.

class falcon.inspect.RouteMethodInfo(method: str, source_info: str, function_name: str, internal: bool)[source]¶

Describes a responder method.

Parameters

method (str) – The HTTP method of this responder.
source_info (str) – The source path of this function.
function_name (str) – Name of the function.
internal (bool) – Whether or not this was a default responder added by the framework.

suffix¶

The suffix of this route function. This is set to an empty string when the function has no suffix.

Type: str

class falcon.inspect.MiddlewareInfo(middleware_tree: MiddlewareTreeInfo, middleware_classes: List[MiddlewareClassInfo], independent: bool)[source]¶

Describes the middleware of the app.

Parameters

middlewareTree (MiddlewareTreeInfo) – The middleware tree of the app.
middlewareClasses (List[MiddlewareClassInfo]) – The middleware classes of the app.
independent (bool) – Whether or not the middleware components are executed independently.

independent_text¶

Text created from the independent arg.

Type: str

class falcon.inspect.MiddlewareTreeInfo(request: List[MiddlewareTreeItemInfo], resource: List[MiddlewareTreeItemInfo], response: List[MiddlewareTreeItemInfo])[source]¶

Describes the middleware methods used by the app.

Parameters

request (List[MiddlewareTreeItemInfo]) – The process_request methods.
resource (List[MiddlewareTreeItemInfo]) – The process_resource methods.
response (List[MiddlewareTreeItemInfo]) – The process_response methods.

class falcon.inspect.MiddlewareClassInfo(name: str, source_info: str, methods: List[MiddlewareMethodInfo])[source]¶

Describes a middleware class.

Parameters

name (str) – The name of the middleware class.
source_info (str) – The source path where the middleware was defined.
methods (List[MiddlewareMethodInfo]) – List of method defined by the middleware class.

class falcon.inspect.MiddlewareTreeItemInfo(name: str, class_name: str)[source]¶

Describes a middleware tree entry.

Parameters

name (str) – The name of the method.
class_name (str) – The class name of the method.

class falcon.inspect.MiddlewareMethodInfo(function_name: str, source_info: str)[source]¶

Describes a middleware method.

Parameters

function_name (str) – Name of the method.
source_info (str) – The source path of the method.

class falcon.inspect.StaticRouteInfo(prefix: str, directory: str, fallback_filename: Optional[str])[source]¶

Describes a static route.

Parameters

path (str) – The prefix of the static route.
directory (str) – The directory for the static route.
fallback_filename (str or None) – Fallback filename to serve.

class falcon.inspect.SinkInfo(prefix: str, name: str, source_info: str)[source]¶

Describes a sink.

Parameters

prefix (str) – The prefix of the sink.
name (str) – The name of the sink function or class.
source_info (str) – The source path where this sink was defined.

class falcon.inspect.ErrorHandlerInfo(error: str, name: str, source_info: str, internal: bool)[source]¶

Desribes an error handler.

Parameters

error (name) – The name of the error type.
name (str) – The name of the handler.
source_info (str) – The source path where this error handler was defined.
internal (bool) – Whether or not this is a default error handler added by the framework.

Visitor Classes¶

The following visitors are used to traverse the information classes.

class falcon.inspect.InspectVisitor[source]¶

Base visitor class that implements the process method.

Subclasses must implement visit_<name> methods for each supported class.

process(instance: _Traversable)[source]¶

Process the instance, by calling the appropriate visit method.

Uses the __visit_name__ attribute of the instance to obtain the method to use.

Parameters: instance (_Traversable) – The instance to process.

class falcon.inspect.StringVisitor(verbose=False, internal=False, name='')[source]¶

Visitor that returns a string representation of the info class.

This is used automatically by calling to_string() on the info class. It can also be used directly by calling StringVisitor.process(info_instance).

Parameters

verbose (bool, optional) – Adds more information. Defaults to False.
internal (bool, optional) – Also include internal route methods and error handlers added by the framework. Defaults to False.
name (str, optional) – The name of the application, to be output at the beginning of the text. Defaults to 'Falcon App'.

Utilities¶

URI
Date and Time
HTTP Status
Async
- Aliases
- Adapters
Other

URI ¶

URI utilities.

This module provides utility functions to parse, encode, decode, and otherwise manipulate a URI. These functions are not available directly in the falcon module, and so must be explicitly imported:

from falcon import uri

name, port = uri.parse_host('example.org:8080')

falcon.uri.decode(encoded_uri, unquote_plus=True)[source]¶

Decode percent-encoded characters in a URI or query string.

This function models the behavior of urllib.parse.unquote_plus, albeit in a faster, more straightforward manner.

Parameters: encoded_uri (str) – An encoded URI (full or partial).
Keyword Arguments: unquote_plus (bool) – Set to False to retain any plus (‘+’) characters in the given string, rather than converting them to spaces (default True). Typically you should set this to False when decoding any part of a URI other than the query string.
Returns: A decoded URL. If the URL contains escaped non-ASCII characters, UTF-8 is assumed per RFC 3986.
Return type: str

falcon.uri.encode(uri)¶

Encodes a full or relative URI according to RFC 3986.

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. This function escapes all other “disallowed” characters by percent-encoding them.

Note

This utility is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

Parameters: uri (str) – URI or part of a URI to encode.
Returns: An escaped version of uri, where all disallowed characters have been percent-encoded.
Return type: str

falcon.uri.encode_check_escaped(uri)¶

Encodes a full or relative URI according to RFC 3986.

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. This function escapes all other “disallowed” characters by percent-encoding them unless they appear to have been previously encoded. For example, '%26' will not be encoded again as it follows the format of an encoded value.

Note

This utility is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

Parameters: uri (str) – URI or part of a URI to encode.
Returns: An escaped version of uri, where all disallowed characters have been percent-encoded.
Return type: str

falcon.uri.encode_value(uri)¶

Encodes a value string according to RFC 3986.

Disallowed characters are percent-encoded in a way that models urllib.parse.quote(safe="~"). However, the Falcon function is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

All reserved characters are lumped together into a single set of “delimiters”, and everything in that set is escaped.

Note

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters.

Parameters: uri (str) – URI fragment to encode. It is assumed not to cross delimiter boundaries, and so any reserved URI delimiter characters included in it will be percent-encoded.
Returns: An escaped version of uri, where all disallowed characters have been percent-encoded.
Return type: str

falcon.uri.encode_value_check_escaped(uri)¶

Encodes a value string according to RFC 3986.

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. Disallowed characters are percent-encoded in a way that models urllib.parse.quote(safe="~") unless they appear to have been previously encoded. For example, '%26' will not be encoded again as it follows the format of an encoded value.

All reserved characters are lumped together into a single set of “delimiters”, and everything in that set is escaped.

Note

This utility is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

Parameters: uri (str) – URI fragment to encode. It is assumed not to cross delimiter boundaries, and so any reserved URI delimiter characters included in it will be percent-encoded.
Returns: An escaped version of uri, where all disallowed characters have been percent-encoded.
Return type: str

falcon.uri.parse_host(host, default_port=None)[source]¶

Parse a canonical ‘host:port’ string into parts.

Parse a host string (which may or may not contain a port) into parts, taking into account that the string may contain either a domain name or an IP address. In the latter case, both IPv4 and IPv6 addresses are supported.

Parameters: host (str) – Host string to parse, optionally containing a port number.
Keyword Arguments: default_port (int) – Port number to return when the host string does not contain one (default None).
Returns: A parsed (host, port) tuple from the given host string, with the port converted to an int. If the host string does not specify a port, default_port is used instead.
Return type: tuple

falcon.uri.parse_query_string(query_string, keep_blank=False, csv=True)[source]¶

Parse a query string into a dict.

Query string parameters are assumed to use standard form-encoding. Only parameters with values are returned. For example, given ‘foo=bar&flag’, this function would ignore ‘flag’ unless the keep_blank_qs_values option is set.

Note

In addition to the standard HTML form-based method for specifying lists by repeating a given param multiple times, Falcon supports a more compact form in which the param may be given a single time but set to a list of comma-separated elements (e.g., ‘foo=a,b,c’).

When using this format, all commas uri-encoded will not be treated by Falcon as a delimiter. If the client wants to send a value as a list, it must not encode the commas with the values.

The two different ways of specifying lists may not be mixed in a single query string for the same parameter.

Parameters

query_string (str) – The query string to parse.
keep_blank (bool) – Set to True to return fields even if they do not have a value (default False). For comma-separated values, this option also determines whether or not empty elements in the parsed list are retained.
csv – Set to False in order to disable splitting query parameters on , (default True). Depending on the user agent, encoding lists as multiple occurrences of the same parameter might be preferable. In this case, setting parse_qs_csv to False will cause the framework to treat commas as literal characters in each occurring parameter value.

Returns

A dictionary of (name, value) pairs, one per query parameter. Note that value may be a single str, or a list of str.

Return type

dict

Raises

TypeError – query_string was not a str.

falcon.uri.unquote_string(quoted)[source]¶

Unquote an RFC 7320 “quoted-string”.

Parameters: quoted (str) – Original quoted string
Returns: unquoted string
Return type: str
Raises: TypeError – quoted was not a str.

Date and Time ¶

falcon.http_now()[source]¶

Return the current UTC time as an IMF-fixdate.

Returns: The current UTC time as an IMF-fixdate, e.g., ‘Tue, 15 Nov 1994 12:45:26 GMT’.
Return type: str

falcon.dt_to_http(dt)[source]¶

Convert a datetime instance to an HTTP date string.

Parameters: dt (datetime) – A datetime instance to convert, assumed to be UTC.
Returns: An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”.
Return type: str

falcon.http_date_to_dt(http_date, obs_date=False)[source]¶

Convert an HTTP date string to a datetime instance.

Parameters: http_date (str) – An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”.
Keyword Arguments: obs_date (bool) – Support obs-date formats according to RFC 7231, e.g.: “Sunday, 06-Nov-94 08:49:37 GMT” (default False).
Returns: A UTC datetime instance corresponding to the given HTTP date.
Return type: datetime
Raises: ValueError – http_date doesn’t match any of the available time formats

class falcon.TimezoneGMT[source]¶

GMT timezone class implementing the datetime.tzinfo interface.

dst(dt)[source]¶

Return the daylight saving time (DST) adjustment.

Parameters: dt (datetime.datetime) – Ignored
Returns: DST adjustment for GMT, which is always 0.
Return type: datetime.timedelta

tzname(dt)[source]¶

Get the name of this timezone.

Parameters: dt (datetime.datetime) – Ignored
Returns: “GMT”
Return type: str

utcoffset(dt)[source]¶

Get the offset from UTC.

Parameters: dt (datetime.datetime) – Ignored
Returns: GMT offset, which is equivalent to UTC and so is aways 0.
Return type: datetime.timedelta

HTTP Status ¶

falcon.http_status_to_code(status)[source]¶

Normalize an HTTP status to an integer code.

This function takes a member of http.HTTPStatus, an HTTP status line string or byte string (e.g., '200 OK'), or an int and returns the corresponding integer code.

An LRU is used to minimize lookup time.

Parameters: status – The status code or enum to normalize.
Returns: Integer code for the HTTP status (e.g., 200)
Return type: int

falcon.code_to_http_status(status)[source]¶

Normalize an HTTP status to an HTTP status line string.

This function takes a member of http.HTTPStatus, an int status code, an HTTP status line string or byte string (e.g., '200 OK') and returns the corresponding HTTP status line string.

An LRU is used to minimize lookup time.

Note

Unlike the deprecated get_http_status(), this function will not attempt to coerce a string status to an integer code, assuming the string already denotes an HTTP status line.

Parameters

status – The status code or enum to normalize.

Returns

HTTP status line corresponding to the given code. A newline: is not included at the end of the string.

Return type

falcon.get_http_status(status_code, default_reason='Unknown')[source]¶

Get both the http status code and description from just a code.

Warning

As of Falcon 3.0, this method has been deprecated in favor of code_to_http_status().

Parameters

status_code – integer or string that can be converted to an integer
default_reason – default text to be appended to the status_code if the lookup does not find a result

Returns

status code e.g. “404 Not Found”

Return type

Raises

ValueError – the value entered could not be converted to an integer

Async ¶

Aliases ¶

These functions provide simple aliases for those implemented in asyncio, with fallbacks for older versions of Python.

falcon.get_running_loop()¶

Return the running event loop. Raise a RuntimeError if there is none.

This function is thread-specific.

falcon.create_task(coro)[source]¶

Schedule the execution of a coroutine object in a spawn task.

Return a Task object.

Adapters ¶

These functions help traverse the barrier between sync and async code.

async falcon.sync_to_async(func, *args, **kwargs)[source]¶

Schedule a synchronous callable on the default executor and await the result.

This helper makes it easier to call functions that can not be ported to use async natively (e.g., functions exported by a database library that does not yet support asyncio).

To execute blocking operations safely, without stalling the async loop, the wrapped callable is scheduled to run in the background, on a separate thread, when the wrapper is called.

The default executor for the running loop is used to schedule the synchronous callable.

Warning

This helper can only be used to execute thread-safe callables. If the callable is not thread-safe, it can be executed serially by first wrapping it with wrap_sync_to_async(), and then executing the wrapper directly.

Warning

Calling a synchronous function safely from an asyncio event loop adds a fair amount of overhead to the function call, and should only be used when a native async library is not available for the operation you wish to perform.

Parameters

func (callable) – Function, method, or other callable to wrap
*args – All additional arguments are passed through to the callable.

Keyword Arguments

**kwargs – All keyword arguments are passed through to the callable.

Returns

An awaitable coroutine function that wraps the synchronous callable.

Return type

function

falcon.wrap_sync_to_async(func, threadsafe=None) → Callable[source]¶

Wrap a callable in a coroutine that executes the callable in the background.

This helper makes it easier to call functions that can not be ported to use async natively (e.g., functions exported by a database library that does not yet support asyncio).

To execute blocking operations safely, without stalling the async loop, the wrapped callable is scheduled to run in the background, on a separate thread, when the wrapper is called.

Normally, the default executor for the running loop is used to schedule the synchronous callable. If the callable is not thread-safe, it can be scheduled serially in a global single-threaded executor.

Warning

Wrapping a synchronous function safely adds a fair amount of overhead to the function call, and should only be used when a native async library is not available for the operation you wish to perform.

Parameters: func (callable) – Function, method, or other callable to wrap
Keyword Arguments: threadsafe (bool) – Set to False when the callable is not thread-safe (default True). When this argument is False, the wrapped callable will be scheduled to run serially in a global single-threaded executor.
Returns: An awaitable coroutine function that wraps the synchronous callable.
Return type: function

falcon.wrap_sync_to_async_unsafe(func) → Callable[source]¶

Wrap a callable in a coroutine that executes the callable directly.

This helper makes it easier to use synchronous callables with ASGI apps. However, it is considered “unsafe” because it calls the wrapped function directly in the same thread as the asyncio loop. Generally, you should use wrap_sync_to_async() instead.

Warning

This helper is only to be used for functions that do not perform any blocking I/O or lengthy CPU-bound operations, since the entire async loop will be blocked while the wrapped function is executed. For a safer, non-blocking alternative that runs the function in a thread pool executor, use sync_to_async() instead.

Parameters: func (callable) – Function, method, or other callable to wrap
Returns: An awaitable coroutine function that wraps the synchronous callable.
Return type: function

falcon.async_to_sync(coroutine, *args, **kwargs)[source]¶

Invoke a coroutine function from a synchronous caller.

This method can be used to invoke an asynchronous task from a synchronous context. The coroutine will be scheduled to run on the current event loop for the current OS thread. If an event loop is not already running, one will be created.

Warning

This method is very inefficient and is intended primarily for testing and prototyping.

Parameters

coroutine – A coroutine function to invoke.
*args – Additional args are passed through to the coroutine function.

Keyword Arguments

**kwargs – Additional args are passed through to the coroutine function.

falcon.runs_sync(coroutine)[source]¶

Transform a coroutine function into a synchronous method.

This is achieved by always invoking the decorated coroutine function via async_to_sync().

Warning

This decorator is very inefficient and should only be used for adapting asynchronous test functions for use with synchronous test runners such as pytest or the unittest module.

It will create an event loop for the current thread if one is not already running.

Parameters: coroutine – A coroutine function to masquerade as a synchronous one.
Returns: A synchronous function.
Return type: callable

Other ¶

falcon.deprecated(instructions, is_property=False, method_name=None)[source]¶

Flag a method as deprecated.

This function returns a decorator which can be used to mark deprecated functions. Applying this decorator will result in a warning being emitted when the function is used.

Parameters

instructions (str) – Specific guidance for the developer, e.g.: ‘Please migrate to add_proxy(…)’.
is_property (bool) – If the deprecated object is a property. It will omit the (...) from the generated documentation.
method_name (str, optional) – Set to override the name of the deprecated function or property in the generated documentation (default None). This is useful when decorating an alias that carries the target’s __name__.

falcon.to_query_str(params, comma_delimited_lists=True, prefix=True)[source]¶

Convert a dictionary of parameters to a query string.

Parameters

params (dict) – A dictionary of parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
comma_delimited_lists (bool) – Set to False to encode list values by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Otherwise, parameters will be encoded as comma-separated values (e.g., ‘thing=1,2,3’). Defaults to True.
prefix (bool) – Set to False to exclude the ‘?’ prefix in the result string (default True).

Returns

A URI query string, including the ‘?’ prefix (unless prefix is False), or an empty string if no params are given (the dict is empty).

Return type

falcon.get_bound_method(obj, method_name)[source]¶

Get a bound method of the given object by name.

Parameters

obj – Object on which to look up the method.
method_name – Name of the method to retrieve.

Returns

Bound method, or None if the method does not exist on the object.

Raises

AttributeError – The method exists, but it isn’t bound (most likely a class was passed, rather than an instance of that class).

falcon.secure_filename(filename)[source]¶

Sanitize the provided filename to contain only ASCII characters.

Only ASCII alphanumerals, '.', '-' and '_' are allowed for maximum portability and safety wrt using this name as a filename on a regular file system. All other characters will be replaced with an underscore ('_').

Note

The filename is normalized to the Unicode NKFD form prior to ASCII conversion in order to extract more alphanumerals where a decomposition is available. For instance:

>>> secure_filename('Bold Digit 𝟏')
'Bold_Digit_1'
>>> secure_filename('Ångström unit physics.pdf')
'A_ngstro_m_unit_physics.pdf'

Parameters: filename (str) – Arbitrary filename input from the request, such as a multipart form filename field.
Returns: The sanitized filename.
Return type: str
Raises: ValueError – the provided filename is an empty string.

falcon.is_python_func(func)[source]¶

Determine if a function or method uses a standard Python type.

This helper can be used to check a function or method to determine if it uses a standard Python type, as opposed to an implementation-specific native extension type.

For example, because Cython functions are not standard Python functions, is_python_func(f) will return False when f is a reference to a cythonized function or method.

Parameters: func – The function object to check.
Returns: True if the function or method uses a standard Python type; False otherwise.
Return type: bool

class falcon.Context[source]¶

Convenience class to hold contextual information in its attributes.

This class is used as the default Request and Response context type (see Request.context_type and Response.context_type, respectively).

In Falcon versions prior to 2.0, the default context type was dict. To ease the migration to attribute-based context object approach, this class also implements the mapping interface; that is, object attributes are linked to dictionary items, and vice versa. For instance:

>>> context = falcon.Context()
>>> context.cache_strategy = 'lru'
>>> context.get('cache_strategy')
'lru'
>>> 'cache_strategy' in context
True

class falcon.ETag[source]¶

Convenience class to represent a parsed HTTP entity-tag.

This class is simply a subclass of str with a few helper methods and an extra attribute to indicate whether the entity-tag is weak or strong. The value of the string is equivalent to what RFC 7232 calls an “opaque-tag”, i.e. an entity-tag sans quotes and the weakness indicator.

Note

Given that a weak entity-tag comparison can be performed by using the == operator (per the example below), only a strong_compare() method is provided.

Here is an example on_get() method that demonstrates how to use instances of this class:

def on_get(self, req, resp):
    content_etag = self._get_content_etag()
    for etag in (req.if_none_match or []):
        if etag == '*' or etag == content_etag:
            resp.status = falcon.HTTP_304
            return

    # -- snip --

    resp.etag = content_etag
    resp.status = falcon.HTTP_200

(See also: RFC 7232)

is_weak¶

True if the entity-tag is weak, otherwise False.

Type: bool

dumps()[source]¶

Serialize the ETag to a string suitable for use in a precondition header.

(See also: RFC 7232, Section 2.3)

Returns: An opaque quoted string, possibly prefixed by a weakness indicator W/.
Return type: str

classmethod loads(etag_str)[source]¶

Deserialize a single entity-tag string from a precondition header.

Note

This method is meant to be used only for parsing a single entity-tag. It can not be used to parse a comma-separated list of values.

(See also: RFC 7232, Section 2.3)

Parameters: etag_str (str) – An ASCII string representing a single entity-tag, as defined by RFC 7232.
Returns: An instance of ~.ETag representing the parsed entity-tag.
Return type: ETag

strong_compare(other)[source]¶

Perform a strong entity-tag comparison.

Two entity-tags are equivalent if both are not weak and their opaque-tags match character-by-character.

(See also: RFC 7232, Section 2.3.2)

Parameters

other (ETag) – The other ETag to which you are comparing
one. (this) –

Returns

True if the two entity-tags match, otherwise False.

Return type

bool

Testing Helpers¶

Simulating Requests
Other Helpers
- Test Cases
- Functions

Functional testing framework for Falcon apps and Falcon itself.

Falcon’s testing module contains various test classes and utility functions to support functional testing for both Falcon-based apps and the Falcon framework itself.

The testing framework supports both unittest and pytest:

# -----------------------------------------------------------------
# unittest
# -----------------------------------------------------------------

from falcon import testing
import myapp


class MyTestCase(testing.TestCase):
    def setUp(self):
        super(MyTestCase, self).setUp()

        # Assume the hypothetical `myapp` package has a
        # function called `create()` to initialize and
        # return a `falcon.App` instance.
        self.app = myapp.create()


class TestMyApp(MyTestCase):
    def test_get_message(self):
        doc = {'message': 'Hello world!'}

        result = self.simulate_get('/messages/42')
        self.assertEqual(result.json, doc)


# -----------------------------------------------------------------
# pytest
# -----------------------------------------------------------------

from falcon import testing
import pytest

import myapp


# Depending on your testing strategy and how your application
# manages state, you may be able to broaden the fixture scope
# beyond the default 'function' scope used in this example.

@pytest.fixture()
def client():
    # Assume the hypothetical `myapp` package has a function called
    # `create()` to initialize and return a `falcon.App` instance.
    return testing.TestClient(myapp.create())


def test_get_message(client):
    doc = {'message': 'Hello world!'}

    result = client.simulate_get('/messages/42')
    assert result.json == doc

Simulating Requests ¶

Main Interface ¶

class falcon.testing.TestClient(app, headers=None)[source]¶

Simulate requests to a WSGI or ASGI application.

This class provides a contextual wrapper for Falcon’s simulate_*() test functions. It lets you replace this:

simulate_get(app, '/messages')
simulate_head(app, '/messages')

with this:

client = TestClient(app)
client.simulate_get('/messages')
client.simulate_head('/messages')

For convenience, TestClient also exposes shorthand aliases without the simulate_ prefix. Just as with a typical Python HTTP client, it is possible to simply call:

client = TestClient(app)
client.get('/messages')
client.request('LOCK', '/files/first')

Note

The methods all call self.simulate_request() for convenient overriding of request preparation by child classes.

Note

In the case of an ASGI request, this class will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

An instance of ASGIConductor may be instantiated directly, or obtained from an instance of TestClient using the context manager pattern, as per the following example:

client = falcon.testing.TestClient(app)

# -- snip --

async with client as conductor:
    async with conductor.simulate_get_stream('/events') as result:
        pass

Parameters: app (callable) – A WSGI or ASGI application to target when simulating requests
Keyword Arguments: headers (dict) – Default headers to set on every request (default None). These defaults may be overridden by passing values for the same headers to one of the simulate_*() methods.

app¶: The app that this client instance was configured to use.

delete(*args, **kwargs) → _ResultBase¶

Simulate a DELETE request to a WSGI application.

New in version 3.1.

get(*args, **kwargs) → _ResultBase¶

Simulate a GET request to a WSGI application.

New in version 3.1.

head(*args, **kwargs) → _ResultBase¶

Simulate a HEAD request to a WSGI application.

New in version 3.1.

options(*args, **kwargs) → _ResultBase¶

Simulate an OPTIONS request to a WSGI application.

New in version 3.1.

patch(*args, **kwargs) → _ResultBase¶

Simulate a PATCH request to a WSGI application.

New in version 3.1.

post(*args, **kwargs) → _ResultBase¶

Simulate a POST request to a WSGI application.

New in version 3.1.

put(*args, **kwargs) → _ResultBase¶

Simulate a PUT request to a WSGI application.

New in version 3.1.

request(*args, **kwargs) → _ResultBase¶

Simulate a request to a WSGI application.

Wraps falcon.testing.simulate_request() to perform a WSGI request directly against self.app. Equivalent to:

falcon.testing.simulate_request(self.app, *args, **kwargs)

New in version 3.1.

simulate_delete(path='/', **kwargs) → _ResultBase[source]¶

Simulate a DELETE request to a WSGI application.

simulate_get(path='/', **kwargs) → _ResultBase[source]¶

Simulate a GET request to a WSGI application.

simulate_head(path='/', **kwargs) → _ResultBase[source]¶

Simulate a HEAD request to a WSGI application.

simulate_options(path='/', **kwargs) → _ResultBase[source]¶

Simulate an OPTIONS request to a WSGI application.

simulate_patch(path='/', **kwargs) → _ResultBase[source]¶

Simulate a PATCH request to a WSGI application.

simulate_post(path='/', **kwargs) → _ResultBase[source]¶

Simulate a POST request to a WSGI application.

simulate_put(path='/', **kwargs) → _ResultBase[source]¶

Simulate a PUT request to a WSGI application.

simulate_request(*args, **kwargs) → _ResultBase[source]¶

Simulate a request to a WSGI application.

Wraps falcon.testing.simulate_request() to perform a WSGI request directly against self.app. Equivalent to:

falcon.testing.simulate_request(self.app, *args, **kwargs)

class falcon.testing.ASGIConductor(app, headers=None)[source]¶

Test conductor for ASGI apps.

This class provides more control over the lifecycle of a simulated request as compared to TestClient. In addition, the conductor’s asynchronous interface affords interleaved requests and the testing of streaming protocols such as Server-Sent Events (SSE) and WebSocket.

ASGIConductor is implemented as a context manager. Upon entering and exiting the context, the appropriate ASGI lifespan events will be simulated.

Within the context, HTTP requests can be simulated using an interface that is similar to TestClient, except that all simulate_*() methods are coroutines:

async with testing.ASGIConductor(some_app) as conductor:
    async def post_events():
        for i in range(100):
            await conductor.simulate_post('/events', json={'id': i}):
            await asyncio.sleep(0.01)

    async def get_events_sse():
        # Here, we will get only some of the single server-sent events
        # because the non-streaming method is "single-shot". In other
        # words, simulate_get() will emit a client disconnect event
        # into the app before returning.
        result = await conductor.simulate_get('/events')

        # Alternatively, we can use simulate_get_stream() as a context
        # manager to perform a series of reads on the result body that
        # are interleaved with the execution of the post_events()
        # coroutine.
        async with conductor.simulate_get_stream('/events') as sr:
            while some_condition:
                # Read next body chunk that was received (if any).
                chunk = await sr.stream.read()

                if chunk:
                    # TODO: Do something with the chunk
                    pass

            # Exiting the context causes the request event emitter to
            # begin emitting ``'http.disconnect'`` events and then awaits
            # the completion of the asyncio task that is running the
            # simulated ASGI request.

    asyncio.gather(post_events(), get_events_sse())

Note

Because the ASGIConductor interface uses coroutines, it cannot be used directly with synchronous testing frameworks such as pytest.

As a workaround, the test can be adapted by wrapping it in an inline async function and then invoking it via falcon.async_to_sync() or decorating the test function with falcon.runs_sync().

Alternatively, you can try searching PyPI to see if an async plugin is available for your testing framework of choice. For example, the pytest-asyncio plugin is available for pytest users.

Similar to the TestClient, ASGIConductor also exposes convenience aliases without the simulate_ prefix. Just as with a typical asynchronous HTTP client, it is possible to simply invoke:

await conductor.get('/messages')
await conductor.request('LOCK', '/files/first')

Parameters: app (callable) – An ASGI application to target when simulating requests.
Keyword Arguments: headers (dict) – Default headers to set on every request (default None). These defaults may be overridden by passing values for the same headers to one of the simulate_*() methods.

app¶: The app that this client instance was configured to use.

async delete(*args, **kwargs) → _ResultBase¶

Simulate a DELETE request to an ASGI application.

New in version 3.1.

async get(*args, **kwargs) → _ResultBase¶

Simulate a GET request to an ASGI application.

New in version 3.1.

get_stream(*args, **kwargs)¶

Simulate a GET request to an ASGI application with a streamed response.

(See also: falcon.testing.simulate_get() for a list of supported keyword arguments.)

This method returns an async context manager that can be used to obtain a managed StreamedResult instance. Exiting the context will automatically finalize the result object, causing the request event emitter to begin emitting 'http.disconnect' events and then await the completion of the task that is running the simulated ASGI request.

In the following example, a series of streamed body chunks are read from the response:

async with conductor.get_stream('/events') as sr:
    while some_condition:
        # Read next body chunk that was received (if any).
        chunk = await sr.stream.read()

        if chunk:
            # TODO: Do something with the chunk. For example,
            #   a series of server-sent events could be validated
            #   by concatenating the chunks and splitting on
            #   double-newlines to obtain individual events.
            pass

New in version 3.1.

async head(*args, **kwargs) → _ResultBase¶

Simulate a HEAD request to an ASGI application.

New in version 3.1.

async options(*args, **kwargs) → _ResultBase¶

Simulate an OPTIONS request to an ASGI application.

New in version 3.1.

async patch(*args, **kwargs) → _ResultBase¶

Simulate a PATCH request to an ASGI application.

New in version 3.1.

async post(*args, **kwargs) → _ResultBase¶

Simulate a POST request to an ASGI application.

New in version 3.1.

async put(*args, **kwargs) → _ResultBase¶

Simulate a PUT request to an ASGI application.

New in version 3.1.

async request(*args, **kwargs) → _ResultBase¶

Simulate a request to an ASGI application.

Wraps falcon.testing.simulate_request() to perform a WSGI request directly against self.app. Equivalent to:

falcon.testing.simulate_request(self.app, *args, **kwargs)

New in version 3.1.

async simulate_delete(path='/', **kwargs) → _ResultBase[source]¶

Simulate a DELETE request to an ASGI application.

async simulate_get(path='/', **kwargs) → _ResultBase[source]¶

Simulate a GET request to an ASGI application.

simulate_get_stream(path='/', **kwargs)[source]¶

Simulate a GET request to an ASGI application with a streamed response.

(See also: falcon.testing.simulate_get() for a list of supported keyword arguments.)

This method returns an async context manager that can be used to obtain a managed StreamedResult instance. Exiting the context will automatically finalize the result object, causing the request event emitter to begin emitting 'http.disconnect' events and then await the completion of the task that is running the simulated ASGI request.

In the following example, a series of streamed body chunks are read from the response:

async with conductor.simulate_get_stream('/events') as sr:
    while some_condition:
        # Read next body chunk that was received (if any).
        chunk = await sr.stream.read()

        if chunk:
            # TODO: Do something with the chunk. For example,
            #   a series of server-sent events could be validated
            #   by concatenating the chunks and splitting on
            #   double-newlines to obtain individual events.
            pass

async simulate_head(path='/', **kwargs) → _ResultBase[source]¶

Simulate a HEAD request to an ASGI application.

async simulate_options(path='/', **kwargs) → _ResultBase[source]¶

Simulate an OPTIONS request to an ASGI application.

async simulate_patch(path='/', **kwargs) → _ResultBase[source]¶

Simulate a PATCH request to an ASGI application.

async simulate_post(path='/', **kwargs) → _ResultBase[source]¶

Simulate a POST request to an ASGI application.

async simulate_put(path='/', **kwargs) → _ResultBase[source]¶

Simulate a PUT request to an ASGI application.

async simulate_request(*args, **kwargs) → _ResultBase[source]¶

Simulate a request to an ASGI application.

Wraps falcon.testing.simulate_request() to perform a WSGI request directly against self.app. Equivalent to:

falcon.testing.simulate_request(self.app, *args, **kwargs)

simulate_ws(path='/', **kwargs)[source]¶

Simulate a WebSocket connection to an ASGI application.

All keyword arguments are passed through to falcon.testing.create_scope_ws().

This method returns an async context manager that can be used to obtain a managed falcon.testing.ASGIWebSocketSimulator instance. Exiting the context will simulate a close on the WebSocket (if not already closed) and await the completion of the task that is running the simulated ASGI request.

In the following example, a series of WebSocket TEXT events are received from the ASGI app:

async with conductor.simulate_ws('/events') as ws:
    while some_condition:
        message = await ws.receive_text()

websocket(*args, **kwargs)¶

Simulate a WebSocket connection to an ASGI application.

All keyword arguments are passed through to falcon.testing.create_scope_ws().

This method returns an async context manager that can be used to obtain a managed falcon.testing.ASGIWebSocketSimulator instance. Exiting the context will simulate a close on the WebSocket (if not already closed) and await the completion of the task that is running the simulated ASGI request.

In the following example, a series of WebSocket TEXT events are received from the ASGI app:

async with conductor.websocket('/events') as ws:
    while some_condition:
        message = await ws.receive_text()

New in version 3.1.

class falcon.testing.Result(iterable, status, headers)[source]¶

Encapsulates the result of a simulated request.

Parameters

iterable (iterable) – An iterable that yields zero or more bytestrings, per PEP-3333
status (str) – An HTTP status string, including status code and reason string
headers (list) – A list of (header_name, header_value) tuples, per PEP-3333

status¶

HTTP status string given in the response

Type: str

status_code¶

The code portion of the HTTP status string

Type: int

headers¶

A case-insensitive dictionary containing all the headers in the response, except for cookies, which may be accessed via the cookies attribute.

Note

Multiple instances of a header in the response are currently not supported; it is unspecified which value will “win” and be represented in headers.

Type: CaseInsensitiveDict

cookies¶

A dictionary of falcon.testing.Cookie values parsed from the response, by name.

Type: dict

encoding¶

Text encoding of the response body, or None if the encoding can not be determined.

Type: str

content¶

Raw response body, or bytes if the response body was empty.

Type: bytes

text¶

Decoded response body of type str. If the content type does not specify an encoding, UTF-8 is assumed.

Type: str

json¶

Deserialized JSON body. Will be None if the body has no content to deserialize. Otherwise, raises an error if the response is not valid JSON.

Type: JSON serializable

class falcon.testing.StreamedResult(body_chunks, status, headers, task, req_event_emitter)[source]¶

Encapsulates the streamed result of an ASGI request.

Parameters

body_chunks (list) – A list of body chunks. This list may be appended to after a result object has been instantiated.
status (str) – An HTTP status string, including status code and reason string
headers (list) – A list of (header_name, header_value) tuples, per PEP-3333
task (asyncio.Task) – The scheduled simulated request which may or may not have already finished. finalize() will await the task before returning.
req_event_emitter (ASGIRequestEventEmitter) – A reference to the event emitter used to simulate events sent to the ASGI application via its receive() method. finalize() will cause the event emitter to simulate an 'http.disconnect' event before returning.

status¶

HTTP status string given in the response

Type: str

status_code¶

The code portion of the HTTP status string

Type: int

headers¶

A case-insensitive dictionary containing all the headers in the response, except for cookies, which may be accessed via the cookies attribute.

Note

Multiple instances of a header in the response are currently not supported; it is unspecified which value will “win” and be represented in headers.

Type: CaseInsensitiveDict

cookies¶

A dictionary of falcon.testing.Cookie values parsed from the response, by name.

Type: dict

encoding¶

Text encoding of the response body, or None if the encoding can not be determined.

Type: str

stream¶

Raw response body, as a byte stream.

Type: ResultStream

async finalize()[source]¶

Finalize the encapsulated simulated request.

This method causes the request event emitter to begin emitting 'http.disconnect' events and then awaits the completion of the asyncio task that is running the simulated ASGI request.

class falcon.testing.ResultBodyStream(chunks: Sequence[bytes])[source]¶

Simple forward-only reader for a streamed test result body.

Parameters: chunks (list) – Reference to a list of body chunks that may continue to be appended to as more body events are collected.

async read() → bytes[source]¶

Read any data that has been collected since the last call.

Returns: data that has been collected since the last call, or an empty byte string if no additional data is available.
Return type: bytes

class falcon.testing.ASGIWebSocketSimulator[source]¶

Simulates a WebSocket client for testing a Falcon ASGI app.

This class provides a way to test WebSocket endpoints in a Falcon ASGI app without having to interact with an actual ASGI server. While it is certainly important to test against a real server, a number of functional tests can be satisfied more efficiently and transparently with a simulated connection.

Note

The ASGIWebSocketSimulator class is not designed to be instantiated directly; rather it should be obtained via simulate_ws().

ready¶

True if the WebSocket connection has been accepted and the client is still connected, False otherwise.

Type: bool

closed¶

True if the WebSocket connection has been denied or closed by the app, or the client has disconnected.

Type: bool

close_code¶

The WebSocket close code provided by the app if the connection is closed, or None if the connection is open.

Type: int

subprotocol¶

The subprotocol the app wishes to accept, or None if not specified.

Type: str

headers¶

An iterable of [name, value] two-item iterables, where name is the header name, and value is the header value for each header returned by the app when it accepted the WebSocket connection. This property resolves to None if the connection has not been accepted.

Type: Iterable[Iterable[bytes]]

async close(code: Optional[int] = None)[source]¶

Close the simulated connection.

Keyword Arguments: code (int) – The WebSocket close code to send to the application per the WebSocket spec (default: 1000).

async receive_data() → bytes[source]¶

Receive a message from the app with a binary data payload.

Awaiting this coroutine will block until a message is available or the WebSocket is disconnected.

async receive_json() → object[source]¶

Receive a message from the app with a JSON-encoded TEXT payload.

Awaiting this coroutine will block until a message is available or the WebSocket is disconnected.

async receive_msgpack() → object[source]¶

Receive a message from the app with a MessagePack-encoded BINARY payload.

Awaiting this coroutine will block until a message is available or the WebSocket is disconnected.

async receive_text() → str[source]¶

Receive a message from the app with a Unicode string payload.

Awaiting this coroutine will block until a message is available or the WebSocket is disconnected.

async send_data(payload: Union[bytes, bytearray, memoryview])[source]¶

Send a message to the app with a binary data payload.

Parameters: payload (Union[bytes, bytearray, memoryview]) – The binary data to send.

async send_json(media: object)[source]¶

Send a message to the app with a JSON-encoded payload.

Parameters: media – A JSON-encodable object to send as a TEXT (0x01) payload.

async send_msgpack(media: object)[source]¶

Send a message to the app with a MessagePack-encoded payload.

Parameters: media – A MessagePack-encodable object to send as a BINARY (0x02) payload.

async send_text(payload: str)[source]¶

Send a message to the app with a Unicode string payload.

Parameters: payload (str) – The string to send.

async wait_ready(timeout: Optional[int] = 5)[source]¶

Wait until the connection has been accepted or denied.

This coroutine can be awaited in order to pause execution until the app has accepted or denied the connection. In the latter case, an error will be raised to the caller.

Keyword Arguments: timeout (int) – Number of seconds to wait before giving up and raising an error (default: 5).

class falcon.testing.Cookie(morsel)[source]¶

Represents a cookie returned by a simulated request.

Parameters: morsel – A Morsel object from which to derive the cookie data.

name¶

The cookie’s name.

Type: str

value¶

The value of the cookie.

Type: str

expires¶

Expiration timestamp for the cookie, or None if not specified.

Type: datetime.datetime

path¶

The path prefix to which this cookie is restricted, or None if not specified.

Type: str

domain¶

The domain to which this cookie is restricted, or None if not specified.

Type: str

max_age¶

The lifetime of the cookie in seconds, or None if not specified.

Type: int

secure¶

Whether or not the cookie may only only be transmitted from the client via HTTPS.

Type: bool

http_only¶

Whether or not the cookie may only be included in unscripted requests from the client.

Type: bool

Standalone Methods ¶

falcon.testing.simulate_get(app, path, **kwargs) → _ResultBase[source]¶

Simulate a GET request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'GET', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) –
The URL path to request

Note

The path may contain a query string. However, neither query_string nor params may be specified in this case.

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
file_wrapper (callable) – Callable that returns an iterable, to be used as the value for wsgi.file_wrapper in the WSGI environ (default: None). This can be used to test high-performance file transmission when resp.stream is set to a file-like object.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_head(app, path, **kwargs) → _ResultBase[source]¶

Simulate a HEAD request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'HEAD', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) –
The URL path to request

Note

The path may contain a query string. However, neither query_string nor params may be specified in this case.

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_post(app, path, **kwargs) → _ResultBase[source]¶

Simulate a POST request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'POST', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) – The URL path to request

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
content_type (str) – The value to use for the Content-Type header in the request. If specified, this value will take precedence over any value set for the Content-Type header in the headers keyword argument. The falcon module provides a number of constants for common media types.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
body (str) – The body of the request (default ‘’). The value will be encoded as UTF-8 in the WSGI environ. Alternatively, a byte string may be passed, in which case it will be used as-is.
json (JSON serializable) – A JSON document to serialize as the body of the request (default: None). If specified, overrides body and sets the Content-Type header to 'application/json', overriding any value specified by either the content_type or headers arguments.
file_wrapper (callable) – Callable that returns an iterable, to be used as the value for wsgi.file_wrapper in the WSGI environ (default: None). This can be used to test high-performance file transmission when resp.stream is set to a file-like object.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_put(app, path, **kwargs) → _ResultBase[source]¶

Simulate a PUT request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'PUT', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) – The URL path to request

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
content_type (str) – The value to use for the Content-Type header in the request. If specified, this value will take precedence over any value set for the Content-Type header in the headers keyword argument. The falcon module provides a number of constants for common media types.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
body (str) – The body of the request (default ‘’). The value will be encoded as UTF-8 in the WSGI environ. Alternatively, a byte string may be passed, in which case it will be used as-is.
json (JSON serializable) – A JSON document to serialize as the body of the request (default: None). If specified, overrides body and sets the Content-Type header to 'application/json', overriding any value specified by either the content_type or headers arguments.
file_wrapper (callable) – Callable that returns an iterable, to be used as the value for wsgi.file_wrapper in the WSGI environ (default: None). This can be used to test high-performance file transmission when resp.stream is set to a file-like object.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_options(app, path, **kwargs) → _ResultBase[source]¶

Simulate an OPTIONS request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'OPTIONS', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) – The URL path to request

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)

Returns

The result of the request

Return type

falcon.testing.simulate_patch(app, path, **kwargs) → _ResultBase[source]¶

Simulate a PATCH request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'PATCH', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) – The URL path to request

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
content_type (str) – The value to use for the Content-Type header in the request. If specified, this value will take precedence over any value set for the Content-Type header in the headers keyword argument. The falcon module provides a number of constants for common media types.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
body (str) – The body of the request (default ‘’). The value will be encoded as UTF-8 in the WSGI environ. Alternatively, a byte string may be passed, in which case it will be used as-is.
json (JSON serializable) – A JSON document to serialize as the body of the request (default: None). If specified, overrides body and sets the Content-Type header to 'application/json', overriding any value specified by either the content_type or headers arguments.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_delete(app, path, **kwargs) → _ResultBase[source]¶

Simulate a DELETE request to a WSGI or ASGI application.

Equivalent to:

simulate_request(app, 'DELETE', path, **kwargs)

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Parameters

app (callable) – The application to call
path (str) – The URL path to request

Keyword Arguments

root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
content_type (str) – The value to use for the Content-Type header in the request. If specified, this value will take precedence over any value set for the Content-Type header in the headers keyword argument. The falcon module provides a number of constants for common media types.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
body (str) – The body of the request (default ‘’). The value will be encoded as UTF-8 in the WSGI environ. Alternatively, a byte string may be passed, in which case it will be used as-is.
json (JSON serializable) – A JSON document to serialize as the body of the request (default: None). If specified, overrides body and sets the Content-Type header to 'application/json', overriding any value specified by either the content_type or headers arguments.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300). Set to 0 to simulate an immediate disconnection without first emitting 'http.request'.
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type

falcon.testing.simulate_request(app, method='GET', path='/', query_string=None, headers=None, content_type=None, body=None, json=None, file_wrapper=None, wsgierrors=None, params=None, params_csv=False, protocol='http', host='falconframework.org', remote_addr=None, extras=None, http_version='1.1', port=None, root_path=None, cookies=None, asgi_chunk_size=4096, asgi_disconnect_ttl=300) → _ResultBase[source]¶

Simulate a request to a WSGI or ASGI application.

Performs a request against a WSGI or ASGI application. In the case of WSGI, uses wsgiref.validate to ensure the response is valid.

Note

In the case of an ASGI request, this method will simulate the entire app lifecycle in a single shot, including lifespan and client disconnect events. In order to simulate multiple interleaved requests, or to test a streaming endpoint (such as one that emits server-sent events), ASGIConductor can be used to more precisely control the app lifecycle.

Keyword Arguments

app (callable) – The WSGI or ASGI application to call
method (str) – An HTTP method to use in the request (default: ‘GET’)
path (str) –
The URL path to request (default: ‘/’).

Note

The path may contain a query string. However, neither query_string nor params may be specified in this case.
root_path (str) – The initial portion of the request URL’s “path” that corresponds to the application object, so that the application knows its virtual “location”. This defaults to the empty string, indicating that the application corresponds to the “root” of the server.
protocol – The protocol to use for the URL scheme (default: ‘http’)
port (int) – The TCP port to simulate. Defaults to the standard port used by the given scheme (i.e., 80 for ‘http’ and 443 for ‘https’). A string may also be passed, as long as it can be parsed as an int.
params (dict) – A dictionary of query string parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).
params_csv (bool) – Set to True to encode list values in query string params as comma-separated values (e.g., ‘thing=1,2,3’). Otherwise, parameters will be encoded by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Defaults to False.
query_string (str) – A raw query string to include in the request (default: None). If specified, overrides params.
content_type (str) – The value to use for the Content-Type header in the request. If specified, this value will take precedence over any value set for the Content-Type header in the headers keyword argument. The falcon module provides a number of constants for common media types.
headers (dict) –
Extra headers as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of strings provides the name and value for an HTTP header. If desired, multiple header values may be combined into a single (name, value) pair by joining the values with a comma when the header in question supports the list format (see also RFC 7230 and RFC 7231). Header names are not case-sensitive.
Note

If a User-Agent header is not provided, it will default to:
```
f'falcon-client/{falcon.__version__}'
```
body (str) – The body of the request (default ‘’). The value will be encoded as UTF-8 in the WSGI environ. Alternatively, a byte string may be passed, in which case it will be used as-is.
json (JSON serializable) – A JSON document to serialize as the body of the request (default: None). If specified, overrides body and sets the Content-Type header to 'application/json', overriding any value specified by either the content_type or headers arguments.
file_wrapper (callable) – Callable that returns an iterable, to be used as the value for wsgi.file_wrapper in the WSGI environ (default: None). This can be used to test high-performance file transmission when resp.stream is set to a file-like object.
host (str) – A string to use for the hostname part of the fully qualified request URL (default: ‘falconframework.org’)
remote_addr (str) – A string to use as the remote IP address for the request (default: ‘127.0.0.1’). For WSGI, this corresponds to the ‘REMOTE_ADDR’ environ variable. For ASGI, this corresponds to the IP address used for the ‘client’ field in the connection scope.
http_version (str) – The HTTP version to simulate. Must be either ‘2’, ‘2.0’, 1.1’, ‘1.0’, or ‘1’ (default ‘1.1’). If set to ‘1.0’, the Host header will not be added to the scope.
wsgierrors (io) – The stream to use as wsgierrors in the WSGI environ (default sys.stderr)
asgi_chunk_size (int) – The maximum number of bytes that will be sent to the ASGI app in a single 'http.request' event (default 4096).
asgi_disconnect_ttl (int) – The maximum number of seconds to wait since the request was initiated, before emitting an 'http.disconnect' event when the app calls the receive() function (default 300).
extras (dict) – Additional values to add to the WSGI environ dictionary or the ASGI scope for the request (default: None)
cookies (dict) – Cookies as a dict-like (Mapping) object, or an iterable yielding a series of two-member (name, value) iterables. Each pair of items provides the name and value for the ‘Set-Cookie’ header.

Returns

The result of the request

Return type