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
|
Debugging
=========
Using the Python debugger
--------------------------
You can configure Litestar to drop into the :doc:`Python Debugger <python:library/pdb>`
when an exception occurs. This can be configured in different ways:
Configuring ``Litestar`` with the ``pdb_on_exception`` option
.. code-block:: python
app = Litestar(pdb_on_exception=True)
Running your app with the CLI and using the ``--pdb`` flag
.. code-block:: shell
litestar run --pdb
Using the ``LITESTAR_PDB`` environment variable
``LITESTAR_PDB=1``
Debugging with an IDE
---------------------
You can easily attach your IDEs debugger to your application, whether you're running it
via the CLI or a webserver like `uvicorn <https://www.uvicorn.org/>`_.
Intellij / PyCharm
++++++++++++++++++
Using the CLI
*************
1. Create a new debug configuration via ``Run`` > ``Edit Configurations``
2. Select ``Module name`` option and set it to ``litestar``
3. Add the ``run`` parameter and optionally additional parameters you want to pass
to the CLI
.. image:: /images/debugging/pycharm-config-cli.png
4. Run your application in the debugger via ``Run`` > ``Debug Litestar``
.. image:: /images/debugging/pycharm-debug.png
:align: center
.. important::
Breakpoints inside route handlers might not work correctly when used in conjunction
with the ``--reload`` and ``--web-concurrency`` parameters. If you want to use the
CLI while making use of these options, you can attach the debugger manually to the
running uvicorn process via ``Run`` > ``Attach to process``.
Using uvicorn
*************
1. Create a new debug configuration via ``Run`` > ``Edit Configurations``
2. Select ``Module name`` option and set it to ``uvicorn``
3. Add the ``app:app`` parameter (or the equivalent path to your application object)
.. image:: /images/debugging/pycharm-config-uvicorn.png
4. Run your application in the debugger via ``Run`` > ``Debug Litestar``
.. image:: /images/debugging/pycharm-debug.png
:align: center
VS Code
+++++++
Using the CLI
*************
1. Add a new debugging configuration via ``Run`` > ``Add configuration``
.. image:: /images/debugging/vs-code-add-config.png
:align: center
2. From the ``Select a debug configuration`` dialog, select ``Module``
.. image:: /images/debugging/vs-code-select-config.png
3. Enter ``litestar`` as the module name
.. image:: /images/debugging/vs-code-config-litestar.png
4. In the opened JSON file, alter the configuration as follows:
.. code-block:: json
{
"name": "Python: Litestar app",
"type": "debugpy",
"request": "launch",
"module": "litestar",
"justMyCode": true,
"args": ["run"]
}
5. Run your application via the debugger via ``Run`` > ``Start debugging``
.. image:: /images/debugging/vs-code-debug.png
:align: center
Using uvicorn
**************
1. Add a new debugging configuration via ``Run`` > ``Add configuration``
.. image:: /images/debugging/vs-code-add-config.png
:align: center
2. From the ``Select a debug configuration`` dialog, select ``Module``
.. image:: /images/debugging/vs-code-select-config.png
3. Enter ``uvicorn`` as the module name
.. image:: /images/debugging/vs-code-config-litestar.png
4. In the opened JSON file, alter the configuration as follows:
.. code-block:: json
{
"name": "Python: Litestar app",
"type": "debugpy",
"request": "launch",
"module": "uvicorn",
"justMyCode": true,
"args": ["app:app"]
}
5. Run your application via the debugger via ``Run`` > ``Start debugging``
.. image:: /images/debugging/vs-code-debug.png
:align: center
Customizing the debugger
-------------------------
You can configure Litestar with the debug_module option to enable interactive debugging. Currently, it supports the following debugging tools:
`ipdb <https://github.com/gotcha/ipdb>`_, `PuDB <https://documen.tician.de/pudb/>`_ and `pdbr <https://github.com/cansarigol/pdbr>`_. Also supports `pdb++ <https://github.com/pdbpp/pdbpp>`_.
The default value is `pdb <https://docs.python.org/3/library/pdb.html>`_.
.. code-block:: python
import ipdb
app = Litestar(pdb_on_exception=True, debugger_module=ipdb)
|
