Detailed walk-thru Guide

Python Tools for Visual Studio provides Python programmers with a great development experience inside of Visual Studio. Python Tools for Visual Studio (PTVS for short) is a set of components that extends Visual Studio. It supports editing, debugging, creating Python projects, an interactive REPL window, profiling, and participating in VS solutions.

Getting Started

Upon starting Visual Studio you can either proceed with or without a project file, while still getting code analysis over related code. To start working with a project you can choose New Project from the start page or File->New Project. Select the appropriate project type and select a location to create the project. For more information about the project types see the Projects section below.

To start working without a project you can just open any .py files using File->Open. Python Tools provides completion, parameter tips, go to definition, etc., on all the code in the directory containing the file you opened, as well as sub directories.

You may also want to configure some options after you’ve initially installed Python Tools. By default Python Tools will pick up all installed versions of Python (both CPython and IronPython, multiple versions) on your system. But you may want to build the intellisense database or pick which version of Python is the default or set various options which controls its behavior. You can do this via the Visual Studio Tools->Options->Python Tools options. In here you’ll find advanced options, interactive window (REPL) options, as well as interpreter options. If you’d like to configure how the text editor behaves you can also take a look at Tools->Options->Text Editor->Python.

Projects

Python Tools supports the Visual Studio project system. Project files for Python projects are .pyproj files. Like all Visual Studio languages, Python project files are referenced from a solution which can contain one or more project files from varying languages.

Projects include a start-up file which is the file that runs when you start with debugging or execute your project in the interactive window. This file is indicated in bold. You can change this file either by right clicking and selecting “Set as Startup File” or by setting the startup file in the project’s properties.

Depending on which components you have installed, Python Tools can support several project types such as Console, MPI, WPF, ...

Note: currently, for the various project types to show up, you need to install the relevant supporting software (eg HPC SDK for the MPI projects, IronPython for .Net projects, ...)

Console Application

This is a simple application or script which is launched as “ipy.exe Program.py”. The program will have a console window for input and output. If you use Execute in Python Interactive, input and output occur in the interactive as if it were a console window.

IronPython Silverlight Web Page

This is an IronPython application which will run in the web browser using Silverlight. Your script code is written in a .py file that a web page includes using a <script type=”text/python” src=”…”> tag. A boilerplate script tag pulls down some JavaScript code which initializes IronPython running inside of Silverlight. From there your Python code can interact with the DOM. Note: Silverlight support is very preliminary at this time.

WPF Application

This is an application which is launched as “ipyw.exe Program.py”. This program will not have a console window and includes a template which creates a Windows Presentation Foundation application. The code and design are separated with the markup being stored in a .XAML file. There is a WYSIWIG designer which enables drag and drop editing of the design. Python code can be used to wire up event handling.

WinForms Application

This is an application which is launched as “ipyw.exe Program.py”. The program will not have a console window. A typical usage of this is to start a WinForms application. Python Tools currently does not provide any WYSIWIG support for developing WinForms applications. Instead you’ll need to write the logic to create the UI in Python (see the IronPython tutorial for examples).

Lightweight Usage Project-free

Python Tools also supports editing your code without a project system. You can open any files on disk and start editing them. Python Tools will automatically include other files and packages in the same directory in its analysis, so you’ll get member completion and help without being required to create a project file.

Create Project from Existing Files

If you already have existing Python code, you can easily create a new project without having to move it around.  In the New Project window select "From Existing Python Code" and a wizard will guide you through quickly incorporating an existing file tree:

The Editor

One of the primary experiences when working with Python Tools is of course editing the source code. Python Tools includes syntax color highlighting, outlining of classes and functions, and drop down navigation. There is an analysis engine that understands your classes and functions using type inference. This enables you to receive member completion and signature help, receive tool tips when hovering over source code, and quickly navigate and find references within your source code.

Intellisense

Some of the primary features of the editor are support for rich member completion, signature help, and quick info when hovering over members. Supporting this is a new analysis engine which infers types from their usage to provide useful information to the developer. The type inference is control flow independent and works across function, class, and module boundaries and is updated in real time while you’re developing your application.

