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
andfalcon.asgi.App
.- Returns:
The information regarding the application. Call
to_string()
on the result to obtain a human-friendly representation.- Return type:
- 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
andfalcon.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
andfalcon.asgi.App
.- Returns:
Information about the app’s middleware components.
- Return type:
- 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
andfalcon.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
andfalcon.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
andfalcon.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 ofRouteInfo
. 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.
- 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:
- 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.
- 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.
- class falcon.inspect.MiddlewareMethodInfo(function_name: str, source_info: str)[source]¶
Describes a middleware method.
- class falcon.inspect.StaticRouteInfo(prefix: str, directory: str, fallback_filename: str | None)[source]¶
Describes a static route.
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.
- 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 callingStringVisitor.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'
.