Skip to content

Commit 2afbf66

Browse files
committed
Formatted readme file based on vscode markdown linter
1 parent 2f3e0bb commit 2afbf66

1 file changed

Lines changed: 28 additions & 1 deletion

File tree

README.md

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,65 +16,88 @@ An implementation of the [Debug Adapter Protocol](https://microsoft.github.io/de
1616
| Mac | ![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/debugpy/debugpy/4) |
1717

1818
## `debugpy` CLI Usage
19+
1920
### Debugging a script file
21+
2022
To run a script file with debugging enabled, but without waiting for the client to attach (i.e. code starts executing immediately):
23+
2124
```console
2225
-m debugpy --listen localhost:5678 myfile.py
2326
```
27+
2428
To wait until the client attaches before running your code, use the `--wait-for-client` switch.
29+
2530
```console
2631
-m debugpy --listen localhost:5678 --wait-for-client myfile.py
2732
```
33+
2834
The hostname passed to `--listen` specifies the interface on which the debug adapter will be listening for connections from DAP clients. It can be omitted, with only the port number specified:
35+
2936
```console
3037
-m debugpy --listen 5678 ...
3138
```
39+
3240
in which case the default interface is 127.0.0.1.
3341

3442
To be able to attach from another machine, make sure that the adapter is listening on a public interface - using `0.0.0.0` will make it listen on all available interfaces:
43+
3544
```console
3645
-m debugpy --listen 0.0.0.0:5678 myfile.py
3746
```
47+
3848
This should only be done on secure networks, since anyone who can connect to the specified port can then execute arbitrary code within the debugged process.
3949

4050
To pass arguments to the script, just specify them after the filename. This works the same as with Python itself - everything up to the filename is processed by debugpy, but everything after that becomes `sys.argv` of the running process.
4151

4252
### Debugging a module
53+
4354
To run a module, use the `-m` switch instead of filename:
55+
4456
```console
4557
-m debugpy --listen localhost:5678 -m mymodule
4658
```
59+
4760
Same as with scripts, command line arguments can be passed to the module by specifying them after the module name. All other debugpy switches work identically in this mode; in particular, `--wait-for-client` can be used to block execution until the client attaches.
4861

4962
### Attaching to a running process by ID
63+
5064
The following command injects the debugger into a process with a given PID that is running Python code. Once the command returns, a debugpy server is running within the process, as if that process was launched via `-m debugpy` itself.
65+
5166
```console
5267
-m debugpy --listen localhost:5678 --pid 12345
5368
```
5469

5570
### Ignoring subprocesses
71+
5672
The following command will ignore subprocesses started by the debugged process.
73+
5774
```console
5875
-m debugpy --listen localhost:5678 --pid 12345 --configure-subProcess False
5976
```
6077

61-
6278
## `debugpy` Import usage
79+
6380
### Enabling debugging
81+
6482
At the beginning of your script, import debugpy, and call `debugpy.listen()` to start the debug adapter, passing a `(host, port)` tuple as the first argument.
83+
6584
```python
6685
import debugpy
6786
debugpy.listen(("localhost", 5678))
6887
...
6988
```
89+
7090
As with the `--listen` command line switch, hostname can be omitted, and defaults to `"127.0.0.1"`:
91+
7192
```python
7293
debugpy.listen(5678)
7394
...
7495
```
7596

7697
### Waiting for the client to attach
98+
7799
Use the `debugpy.wait_for_client()` function to block program execution until the client is attached.
100+
78101
```python
79102
import debugpy
80103
debugpy.listen(5678)
@@ -83,7 +106,9 @@ debugpy.wait_for_client() # blocks execution until client is attached
83106
```
84107

85108
### `breakpoint()` function
109+
86110
Where available, debugpy supports the standard `breakpoint()` function for programmatic breakpoints. Use `debugpy.breakpoint()` function to get the same behavior when `breakpoint()` handler installed by debugpy is overridden by another handler. If the debugger is attached when either of these functions is invoked, it will pause execution on the calling line, as if it had a breakpoint set. If there's no client attached, the functions do nothing, and the code continues to execute normally.
111+
87112
```python
88113
import debugpy
89114
debugpy.listen(...)
@@ -97,11 +122,13 @@ while True:
97122
## Debugger logging
98123

99124
To enable debugger internal logging via CLI, the `--log-to` switch can be used:
125+
100126
```console
101127
-m debugpy --log-to path/to/logs ...
102128
```
103129

104130
When using the API, the same can be done with `debugpy.log_to()`:
131+
105132
```py
106133
debugpy.log_to('path/to/logs')
107134
debugpy.listen(...)

0 commit comments

Comments
 (0)