Python Tools also is able to provide significant intellisense against standard Python built-in functions. For standard Python this is done with a database for the interpreter which can be generated after Python Tools is installed. For IronPython .NET classes are supported directly by relying upon the strong typing available for .NET members.

You’ll also find you get completion when you’re dotting through members and also when you’re importing modules, or members from inside of a module. In this example you can also see that the intellisense engine is aware of the members and also of the types of members, so you get a quick visual clue for the member type that you’re looking for.

These are all fairly simple examples so far, but the analysis engine is capable of some sophisticated tricks. For example, it’s common to use tuples or lists to store homogeneous data and then either iterate over those lists or index into them using global constants. The analysis engine is capable of tracking the types of indices and providing intellisense on a per-index basis.

So far we’ve just been talking about member completion which is extremely useful, but the editor can offer more information than just that. One common form of additional information is signature help. Here Python Tools captures any relevant doc strings from the function you’re calling and provides information about default parameters as well. When calling a .NET function that has multiple overloads, you’ll also be able to iterate through the available overloads using the arrow keys. Of course, you don’t need to use the arrow keys – we’ll try to automatically select the correct function based upon the number of parameters.

Other times you’re just browsing source code, and you’re curious what some variable could be holding as a value. Python Tools provides rich information about what an expression can possibly represent when you hover over it.

Navigation Bar

When working with a large file or class it’s often useful to quickly jump to a class or function without needing to search through the entire document. Visual Studio has traditionally provided a navigation bar in the editor’s view. It enables you to quickly jump around the document. The left hand drop down allows you to select top-level classes and function definitions while the right hand drop down allows selecting methods or nested classes within the current class. It’s as simple as clicking on the drop down and selecting where you want to go.

Go To Definition

One very handy tool when looking at source code is to be able to quickly navigate to a function definition from a caller to understand what it’s going to do. For any expression you can right click and select “Go To Definition” or press F12. Python Tools will analyze what the current expression is, and if the expression resolves to a single function, Python Tools immediately navigates to that function. If there are multiple definitions, the tool displays choices in the Find Symbol Results window, where you can double click on any definition to navigate to it.

Find All References

Another useful tool when refactoring or working with a large code base is to find all the references to a function or a class. Python Tools provides this functionality through the context menu’s Find All References or via the Shift-F12 hot key. Based upon the analysis of the code, all of the known references will be displayed in the Find Symbol Results along with the line of code where the reference appears.

You can then double click on each line to immediately navigate to the nearest reference:

Refactoring

Another feature of PTVS is Refactoring which enables method extraction and renaming and is available thru the Refactor Menu:

To rename a variable, class, method name, … simply move the caret to the identifier and type Ctrl-R Ctrl-R.  You’ll be prompted to type a new name.  You can then select which lines the changes will be applied to (All by default):

Extract method works in a similar way: select the lines you’re interested in extracting, and type Ctrl-R Ctrl-M.  You’ll get a pop up that enables you to specify a new method name, where to extract the code to (eg Module, enclosing Method or Class), and optionally any closure variables (if not selected, they become parameters):

Working with the Interactive Window

Python Tools for Visual Studio includes an interactive window for developing your code – commonly called a REPL (Read/Evaluate/Print/Loop). The interactive window supports executing files or the start file of your project. The text of the menu item will change depending on if you have a project opened or not. When in a project the command will be called “Execute Project in Python Interactive”. When working with a loose set of files the command will be “Execute File in Python Interactive”:

You can also bring up the interactive window without executing any code with the View->Other Windows->Python Interactive menu item (or Alt-I for the default interpreter), or via Tools->Python Tools->Python Interactive (the exact menu items will be different depending on which versions of Python you have installed). This opens the interactive window if it is not already open and sets focus on it. If you’ve previously used the interactive window for executing a script or for other interactive development, the contents will still be available for your perusal.

Beyond the built-in Interactive window, you can choose IPython as the main REPL. IPython is an advanced yet user-friendly interactive development environment that's cross-platform and has Interactive Parallel Computing features (discussed elsewhere). Assuming you've installed it, go to Tools/Options/Python Tools to select it:

