Editing Python code
Developers spend much of their time in the code editor, so Python support in Visual Studio provides functionality to help you be more productive. Features include IntelliSense syntax highlighting, auto-completion, signature help, method overrides, search, and navigation.
The editor is also integrated with the interactive window in Visual Studio, making it easy to exchange code between the two. See Tutorial Step 3: Using the interactive REPL window and Using the interactive window - Send code to interactive command for details.
|Watch a video (Microsoft Virtual Academy) for a demonstration of editing Python code (2m 30s).|
For general documentation on editing code in Visual Studio, see Writing Code in the Code and Text Editor. Also see Outlining in Visual Studio, which helps you stay focused on particular sections of your code.
You can also use the Visual Studio Object Browser (View > Other Windows > Object Browser or Ctrl+W,J) for inspecting Python classes defined in each module and the functions defined in those classes.
To improve performance, IntelliSense in Visual Studio 2017 version 15.5 and earlier depends on a completion database that's generated for each Python environment in your project. Databases may need refreshing if you add, remove, or update packages. Database status is shown in the Python Environments window (a sibling of Solution Explorer) on the IntelliSense tab (see Environments window reference).
Visual Studio 2017 version 15.6 and later uses a different means to provide IntelliSense completions that are not dependent on the database.
Completions appear as statements, identifiers, and other words that may be appropriately entered at the current location in the editor. What's shown in the list is based on context and is filtered to omit incorrect or distracting options. Completions are often triggered by typing different statements (such as
import) and operators (including a period), but you can have them appear at anytime by typing Ctrl-J, Space.
When a completion list is open, you can search for the completion you want using the arrow keys, the mouse, or by continuing to type. As you type more letters, the list is further filtered to show likely completions. You can also use shortcuts such as:
- Typing letters that are not at the start of the name, such as 'parse' to find 'argparse'
- Typing only letters that are at the start of words, such as 'abc' to find 'AbstractBaseClass' or 'air' to find 'as_integer_ratio'
- Skipping letters, such as 'b64' to find 'base64'
Member completions appear automatically when you type a period after a variable or value, along with the methods and attributes of the potential types. If a variable could be more than one type, the list includes all possibilities from all types, with extra information to indicate which types support each completion. Where a completion is supported by all possible types, it is shown without annotation.
By default, "dunder" members (members beginning and ending with a double underscore) are not shown. In general, such members should not be accessed directly. If you need one, however, typing the leading double underscore adds these completions to the list:
from ... import statements display a list of modules that can be imported. With
from ... import, the list includes members that can be imported from the specified module.
except statements display lists of classes likely to be error types. The list may not include all user-defined exceptions, but helps you find suitable built-in exceptions quickly:
Typing @ starts a decorator and shows potential decorators. Many of these items aren't usable as decorators; check the library documentation to determine which to use.
You can configure the behavior of completions through Tools > Options > Text Editor > Python > Advanced". Among these, Filter list based on search string: applies filtering of completion suggestions as you type (default is checked), and Member completion displays intersection of members shows only completions that are supported by all possible types (default is unchecked). See Options - completion results.
When writing code that calls a function, signature help appears when you type the opening
( and displays available documentation and parameter information. You can also make it appear with Ctrl+Shift+Space inside a function call. The information displayed depends on the documentation strings in the function's source code, but includes any default values.
To disable signature help, go to Tools > Options > Text Editor > Python > General and clear Statement completion > Parameter information.
Hovering the mouse pointer over an identifier displays a Quick Info tooltip. Depending on the identifier, Quick Info may display the potential values or types, any available documentation, return types and, definition locations:
Code coloring uses information from code analysis to colors variables, statements, and other parts of your code. For example, variables that refer to modules or classes may be shown in a different color than functions or other values, and parameter names appear in a different color than local or global variables. (By default, functions are not shown in bold):
To customize the colors, go to Tools > Options > Environment > Fonts and Colors and modify the Python entries in the Display items list:
To disable code coloring, go to Tools > Options > Text Editor > Python > Advanced and clear Miscellaneous Options > Color names based on type. See Options - Miscellaneous Options.
Code snippets are fragments of code that can be inserted into your files by typing a shortcut and pressing Tab, or using the Edit > IntelliSense > Insert Code Snippet and Surround With commands, selecting Python, then selecting the desired snippet.
class is a shortcut for a code snippet that inserts a class definition. You see the snippet appear in the auto-completion list when you type
Pressing Tab generates the rest of the class. You can then type over the name and bases list, moving between the highlighted fields with Tab, then press Enter to begin typing the body.
When you use the Edit > IntelliSense > Insert Code Snippet menu command, you first select "Python", then select a snippet:
The Edit > IntelliSense > Surround With command, similarly, places the current selection in the text editor inside a chosen structural element. For example, suppose you had a bit of code like the following:
sum = 0 for x in range(1, 100): sum = sum + x
Selecting this code and choosing the Surround With command displays a list of available snippets. Choosing
def from the list places the selected code within a function definition, and you can use the Tab key to navigate between the highlighted function name and arguments:
Examine available snippets
You can see the available code snippets in the Code Snippets Manager, opened by using Tools > Code Snippets Manager menu command and selecting Python as the language:
To create your own snippets, see Walkthrough: Creating a Code Snippet.
If you write a great code snippet that you'd like to share, feel free to post it in a gist and let us know. We may be able to include it in a future release of Visual Studio.
Navigating your code
Python support in Visual Studio provides several means to quickly navigate within your code, including libraries for which source code is available: the navigation bar, Go To Definition, Navigate To, and Find All References. You can also use the Visual Studio Object Browser.
The navigation bar is displayed at the top of each editor window and includes a two-level list of definitions. The left drop-down contains top-level class and function definitions in the current file; the right drop-down displays a list of definitions within the scope shown in the left. As you move around in the editor, the lists update to show your current context, and you can also select an entry from these lists to jump directly to in.
To hide the navigation bar, go to Tools > Options > Text Editor > Python > General and clear Settings > Navigation bar.
Go To Definition
Go To Definition quickly jumps from the use of an identifier (such as a function name, class, or variable), to the source code where it's defined. You invoke it by right-clicking an identifier and selecting Go To Definition or, by placing the caret in the identifier and pressing F12. It works across your code and external libraries provided that source code is available. If library source code is not available, Go To Definition jumps to the relevant
import statement for a module reference, or display an error.
The Edit > Navigate To... command (Ctrl-comma) displays a search box in the editor where you can type any string and see possible matches in your code that defines a function, class, or variable containing that string. This feature provides a similar capability as Go To Definition but without having to locate a use of an identifier.
Double-clicking any name, or selecting with arrow keys and Enter, navigates to the definition of that identifier.
Find All References
Find All References is a helpful way of discovering where any given identifier is both defined and used, including imports and assignments. You invoke it by right-clicking an identifier and selecting Find All References, or by placing the caret in the identifier and pressing Shift+F12. Double-clicking an item in the list navigates to its location.