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
|
.. _quickstart:
Quickstart
==========
If you haven't done so already, please take a moment to
:ref:`install <install>` the Falcon web framework before
continuing.
Learning by Example
-------------------
Here is a simple example from Falcon's README, showing how to get
started writing an app.
.. tab-set::
.. tab-item:: WSGI
:sync: wsgi
.. literalinclude:: ../../examples/things.py
:language: python
You can run the above example directly using the included wsgiref server:
.. code:: bash
$ pip install falcon
$ python things.py
Then, in another terminal:
.. code:: bash
$ curl localhost:8000/things
As an alternative to Curl, you might want to give
`HTTPie <https://github.com/jkbr/httpie>`_ a try:
.. code:: bash
$ pip install --upgrade httpie
$ http localhost:8000/things
.. tab-item:: ASGI
:sync: asgi
.. literalinclude:: ../../examples/things_asgi.py
:language: python
You can run the ASGI version with uvicorn or any other ASGI server:
.. code:: bash
$ pip install falcon uvicorn
$ uvicorn things_asgi:app
Then, in another terminal:
.. code:: bash
$ curl localhost:8000/things
As an alternative to Curl, you might want to give
`HTTPie <https://github.com/jkbr/httpie>`_ a try:
.. code:: bash
$ pip install --upgrade httpie
$ http localhost:8000/things
.. _quickstart-more-features:
A More Complex Example
----------------------
Here is a more involved example that demonstrates reading headers and query
parameters, handling errors, and working with request and response bodies.
.. tab-set::
.. tab-item:: WSGI
:sync: wsgi
Note that this example assumes that the
`requests <https://pypi.org/project/requests/>`_ package has been installed.
.. literalinclude:: ../../examples/things_advanced.py
:language: python
Again this code uses wsgiref, but you can also run the above example using
any WSGI server, such as uWSGI or Gunicorn. For example:
.. code:: bash
$ pip install requests gunicorn
$ gunicorn things:app
On Windows you can run Gunicorn and uWSGI via WSL, or you might try Waitress:
.. code:: bash
$ pip install requests waitress
$ waitress-serve --port=8000 things:app
To test this example go to the another terminal and run:
.. code:: bash
$ http localhost:8000/1/things authorization:custom-token
To visualize the application configuration the :ref:`inspect` can be used:
.. code:: bash
falcon-inspect-app things_advanced:app
This would print for this example application:
.. code::
Falcon App (WSGI)
• Routes:
⇒ /{user_id}/things - ThingsResource:
├── GET - on_get
└── POST - on_post
• Middleware (Middleware are independent):
→ AuthMiddleware.process_request
→ RequireJSON.process_request
→ JSONTranslator.process_request
├── Process route responder
↢ JSONTranslator.process_response
• Sinks:
⇥ /search/(?P<engine>ddg|y)\Z SinkAdapter
• Error handlers:
⇜ StorageError handle
.. tab-item:: ASGI
:sync: asgi
Note that this example requires the
`httpx <https://pypi.org/project/httpx/>`_ package in lieu of
`requests <https://pypi.org/project/requests/>`_.
.. literalinclude:: ../../examples/things_advanced_asgi.py
:language: python
You can run the ASGI version with any ASGI server, such as uvicorn:
.. code:: bash
$ pip install falcon httpx uvicorn
$ uvicorn things_advanced_asgi:app
|
