Inspect Module

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:

str

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:
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: str | None)[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]

Describes 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'.