Debian Codegraph @

docs/usage/debugging.rst

raw
1 Debugging
2 =========
3
4 Using the Python debugger
5 --------------------------
6
7 You can configure Litestar to drop into the :doc:`Python Debugger <python:library/pdb>`
8 when an exception occurs. This can be configured in different ways:
9
10 Configuring ``Litestar`` with the ``pdb_on_exception`` option
11 .. code-block:: python
12
13 app = Litestar(pdb_on_exception=True)
14
15
16 Running your app with the CLI and using the ``--pdb`` flag
17 .. code-block:: shell
18
19 litestar run --pdb
20
21 Using the ``LITESTAR_PDB`` environment variable
22 ``LITESTAR_PDB=1``
23
24
25 Debugging with an IDE
26 ---------------------
27
28 You can easily attach your IDEs debugger to your application, whether you're running it
29 via the CLI or a webserver like `uvicorn <https://www.uvicorn.org/>`_.
30
31 Intellij / PyCharm
32 ++++++++++++++++++
33
34 Using the CLI
35 *************
36
37 1. Create a new debug configuration via ``Run`` > ``Edit Configurations``
38 2. Select ``Module name`` option and set it to ``litestar``
39 3. Add the ``run`` parameter and optionally additional parameters you want to pass
40 to the CLI
41
42 .. image:: /images/debugging/pycharm-config-cli.png
43
44 4. Run your application in the debugger via ``Run`` > ``Debug Litestar``
45
46 .. image:: /images/debugging/pycharm-debug.png
47 :align: center
48
49
50 .. important::
51 Breakpoints inside route handlers might not work correctly when used in conjunction
52 with the ``--reload`` and ``--web-concurrency`` parameters. If you want to use the
53 CLI while making use of these options, you can attach the debugger manually to the
54 running uvicorn process via ``Run`` > ``Attach to process``.
55
56
57 Using uvicorn
58 *************
59
60 1. Create a new debug configuration via ``Run`` > ``Edit Configurations``
61 2. Select ``Module name`` option and set it to ``uvicorn``
62 3. Add the ``app:app`` parameter (or the equivalent path to your application object)
63
64 .. image:: /images/debugging/pycharm-config-uvicorn.png
65
66 4. Run your application in the debugger via ``Run`` > ``Debug Litestar``
67
68 .. image:: /images/debugging/pycharm-debug.png
69 :align: center
70
71
72 VS Code
73 +++++++
74
75
76 Using the CLI
77 *************
78
79
80 1. Add a new debugging configuration via ``Run`` > ``Add configuration``
81 .. image:: /images/debugging/vs-code-add-config.png
82 :align: center
83 2. From the ``Select a debug configuration`` dialog, select ``Module``
84 .. image:: /images/debugging/vs-code-select-config.png
85 3. Enter ``litestar`` as the module name
86 .. image:: /images/debugging/vs-code-config-litestar.png
87 4. In the opened JSON file, alter the configuration as follows:
88 .. code-block:: json
89
90 {
91 "name": "Python: Litestar app",
92 "type": "debugpy",
93 "request": "launch",
94 "module": "litestar",
95 "justMyCode": true,
96 "args": ["run"]
97 }
98
99 5. Run your application via the debugger via ``Run`` > ``Start debugging``
100 .. image:: /images/debugging/vs-code-debug.png
101 :align: center
102
103
104 Using uvicorn
105 **************
106
107 1. Add a new debugging configuration via ``Run`` > ``Add configuration``
108 .. image:: /images/debugging/vs-code-add-config.png
109 :align: center
110 2. From the ``Select a debug configuration`` dialog, select ``Module``
111 .. image:: /images/debugging/vs-code-select-config.png
112 3. Enter ``uvicorn`` as the module name
113 .. image:: /images/debugging/vs-code-config-litestar.png
114 4. In the opened JSON file, alter the configuration as follows:
115 .. code-block:: json
116
117 {
118 "name": "Python: Litestar app",
119 "type": "debugpy",
120 "request": "launch",
121 "module": "uvicorn",
122 "justMyCode": true,
123 "args": ["app:app"]
124 }
125
126 5. Run your application via the debugger via ``Run`` > ``Start debugging``
127 .. image:: /images/debugging/vs-code-debug.png
128 :align: center
129
130
131 Customizing the debugger
132 -------------------------
133
134 You can configure Litestar with the debug_module option to enable interactive debugging. Currently, it supports the following debugging tools:
135 `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>`_.
136 The default value is `pdb <https://docs.python.org/3/library/pdb.html>`_.
137
138 .. code-block:: python
139
140 import ipdb
141
142
143 app = Litestar(pdb_on_exception=True, debugger_module=ipdb)