Python debugger package for use with Visual Studio and Visual Studio Code.
Clone or download
karthiknadig Merge into master (#1020)
* Migrate debugger tests (#968)

* Remove references to old test code (#1019)
Latest commit bd03d3a Nov 14, 2018
Permalink
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates (#917) Oct 15, 2018
debugger_protocol Tests for break on start, wait for normal and abnormal exit (#952) Oct 24, 2018
ptvsd Empty stack traces. Fixes #1006 (#1011) Nov 13, 2018
pytests Merge into master (#1020) Nov 15, 2018
tests Merge into master (#1020) Nov 15, 2018
win Fix build paths in sign project (#458) Jun 1, 2018
.flake8 Fix #966: Sub process debugging not working with PTVSD Oct 30, 2018
.flake8.ci Update for VSTS-based CI process (#431) Jun 22, 2018
.gitattributes Set up versioneer to auto-generate version numbers from git. Apr 11, 2018
.gitignore Test & infrastructure cleanup, stage 1 (#850) Sep 27, 2018
.pylintrc Test & infrastructure cleanup, stage 1 (#850) Sep 27, 2018
.travis.yml Testing framework for timeline-based tests. (#857) Oct 1, 2018
CODE_OF_CONDUCT.md Updating contribution details (#860) Oct 2, 2018
CONTRIBUTING.md Fix a broken link and a double space in README.md (#946) Oct 22, 2018
DESCRIPTION.md Update pypi info (#480) Jun 15, 2018
LICENSE Updates LICENSE file with correct text and includes it in distributions Feb 22, 2018
MANIFEST.in Fix for missing Description.md (#493) Jun 18, 2018
Makefile Test fixes and tweaks. Nov 14, 2018
README.md Correct Grammatical Mistakes (#976) Nov 12, 2018
ptvsd.code-workspace Test & infrastructure cleanup, stage 1 (#850) Sep 27, 2018
pytest.ini Use 'thread' timeout method for pytest for more reliable timeouts on … Oct 11, 2018
setup.cfg Testing framework for timeline-based tests. (#857) Oct 1, 2018
setup.py Refactor timeline: Oct 11, 2018
test_requirements.txt Test fixes and tweaks. Nov 14, 2018
tox.ini Automate pytest using tox (#934) Oct 31, 2018
versioneer.py Disable 'dirty' flag for version numbers. Apr 19, 2018

README.md

Python Tools for Visual Studio debug server

Build Status Build Status GitHub PyPI

ptvsd CLI Usage

Debugging a script file

To run a script file with debugging enabled, but without waiting for the debugger to attach (i.e. code starts executing immediately):

-m ptvsd --host localhost --port 5678 myfile.py

To wait until the debugger attaches before running your code, use the --wait switch.

-m ptvsd --host localhost  --port 5678 --wait myfile.py

The --host option specifies the interface on which the debug server is listening for connections. To be able to attach from another machine, make sure that the server is listening on a public interface - using 0.0.0.0 will make it listen on all available interfaces:

-m ptvsd --host 0.0.0.0 --port 5678 myfile.py

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.

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 ptvsd, but everything after that becomes sys.argv of the running process.

Debugging a module

To run a module, use the -m switch instead of filename:

-m ptvsd --host localhost --port 5678 -m mymodule

Same as with scripts, command line arguments can be passed to the module by specifying them after the module name. All other ptvsd switches work identically in this mode; in particular, --wait can be used to block execution until the debugger attaches.

Attaching to a running process by ID

The following command injects the debugger into a process with a given PID that is running Python code. Once the command returns, a ptvsd server is running within the process, as if that process was launched via -m ptvsd itself.

-m ptvsd --host localhost --port 5678 --pid 12345

ptvsd Import usage

Enabling debugging

At the beginning of your script, import ptvsd, and call ptvsd.enable_attach() to start the debug server. The default hostname is 0.0.0.0, and the default port is 5678; these can be overridden by passing a (host, port) tuple as the first argument of enable_attach().

import ptvsd
ptvsd.enable_attach()
...

Waiting for the debugger to attach

Use the ptvsd.wait_for_attach() function to block program execution until the debugger is attached.

import ptvsd
ptvsd.enable_attach()
ptvsd.wait_for_attach()  # blocks execution until debugger is attached
...

breakpoint() function

In Python 3.7 and above, ptvsd supports the standard breakpoint() function. Use ptvsd.break_into_debugger() function for similar behavior and compatibility with older versions of Python (3.6 and below). 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 debugger attached, the functions do nothing, and the code continues to execute normally.

import ptvsd
ptvsd.enable_attach()

while True:
    ...
    breakpoint() # or ptvsd.break_into_debugger() on <3.7
    ...

Custom Protocol arguments

Launch request arguments

{
    "debugOptions":  [
            "RedirectOutput",       // Whether to redirect stdout and stderr (see pydevd_comm.CMD_REDIRECT_OUTPUT)
            "WaitOnNormalExit",     // Wait for user input after user code exits normally
            "WaitOnAbnormalExit",   // Wait for user input after user code exits with error
            "Django",               // Enables Django Template debugging
            "Jinja",                // Enables Jinja (Flask) Template debugging
            "FixFilePathCase",      // See FIX_FILE_PATH_CASE in wrapper.py
            "DebugStdLib",          // Whether to enable debugging of standard library functions
            "StopOnEntry",          // Whether to stop at first line of user code
            "ShowReturnValue",      // Show return values of functions
    ]
}

Attach request arguments

{
    "debugOptions":  [
            "RedirectOutput",       // Whether to redirect stdout and stderr (see pydevd_comm.CMD_REDIRECT_OUTPUT)
            "Django",               // Enables Django Template debugging
            "Jinja",                // Enables Jinja (Flask) Template debugging
            "FixFilePathCase",      // See FIX_FILE_PATH_CASE in wrapper.py
            "DebugStdLib",          // Whether to enable debugging of standard library functions
            "WindowsClient",        // Whether client OS is Windows
            "UnixClient",           // Whether client OS is Unix
            "ShowReturnValue",      // Show return values of functions
    ],
    "pathMappings": [
        {
            "localRoot": "C:\\Project\\src",   // Local root  (where source and debugger running)
            "remoteRoot": "/home/smith/proj"   // Remote root (where remote code is running)
        },
        // Add more path mappings
    ]
}