1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.. _inspect:
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
:func:`.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:
.. code:: bash
# 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 :meth:`.AppInfo.to_string` method. In fact, here is a simple
script that returns the same output as the ``falcon-inspect-app`` command:
.. code:: python
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 :meth:`.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 :func:`.register_router` function to register
a handler function for the custom router class.
Inspection of the default :class:`.CompiledRouter` class is
handled by the :func:`.inspect_compiled_router`
function.
The returned information classes can be explored using the visitor
pattern. To create the string representation of the classes the
:class:`.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 :class:`.InspectVisitor` and
use the :meth:`.InspectVisitor.process` method to visit
the classes.
Inspect Functions Reference
---------------------------
This module defines the following inspect functions.
.. autofunction:: falcon.inspect.inspect_app
.. autofunction:: falcon.inspect.inspect_routes
.. autofunction:: falcon.inspect.inspect_middleware
.. autofunction:: falcon.inspect.inspect_static_routes
.. autofunction:: falcon.inspect.inspect_sinks
.. autofunction:: falcon.inspect.inspect_error_handlers
Router Inspection
-----------------
The following functions enable route inspection.
.. autofunction:: falcon.inspect.register_router
.. autofunction:: falcon.inspect.inspect_compiled_router
Information Classes
-------------------
Information returned by the inspect functions is represented by these classes.
.. autoclass:: falcon.inspect.AppInfo
:members:
.. autoclass:: falcon.inspect.RouteInfo
.. autoclass:: falcon.inspect.RouteMethodInfo
.. autoclass:: falcon.inspect.MiddlewareInfo
.. autoclass:: falcon.inspect.MiddlewareTreeInfo
.. autoclass:: falcon.inspect.MiddlewareClassInfo
.. autoclass:: falcon.inspect.MiddlewareTreeItemInfo
.. autoclass:: falcon.inspect.MiddlewareMethodInfo
.. autoclass:: falcon.inspect.StaticRouteInfo
.. autoclass:: falcon.inspect.SinkInfo
.. autoclass:: falcon.inspect.ErrorHandlerInfo
Visitor Classes
---------------
The following visitors are used to traverse the information classes.
.. autoclass:: falcon.inspect.InspectVisitor
:members:
.. autoclass:: falcon.inspect.StringVisitor
|