Switching Scopes

The interactive window when initially started is in the scope for the  main  module. If you bring up the interactive window without starting a file, the module is empty. If you start a file or your project, the module contents is the starting file, as if you ran it from the command prompt. You can also view other scopes which contain user code and switch amongst them to execute code within those modules. For example, after typing “import os” a number of modules execute, and you can now switch between them using the File Scope drop down.

Selecting a module changes the current scope, and input now executes in that module. Whenever you perform any actions such as switching scopes, a log message is written to the output window, so you can keep track of how you got to a certain state during your development.
The interactive window also supports several meta commands. All meta commands start with a $, and you can type $ or $help to get a list of the meta commands. The most useful meta command is probably the command that switches between modules without using the drop down box. This command is the $mod command and is followed by the module name you’d like to switch to. Other commands include clearing the screen, running a file which can include $ commands as well, or resetting the interactive process. The commands are also extensible via MEF (the Managed Extensibility Framework for .NET).

The interactive window includes intellisense based on the live objects rather than by analyzing the source code. This differs from the editor buffers of .py files in that analysis of the code in the REPL window is not necessary. The benefits are that you always get good completion.  The drawback here is that functions which have side effects may impact your development experience. To control this behavior there are few different options in the Tools->Options->Editor->Python->Advanced menu. Here you can choose to never evaluate expressions, never evaluate expressions containing calls, or always evaluate expressions. In the never evaluate expressions mode the normal intellisense engine will be used for discovering possible completions. In the never evaluate expressions containing calls simple expressions such as “a.b” will be evaluated but expressions involving calls, such as “a.b()”, will use the normal intellisense engine. The idea here is that simple member accesses are unlikely to have side effects. Finally always evaluate expressions will execute the expression to get completion information regardless of the expression

Sending Code to Interactive

In addition to working within the interactive window there are commands available that send selected code from the editor to the interactive window. This lets you work within the interactive window, update code in the editor, and then quickly send the updated code to the interactive window.

In addition to simply sending the code to the current scope in the interactive window there is also a separate command which sends the code to the defining module. This command will search the interactive process to find the module that matches the current file being edited. If the command finds the correct module, then it uses the $module command to switch to that module. The $module command becomes part of the history of the interactive window so that the interactive buffer remains as a comprehensive history of everything you’ve done. Then the command pastes the selection into the interactive window for evaluation.

The end result of this in the interactive window is indistinguishable from if you had manually switched to the correct scope and pasted the text yourself.

The Object Browser

When a project is loaded, Python Tools supports using the Object Browser for viewing classes defined in each module and the functions defined in those classes. The left hand pane of the Object Browser enables you to view all of the modules defined and drill down into them. As you do so, the right hand side updates to reflect the current class you are browsing, and the bottom right hand pane will show you any information about the method currently selected on the right hand side.

Debugging

Python Tools includes integrated support for debugging multiple types of Python applications including attaching to Python processes, evaluating Python expressions in the watch and immediate windows, and inspecting local variables, step in, out, and over statements, set the next statement, and breaking on exceptions.

Right click on your project and choose Properties (Alt+Enter). From the Debug tab, you can choose one of four debuggers:

• Standard VS Debugger for CPython
• IronPython / .Net Debugger
• Python MPI Debugger
• Django Debugger

The Standard debugger basically works just like the VS debugger. The IronPython debugger uses the .Net debugger and allows you to debug into multi-lingual .Net projects in C#, VB, F#, ... The Python MPI Debugger supports debugging across remote processes on an HPC cluster (discussed elsewhere).

Profiling

Python Tools for Visual Studio also supports profiling your Python program (this feature is only available for CPython based interpreters and requires Visual Studio 2010 Ultimate). To start profiling you can go to the Analyze menu and and select Launch Python Profiling:

You can then use the dialog to configure how you’d like to setup profiling:

 


When you click OK the profiler will run and then open the resulting performance report. You can then drill into which functions are consuming the most time.

Note: Please see the Cluster/MPI section for Profiling code on a cluster.