diff --git a/docs/python/debugging-symbols-for-mixed-mode-c-cpp-python.md b/docs/python/debugging-symbols-for-mixed-mode-c-cpp-python.md index f25a5f8630b..0e9c9779376 100644 --- a/docs/python/debugging-symbols-for-mixed-mode-c-cpp-python.md +++ b/docs/python/debugging-symbols-for-mixed-mode-c-cpp-python.md @@ -1,7 +1,7 @@ --- title: Symbols for mixed-mode Python/C++ debugging description: How Visual Studio provides the ability to load symbols for complete mixed-mode C++ and Python debugging. -ms.date: 01/27/2022 +ms.date: 08/18/2023 ms.topic: how-to author: cwebster-99 ms.author: cowebster @@ -11,11 +11,12 @@ ms.workload: - python - data-science --- + # Install debugging symbols for Python interpreters - [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] +[!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] -To provide a full debugging experience, the [mixed-mode Python debugger](debugging-mixed-mode-c-cpp-python-in-visual-studio.md) in Visual Studio needs debug symbols for the Python interpreter being used to parse numerous internal data structures. For *python27.dll*, for example, the corresponding symbol file is *python27.pdb*; for *python36.dll*, the symbol file is *python36.pdb*. Each version of the interpreter also supplies symbol files for a variety of modules. +To provide a full debugging experience, the [mixed-mode Python debugger](debugging-mixed-mode-c-cpp-python-in-visual-studio.md) in Visual Studio needs debug symbols for the Python interpreter being used to parse numerous internal data structures. For _python27.dll_, for example, the corresponding symbol file is _python27.pdb_; for _python36.dll_, the symbol file is _python36.pdb_. Each version of the interpreter also supplies symbol files for a variety of modules. With Visual Studio 2017 and later, the Python 3 and Anaconda 3 interpreters automatically install their respective symbols and Visual Studio finds those symbols automatically. For Visual Studio 2015 and earlier, or when using other interpreters, you need to download symbols separately and then point Visual Studio to them through the **Tools** > **Options** dialog in the **Debugging** > **Symbols** tab. These steps are detailed in the following sections. @@ -24,20 +25,20 @@ Visual Studio may prompt you when it needs symbols, typically when starting a mi - **Open symbol settings dialog** opens the **Options** dialog to the **Debugging** > **Symbols** tab. - **Download symbols for my interpreter** opens this present documentation page, in which case, select **Tools** > **Options** and navigate to the **Debugging** > **Symbols** tab to continue. - ![Mixed mode debugger symbols prompt](media/mixed-mode-debugging-symbols-required.png) + ![Mixed mode debugger symbols prompt](media/mixed-mode-debugging-symbols-required.png) ## Download symbols - Python 3.5 and later: acquire debug symbols through the Python installer. Select **Custom installation**, select **Next** to get to **Advanced Options**, then select the boxes for **Download debugging symbols** and **Download debug binaries**: - ![Python 3.x installer including debug symbols](media/mixed-mode-debugging-symbols-installer35.png) + ![Python 3.x installer including debug symbols](media/mixed-mode-debugging-symbols-installer35.png) - The symbol files (*.pdb*) are then found in the root installation folder (symbol files for individual modules are in the *DLLs* folder as well). Because of this, Visual Studio finds them automatically, and no further steps are needed. + The symbol files (_.pdb_) are then found in the root installation folder (symbol files for individual modules are in the _DLLs_ folder as well). Because of this, Visual Studio finds them automatically, and no further steps are needed. -- Python 3.4.x and earlier: symbols are available as downloadable *.zip* files from the [official distributions](#official-distributions) or [Enthought Canopy](#enthought-canopy). After downloading, extract files to a local folder to continue, such as a *Symbols* folder within the Python folder. +- Python 3.4.x and earlier: symbols are available as downloadable _.zip_ files from the [official distributions](#official-distributions) or [Enthought Canopy](#enthought-canopy). After downloading, extract files to a local folder to continue, such as a _Symbols_ folder within the Python folder. - > [!Important] - > Symbols differ between minor builds of Python, and between 32-bit and 64-bit builds, so you want to exactly match the versions. To check the interpreter being used, expand the **Python Environments** *node* under your project in **Solution Explorer** and note the environment name. Then switch to the **Python Environments** *window* and note the install location. Then open a command window in that location and start *python.exe*, which displays the exact version and whether it's 32-bit or 64-bit. + > [!Important] + > Symbols differ between minor builds of Python, and between 32-bit and 64-bit builds, so you want to exactly match the versions. To check the interpreter being used, expand the **Python Environments** _node_ under your project in **Solution Explorer** and note the environment name. Then switch to the **Python Environments** _window_ and note the install location. Then open a command window in that location and start _python.exe_, which displays the exact version and whether it's 32-bit or 64-bit. - For any other third-party Python distribution such as ActiveState Python: contact the authors of that distribution and request them to provide you with symbols. WinPython, for its part, incorporates the standard Python interpreter without changes, so use symbols from the official distribution for the corresponding version number. @@ -47,9 +48,9 @@ If you downloaded symbols separately, follow the steps below to make Visual Stud 1. Select the **Tools** > **Options** menu and navigate to **Debugging** > **Symbols**. -1. Select the **Add** button on the toolbar (outlined below), enter the folder where you expanded the downloaded symbols (which is where *python.pdb* is located, such as *c:\python34\Symbols*, shown below), and select **OK**. +1. Select the **Add** button on the toolbar (outlined below), enter the folder where you expanded the downloaded symbols (which is where _python.pdb_ is located, such as _c:\python34\Symbols_, shown below), and select **OK**. - ![Mixed mode debugger symbols options](media/mixed-mode-debugging-symbols.png) + ![Mixed mode debugger symbols options](media/mixed-mode-debugging-symbols.png) 1. During a debugging session, Visual Studio might also prompt you for the location of a source file for the Python interpreter. If you've downloaded source files (from [python.org/downloads/](https://www.python.org/downloads/), for example), then you of course can point to them as well. @@ -58,41 +59,41 @@ If you downloaded symbols separately, follow the steps below to make Visual Stud ## Official distributions -| Python version | Downloads | -| --- | --- | -| 3.5 and later | Install symbols through the Python installer. | -| 3.4.4 | [32-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4.amd64-pdb.zip) | -| 3.4.3 | [32-bit](https://www.python.org/ftp/python/3.4.3/python-3.4.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.3/python-3.4.3.amd64-pdb.zip) | -| 3.4.2 | [32-bit](https://www.python.org/ftp/python/3.4.2/python-3.4.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.2/python-3.4.2.amd64-pdb.zip) | -| 3.4.1 | [32-bit](https://www.python.org/ftp/python/3.4.1/python-3.4.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.1/python-3.4.1.amd64-pdb.zip) | -| 3.4.0 | [32-bit](https://www.python.org/ftp/python/3.4.0/python-3.4.0-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.0/python-3.4.0.amd64-pdb.zip) | -| 3.3.5 | [32-bit](https://www.python.org/ftp/python/3.3.5/python-3.3.5-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.5/python-3.3.5.amd64-pdb.zip) | -| 3.3.4 | [32-bit](https://www.python.org/ftp/python/3.3.4/python-3.3.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.4/python-3.3.4.amd64-pdb.zip) | -| 3.3.3 | [32-bit](https://www.python.org/ftp/python/3.3.3/python-3.3.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.3/python-3.3.3.amd64-pdb.zip) | -| 3.3.2 | [32-bit](https://www.python.org/ftp/python/3.3.2/python-3.3.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.2/python-3.3.2.amd64-pdb.zip) | -| 3.3.1 | [32-bit](https://www.python.org/ftp/python/3.3.1/python-3.3.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.1/python-3.3.1.amd64-pdb.zip) | -| 3.3.0 | [32-bit](https://www.python.org/ftp/python/3.3.0/python-3.3.0-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.0/python-3.3.0.amd64-pdb.zip) | -| 2.7.18 | [32-bit](https://www.python.org/ftp/python/2.7.18/python-2.7.18-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.18/python-2.7.18.amd64-pdb.zip) | -| 2.7.17 | [32-bit](https://www.python.org/ftp/python/2.7.17/python-2.7.17-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.17/python-2.7.17.amd64-pdb.zip) | -| 2.7.16 | [32-bit](https://www.python.org/ftp/python/2.7.16/python-2.7.16-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.16/python-2.7.16.amd64-pdb.zip) | -| 2.7.15 | [32-bit](https://www.python.org/ftp/python/2.7.15/python-2.7.15-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.15/python-2.7.15.amd64-pdb.zip) | -| 2.7.14 | [32-bit](https://www.python.org/ftp/python/2.7.14/python-2.7.14-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.14/python-2.7.14.amd64-pdb.zip) | -| 2.7.13 | [32-bit](https://www.python.org/ftp/python/2.7.13/python-2.7.13-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.13/python-2.7.13.amd64-pdb.zip) | -| 2.7.12 | [32-bit](https://www.python.org/ftp/python/2.7.12/python-2.7.12-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.12/python-2.7.12.amd64-pdb.zip) | -| 2.7.11 | [32-bit](https://www.python.org/ftp/python/2.7.11/python-2.7.11-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64-pdb.zip) | -| 2.7.10 | [32-bit](https://www.python.org/ftp/python/2.7.10/python-2.7.10-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.10/python-2.7.10.amd64-pdb.zip) | -| 2.7.9 | [32-bit](https://www.python.org/ftp/python/2.7.9/python-2.7.9-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.9/python-2.7.9.amd64-pdb.zip) | -| 2.7.8 | [32-bit](https://www.python.org/ftp/python/2.7.8/python-2.7.8-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.8/python-2.7.8.amd64-pdb.zip) | -| 2.7.7 | [32-bit](https://www.python.org/ftp/python/2.7.7/python-2.7.7-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.7/python-2.7.7.amd64-pdb.zip) | -| 2.7.6 | [32-bit](https://www.python.org/ftp/python/2.7.6/python-2.7.6-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.6/python-2.7.6.amd64-pdb.zip) | -| 2.7.5 | [32-bit](https://www.python.org/ftp/python/2.7.5/python-2.7.5-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.5/python-2.7.5.amd64-pdb.zip) | -| 2.7.4 | [32-bit](https://www.python.org/ftp/python/2.7.4/python-2.7.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.4/python-2.7.4.amd64-pdb.zip) | -| 2.7.3 | [32-bit](https://www.python.org/ftp/python/2.7.3/python-2.7.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.3/python-2.7.3.amd64-pdb.zip) | -| 2.7.2 | [32-bit](https://www.python.org/ftp/python/2.7.2/python-2.7.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.2/python-2.7.2.amd64-pdb.zip) | -| 2.7.1 | [32-bit](https://www.python.org/ftp/python/2.7.1/python-2.7.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.1/python-2.7.1.amd64-pdb.zip) | +| Python version | Downloads | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 3.5 and later | Install symbols through the Python installer. | +| 3.4.4 | [32-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.4/python-3.4.4.amd64-pdb.zip) | +| 3.4.3 | [32-bit](https://www.python.org/ftp/python/3.4.3/python-3.4.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.3/python-3.4.3.amd64-pdb.zip) | +| 3.4.2 | [32-bit](https://www.python.org/ftp/python/3.4.2/python-3.4.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.2/python-3.4.2.amd64-pdb.zip) | +| 3.4.1 | [32-bit](https://www.python.org/ftp/python/3.4.1/python-3.4.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.1/python-3.4.1.amd64-pdb.zip) | +| 3.4.0 | [32-bit](https://www.python.org/ftp/python/3.4.0/python-3.4.0-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.4.0/python-3.4.0.amd64-pdb.zip) | +| 3.3.5 | [32-bit](https://www.python.org/ftp/python/3.3.5/python-3.3.5-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.5/python-3.3.5.amd64-pdb.zip) | +| 3.3.4 | [32-bit](https://www.python.org/ftp/python/3.3.4/python-3.3.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.4/python-3.3.4.amd64-pdb.zip) | +| 3.3.3 | [32-bit](https://www.python.org/ftp/python/3.3.3/python-3.3.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.3/python-3.3.3.amd64-pdb.zip) | +| 3.3.2 | [32-bit](https://www.python.org/ftp/python/3.3.2/python-3.3.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.2/python-3.3.2.amd64-pdb.zip) | +| 3.3.1 | [32-bit](https://www.python.org/ftp/python/3.3.1/python-3.3.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.1/python-3.3.1.amd64-pdb.zip) | +| 3.3.0 | [32-bit](https://www.python.org/ftp/python/3.3.0/python-3.3.0-pdb.zip) - [64-bit](https://www.python.org/ftp/python/3.3.0/python-3.3.0.amd64-pdb.zip) | +| 2.7.18 | [32-bit](https://www.python.org/ftp/python/2.7.18/python-2.7.18-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.18/python-2.7.18.amd64-pdb.zip) | +| 2.7.17 | [32-bit](https://www.python.org/ftp/python/2.7.17/python-2.7.17-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.17/python-2.7.17.amd64-pdb.zip) | +| 2.7.16 | [32-bit](https://www.python.org/ftp/python/2.7.16/python-2.7.16-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.16/python-2.7.16.amd64-pdb.zip) | +| 2.7.15 | [32-bit](https://www.python.org/ftp/python/2.7.15/python-2.7.15-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.15/python-2.7.15.amd64-pdb.zip) | +| 2.7.14 | [32-bit](https://www.python.org/ftp/python/2.7.14/python-2.7.14-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.14/python-2.7.14.amd64-pdb.zip) | +| 2.7.13 | [32-bit](https://www.python.org/ftp/python/2.7.13/python-2.7.13-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.13/python-2.7.13.amd64-pdb.zip) | +| 2.7.12 | [32-bit](https://www.python.org/ftp/python/2.7.12/python-2.7.12-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.12/python-2.7.12.amd64-pdb.zip) | +| 2.7.11 | [32-bit](https://www.python.org/ftp/python/2.7.11/python-2.7.11-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64-pdb.zip) | +| 2.7.10 | [32-bit](https://www.python.org/ftp/python/2.7.10/python-2.7.10-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.10/python-2.7.10.amd64-pdb.zip) | +| 2.7.9 | [32-bit](https://www.python.org/ftp/python/2.7.9/python-2.7.9-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.9/python-2.7.9.amd64-pdb.zip) | +| 2.7.8 | [32-bit](https://www.python.org/ftp/python/2.7.8/python-2.7.8-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.8/python-2.7.8.amd64-pdb.zip) | +| 2.7.7 | [32-bit](https://www.python.org/ftp/python/2.7.7/python-2.7.7-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.7/python-2.7.7.amd64-pdb.zip) | +| 2.7.6 | [32-bit](https://www.python.org/ftp/python/2.7.6/python-2.7.6-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.6/python-2.7.6.amd64-pdb.zip) | +| 2.7.5 | [32-bit](https://www.python.org/ftp/python/2.7.5/python-2.7.5-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.5/python-2.7.5.amd64-pdb.zip) | +| 2.7.4 | [32-bit](https://www.python.org/ftp/python/2.7.4/python-2.7.4-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.4/python-2.7.4.amd64-pdb.zip) | +| 2.7.3 | [32-bit](https://www.python.org/ftp/python/2.7.3/python-2.7.3-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.3/python-2.7.3.amd64-pdb.zip) | +| 2.7.2 | [32-bit](https://www.python.org/ftp/python/2.7.2/python-2.7.2-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.2/python-2.7.2.amd64-pdb.zip) | +| 2.7.1 | [32-bit](https://www.python.org/ftp/python/2.7.1/python-2.7.1-pdb.zip) - [64-bit](https://www.python.org/ftp/python/2.7.1/python-2.7.1.amd64-pdb.zip) | ## Enthought Canopy -Enthought Canopy provides symbols for its binaries starting from version 1.2. They are automatically installed alongside with the distribution, but you still need to manually add the folder containing them to symbol path as described earlier. For a typical per-user installation of Canopy, the symbols are located in *%UserProfile%\AppData\Local\Enthought\Canopy\User\Scripts* for the 64-bit version and *%UserProfile%\AppData\Local\Enthought\Canopy32\User\Scripts* for the 32-bit version. +Enthought Canopy provides symbols for its binaries starting from version 1.2. They are automatically installed alongside with the distribution, but you still need to manually add the folder containing them to symbol path as described earlier. For a typical per-user installation of Canopy, the symbols are located in _%UserProfile%\AppData\Local\Enthought\Canopy\User\Scripts_ for the 64-bit version and _%UserProfile%\AppData\Local\Enthought\Canopy32\User\Scripts_ for the 32-bit version. Enthought Canopy 1.1 and earlier, as well as Enthought Python Distribution (EPD), do not provide interpreter symbols, and are therefore not compatible with mixed-mode debugging. diff --git a/docs/python/includes/project-from-existing.md b/docs/python/includes/project-from-existing.md index 5bd4a490a0c..7d3020a9464 100644 --- a/docs/python/includes/project-from-existing.md +++ b/docs/python/includes/project-from-existing.md @@ -1,24 +1,25 @@ --- ms.topic: include --- + 1. Launch Visual Studio and select **File** > **New** > **Project**. 1. In the **New Project** dialog, search for "Python", select the **From Existing Python code** template, give the project a name and location, and select **OK**. 1. In the wizard that appears, set the path to your existing code, set a filter for file types, and specify any search paths that your project requires, then select **Next**. If you don't know what search paths are, leave that field blank. - :::image type="content" source="../media/projects-from-existing-1.png" alt-text="Screenshot of a New Project creation from Existing Code window, step 1."::: + :::image type="content" source="../media/projects-from-existing-1.png" alt-text="Screenshot of a New Project creation from Existing Code window, step 1."::: 1. In the next dialog, select the startup file for your project and select **Next**. If necessary, select an environment; otherwise accept the defaults. - > [!Note] - > The dialog shows only files in the root folder; if the file you want is in a subfolder, leave the startup file blank and set it later in **Solution Explorer** (described next). + > [!Note] + > The dialog shows only files in the root folder; if the file you want is in a subfolder, leave the startup file blank and set it later in **Solution Explorer** (described next). - :::image type="content" source="../media/projects-from-existing-2.png" alt-text="Screenshot of New Project Creation from Existing Code window, step 2."::: + :::image type="content" source="../media/projects-from-existing-2.png" alt-text="Screenshot of New Project Creation from Existing Code window, step 2."::: -1. Select the location in which to save the project file (which is a `.pyproj` file on disk). If applicable, you can also include autodetection of virtual environments and customize the project for different web frameworks. If you're unsure of these options, leave them set to the defaults. +1. Select the location in which to save the project file (which is a `.pyproj` file on disk). If applicable, you can also include auto-detection of virtual environments and customize the project for different web frameworks. If you're unsure of these options, leave them set to the defaults. - :::image type="content" source="../media/projects-from-existing-3.png" alt-text="Screenshot of a New Project creation from Existing Code window, step 3."::: + :::image type="content" source="../media/projects-from-existing-3.png" alt-text="Screenshot of a New Project creation from Existing Code window, step 3."::: 1. Select **Finish** and Visual Studio creates the project and opens it in **Solution Explorer**. If you want to move the `.pyproj` file elsewhere, select it in **Solution Explorer** and choose **File** > **Save As**. This action updates file references in the project but doesn't move any code files. diff --git a/docs/python/includes/vs-2019/unit-testing-python.md b/docs/python/includes/vs-2019/unit-testing-python.md index 1597a058fee..8879cb0b051 100644 --- a/docs/python/includes/vs-2019/unit-testing-python.md +++ b/docs/python/includes/vs-2019/unit-testing-python.md @@ -1,7 +1,7 @@ --- title: Unit test Python code description: Setting up unit testing for Python code in Visual Studio takes full advantage of Test Explorer features to discover, run, and debug tests. -ms.date: 04/01/2022 +ms.date: 08/18/2023 ms.topic: how-to author: cwebster-99 ms.author: cowebster @@ -15,16 +15,18 @@ ms.workload: ## Select the test framework for a Python project -Visual Studio supports two testing frameworks for Python, [unittest](https://docs.python.org/3/library/unittest.html) and [pytest](https://pytest.org/en/latest/) (available in Visual Studio 2019 starting with version 16.3). By default, no framework is selected when you create a Python project. To specify a framework, right-click on the project name in Solution Explorer and select the **Properties** option. This opens the project designer, which allows you to configure tests through the **Test** tab. From this tab, you can select the test framework that you want to use for your project. +Visual Studio supports two testing frameworks for Python, [unittest](https://docs.python.org/3/library/unittest.html) and [pytest](https://pytest.org/en/latest/) (available in Visual Studio 2019 starting with version 16.3). By default, no framework is selected when you create a Python project. To specify a framework, right-click on the project name in Solution Explorer and select the **Properties** option. This opens the project designer, which allows you to configure tests through the **Test** tab. From this tab, you can select the test framework that you want to use for your project. -* For the **unittest** framework, the project's root directory is used for test discovery. This location, as well as the text pattern for identifying tests, can be modified on the **Test** tab to user specified values. -* For the **pytest** framework, testing options such as test location and filename patterns are specified using the standard pytest .ini configuration file. See the [pytest reference documentation](https://docs.pytest.org/en/latest/reference.html#ini-options-ref) for more details. +- For the **unittest** framework, the project's root directory is used for test discovery. This location, as well as the text pattern for identifying tests, can be modified on the **Test** tab to user specified values. +- For the **pytest** framework, testing options such as test location and filename patterns are specified using the standard pytest .ini configuration file. See the [pytest reference documentation](https://docs.pytest.org/en/latest/reference.html#ini-options-ref) for more details. Once you've saved your framework selection and settings, test discovery is initiated in the Test Explorer. If the Test Explorer window is not already open, navigate to the toolbar and select **Test** > **Test Explorer**. ## Configure testing for Python without a project -Visual Studio allows you to run and test existing Python code without a project, by [opening a folder](../../quickstart-05-python-visual-studio-open-folder.md) with Python code. Under these circumstances, you'll need to use a **PythonSettings.json** file to configure testing. -1. Open your existing Python code using the **Open a Local Folder** option. + +Visual Studio allows you to run and test existing Python code without a project, by [opening a folder](../../quickstart-05-python-visual-studio-open-folder.md) with Python code. Under these circumstances, you'll need to use a **PythonSettings.json** file to configure testing. + +1. Open your existing Python code using the **Open a Local Folder** option. ![The Visual Studio startup screen](../../media/quickstart-open-folder/01-open-local-folder.png) @@ -33,32 +35,31 @@ Visual Studio allows you to run and test existing Python code without a project, ![Show all files button](../../media/unit-test-show-files.png) 1. Navigate to the **PythonSettings.json** file within the **Local Settings** folder. If you don't see this file in the **Local Settings** folder, create it manually. - 1. Add the field **TestFramework** to the settings file and set it to **pytest** or **unittest** depending on the testing framework you want to use. - ```json - { - "TestFramework": "unittest", - "UnitTestRootDirectory": "testing", - "UnitTestPattern": "test_*.py" - } - ``` + ```json + { + "TestFramework": "unittest", + "UnitTestRootDirectory": "testing", + "UnitTestPattern": "test_*.py" + } + ``` - > [!Note] - > For the **unittest** framework, if the fields **UnitTestRootDirectory** and **UnitTestPattern** are not specified in the PythonSettings.json file, they are added and assigned default values of "." and "test*.py" respectively. + > [!Note] + > For the **unittest** framework, if the fields **UnitTestRootDirectory** and **UnitTestPattern** are not specified in the PythonSettings.json file, they are added and assigned default values of "." and "test\*.py" respectively. 1. If your folder contains a **src** directory that is separate from the folder that contains your tests, specify the path to the **src** folder using the **SearchPaths** field in your **PythonSettings.json** file. - ```json - { - "TestFramework": "unittest", - "UnitTestRootDirectory": "testing", - "UnitTestPattern": "test_*.py", - "SearchPaths": [ ".\\src"] - } - ``` + ```json + { + "TestFramework": "unittest", + "UnitTestRootDirectory": "testing", + "UnitTestPattern": "test_*.py", + "SearchPaths": [".\\src"] + } + ``` -1. Save your changes to the PythonSettings.json file to initiate test discovery for the specified framework. +1. Save your changes to the PythonSettings.json file to initiate test discovery for the specified framework. > [!Note] > If the Test Explorer window is already open **CTRL** + **R,A** also triggers discovery. @@ -69,33 +70,34 @@ By default, Visual Studio identifies **unittest** and **pytest** tests as method 1. Open a [Python project](../../managing-python-projects-in-visual-studio.md). 1. Once the project is loaded in Visual Studio, right-click your project in Solution Explorer and select the **unittest** or **pytest** framework from the Properties **Test** tab. + > [!Note] > If you use the pytest framework, you can specify test location and filename patterns using the standard pytest .ini configuration file. By default, the workspace/project folder is used, with a pattern of `test_*py` and `*_test.py`. See the [pytest reference documentation](https://docs.pytest.org/en/latest/reference.html#ini-options-ref) for more details. 1. After the framework is selected, right-click the project again and select **Add** > **New Item**, then select **Python Unit Test** followed by **Add**. -1. This action creates a *test_1.py* file with code that imports the standard `unittest` module, derives a test class from `unittest.TestCase`, and invokes `unittest.main()` if you run the script directly: +1. This action creates a _test_1.py_ file with code that imports the standard `unittest` module, derives a test class from `unittest.TestCase`, and invokes `unittest.main()` if you run the script directly: - ```python - import unittest + ```python + import unittest - class Test_test1(unittest.TestCase): - def test_A(self): - self.fail("Not implemented") + class Test_test1(unittest.TestCase): + def test_A(self): + self.fail("Not implemented") - if __name__ == '__main__': - unittest.main() - ``` + if __name__ == '__main__': + unittest.main() + ``` 1. Save the file if necessary, then open **Test Explorer** with the **Test** > **Test Explorer** menu command. 1. **Test Explorer** searches your project for tests and displays them as shown below. Double-clicking a test opens its source file. - ![Test Explorer showing default test_A](../../media/unit-test-a-2.png) + ![Test Explorer showing default test_A](../../media/unit-test-a-2.png) 1. As you add more tests to your project, you can organize the view in **Test Explorer** using the **Group By** menu on the toolbar: - ![Tests Explorer Group By toolbar menu](../../media/unit-test-group-menu-2.png) + ![Tests Explorer Group By toolbar menu](../../media/unit-test-group-menu-2.png) 1. You can also enter text in the **Search** field to filter tests by name. @@ -113,20 +115,20 @@ Tests run in the background and **Test Explorer** updates each test's status as - Passing tests show a green tick and the time taken to run the test: - ![test_A passed status](../../media/unit-test-A-pass.png) + ![test_A passed status](../../media/unit-test-A-pass.png) - Failed tests show a red cross with an **Output** link that shows console output and `unittest` output from the test run: - ![test_A failed status](../../media/unit-test-A-fail.png) + ![test_A failed status](../../media/unit-test-A-fail.png) - ![test_A failed with reason](../../media/unit-test-A-fail-reason.png) + ![test_A failed with reason](../../media/unit-test-A-fail-reason.png) ## Debug tests Because unit tests are pieces of code, they are subject to bugs just like any other code and occasionally need to be run in a debugger. In the debugger you can set breakpoints, examine variables, and step through code. Visual Studio also provides diagnostic tools for unit tests. > [!Note] -> By default, test debugging uses the ptvsd 4 debugger for Visual Studio 2017 (versions 15.8 and later) and debugpy for Visual Studio 2019 (versions 16.5 and later). If you would like to instead use ptvsd 3, you can select the **Use Legacy Debugger** option on **Tools** > **Options** > **Python** > **Debugging**. +> By default, test debugging uses the ptvsd 4 debugger for Visual Studio 2017 (versions 15.8 and later) and debugpy for Visual Studio 2019 (versions 16.5 and later). If you would like to instead use ptvsd 3, you can select the **Use Legacy Debugger** option on **Tools** > **Options** > **Python** > **Debugging**. To start debugging, set an initial breakpoint in your code, then right-click the test (or a selection) in **Test Explorer** and select **Debug Selected Tests**. Visual Studio starts the Python debugger as it would for application code. diff --git a/docs/python/managing-python-projects-in-visual-studio.md b/docs/python/managing-python-projects-in-visual-studio.md index c3dca54a656..f6fce90aa17 100644 --- a/docs/python/managing-python-projects-in-visual-studio.md +++ b/docs/python/managing-python-projects-in-visual-studio.md @@ -1,7 +1,7 @@ --- title: Manage Python application projects description: Projects in Visual Studio manage dependencies between files and the complexity of relationships in an application. -ms.date: 02/10/2022 +ms.date: 08/18/2023 ms.topic: conceptual author: cwebster-99 ms.author: cowebster @@ -12,15 +12,16 @@ ms.workload: - python - data-science --- + # Python projects in Visual Studio - [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] +[!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] -Python applications are typically defined using only folders and files, but this structure can become complex as applications become larger and perhaps involve auto-generated files, JavaScript for web applications, and so on. A Visual Studio project helps manage this complexity. The project (a *.pyproj* file) identifies all the source and content files associated with your project, contains build information for each file, maintains the information to integrate with source-control systems, and helps you organize your application into logical components. +Python applications are typically defined using only folders and files, but this structure can become complex as applications become larger and perhaps involve auto-generated files, JavaScript for web applications, and so on. A Visual Studio project helps manage this complexity. The project (a _.pyproj_ file) identifies all the source and content files associated with your project, contains build information for each file, maintains the information to integrate with source-control systems, and helps you organize your application into logical components. ![Python project in Solution Explorer](media/projects-solution-explorer.png) -In addition, projects are always managed within a Visual Studio *solution*, which can contain any number of projects that might reference one another. For example, a Python project can reference a C++ project that implements an extension module. With this relationship, Visual Studio automatically builds the C++ project (if necessary) when you start debugging the Python project. (For a general discussion, see [Solutions and projects in Visual Studio](../ide/solutions-and-projects-in-visual-studio.md).) +In addition, projects are always managed within a Visual Studio _solution_, which can contain any number of projects that might reference one another. For example, a Python project can reference a C++ project that implements an extension module. With this relationship, Visual Studio automatically builds the C++ project (if necessary) when you start debugging the Python project. (For a general discussion, see [Solutions and projects in Visual Studio](../ide/solutions-and-projects-in-visual-studio.md).) Visual Studio provides a variety of Python project templates to quickly set up a number of application structures, including a template to create a project from an existing folder tree and a template to create a clean, empty project. See [Project templates](#project-templates) for an index. @@ -47,33 +48,49 @@ Each Python project has one assigned start-up file, shown in boldface in **Solut A new project is always associated with the default global Python environment. To associate the project with a different environment (including virtual environments), right-click the **Python Environments** node in the project, select **Add Environment..**, and select the ones you want. You can also use the environments drop-down control on the toolbar to select and environment or add another one to the project. -![Add Environment command on the Python toolbar](media/environments/environments-toolbar-2019.png) +![Add Environment command on the Python toolbar](media/vs-2022/environments-toolbar-2022.png) To change the active environment, right-click the desired environment in **Solution Explorer** and select **Activate Environment** as shown below. For more information, see [Select an environment for a project](selecting-a-python-environment-for-a-project.md). -![Activating an environment for a Python project](media/projects-activate-environment.png) +![Activating an environment for a Python project](media/vs-2022/projects-activate-environment-2022.png) ## Project templates -Visual Studio gives you a number of ways to set up a Python project, either from scratch or from existing code. To use a template, select the **File** > **New** > **Project** menu command or right-click the solution in **Solution Explorer** and select **Add** > **New Project**, both of which bring up the **New Project** dialog below. To see Python-specific templates, either search on "Python" or select the **Installed** > **Python** node: +Visual Studio gives you a number of ways to set up a Python project, either from scratch or from existing code. To use a template, select the **File** > **New** > **Project** menu command or right-click the solution in **Solution Explorer** and select **Add** > **New Project**, both of which bring up the **New Project** dialog below. To see Python-specific templates, either search on "Python" or select the **Language** > **Python** node: ![New project dialog with Python templates](media/projects-new-project-dialog.png) +:::moniker range=">=vs-2022" +The following table summarizes the templates available in Visual Studio 2022: + +| Template | Description | +| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**From existing Python code**](#create-project-from-existing-files) | Creates a Visual Studio project from existing Python code in a folder structure. | +| **Python Application** | A basic project structure for a new Python application with a single, empty source file. By default, the project runs in the console interpreter of the default global environment, which you can change by [assigning a different environment](selecting-a-python-environment-for-a-project.md). | +| [**Web projects**](python-web-application-project-templates.md) | Projects for web apps based on various frameworks including Bottle, Django, and Flask. | +| **Background Application (IoT)** | Supports deploying Python projects to run as background services on devices. Visit the [Windows IoT Dev Center](https://dev.windows.com/en-us/iot) for more information. | +| **Python Extension Module** | This template appears under Visual C++ if you've installed the **Python native development tools** with the Python workload in Visual Studio 2017 or later (see [Installation](installing-python-support-in-visual-studio.md)). It provides the core structure for a C++ extension DLL, similar to what's described on [Create a C++ extension for Python](working-with-c-cpp-python-in-visual-studio.md). | + +::: moniker-end + +:::moniker range="<=vs-2019" The following table summarizes the templates available in Visual Studio 2019 (not all templates are available in all previous versions): -| Template | Description | -| --- | --- | -| [**From existing Python code**](#create-project-from-existing-files) | Creates a Visual Studio project from existing Python code in a folder structure. | -| **Python Application** | A basic project structure for a new Python application with a single, empty source file. By default, the project runs in the console interpreter of the default global environment, which you can change by [assigning a different environment](selecting-a-python-environment-for-a-project.md). | -| [**Web projects**](python-web-application-project-templates.md) | Projects for web apps based on various frameworks including Bottle, Django, and Flask. | -| **IronPython Application** | Similar to the Python Application template, but uses IronPython by default enabling .NET interop and mixed-mode debugging with .NET languages. | -| **IronPython WPF Application** | A project structure using IronPython with Windows Presentation Foundation XAML files for the application's user interface. Visual Studio provides a XAML UI designer, code-behind can be written in Python, and the application runs without displaying a console. | -| **IronPython Silverlight Web Page** | An IronPython project that runs in a browser using Silverlight. The application's Python code is included in the web page as script. A boilerplate script tag pulls down some JavaScript code that initializes IronPython running inside of Silverlight, from which your Python code can interact with the DOM. | -| **IronPython Windows Forms Application** | A project structure using IronPython with UI created using code with Windows Forms. The application runs without displaying a console. | -| **Background Application (IoT)** | Supports deploying Python projects to run as background services on devices. Visit the [Windows IoT Dev Center](https://dev.windows.com/en-us/iot) for more information. | -| **Python Extension Module** | This template appears under Visual C++ if you've installed the **Python native development tools** with the Python workload in Visual Studio 2017 or later (see [Installation](installing-python-support-in-visual-studio.md)). It provides the core structure for a C++ extension DLL, similar to what's described on [Create a C++ extension for Python](working-with-c-cpp-python-in-visual-studio.md). | +| Template | Description | +| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**From existing Python code**](#create-project-from-existing-files) | Creates a Visual Studio project from existing Python code in a folder structure. | +| **Python Application** | A basic project structure for a new Python application with a single, empty source file. By default, the project runs in the console interpreter of the default global environment, which you can change by [assigning a different environment](selecting-a-python-environment-for-a-project.md). | +| [**Web projects**](python-web-application-project-templates.md) | Projects for web apps based on various frameworks including Bottle, Django, and Flask. | +| **IronPython Application** | Similar to the Python Application template, but uses IronPython by default enabling .NET interop and mixed-mode debugging with .NET languages. | +| **IronPython WPF Application** | A project structure using IronPython with Windows Presentation Foundation XAML files for the application's user interface. Visual Studio provides a XAML UI designer, code-behind can be written in Python, and the application runs without displaying a console. | +| **IronPython Silverlight Web Page** | An IronPython project that runs in a browser using Silverlight. The application's Python code is included in the web page as script. A boilerplate script tag pulls down some JavaScript code that initializes IronPython running inside of Silverlight, from which your Python code can interact with the DOM. | +| **IronPython Windows Forms Application** | A project structure using IronPython with UI created using code with Windows Forms. The application runs without displaying a console. | +| **Background Application (IoT)** | Supports deploying Python projects to run as background services on devices. Visit the [Windows IoT Dev Center](https://dev.windows.com/en-us/iot) for more information. | +| **Python Extension Module** | This template appears under Visual C++ if you've installed the **Python native development tools** with the Python workload in Visual Studio 2017 or later (see [Installation](installing-python-support-in-visual-studio.md)). It provides the core structure for a C++ extension DLL, similar to what's described on [Create a C++ extension for Python](working-with-c-cpp-python-in-visual-studio.md). | + +::: moniker-end > [!Note] > Because Python is an interpreted language, Python projects in Visual Studio don't produce a stand-alone executable like other compiled language projects (C#, for example). For more information, see [questions and answers](overview-of-python-tools-for-visual-studio.md#questions-and-answers). @@ -91,7 +108,7 @@ The following table summarizes the templates available in Visual Studio 2019 (no Linked files are files that are brought into a project but typically reside outside of the application's project folders. They appear in **Solution Explorer** as normal files with an overlaid shortcut icon: ![Linked file icon](media/projects-linked-file-icon.png) -Linked files are specified in the *.pyproj* file using the `` element. Linked files are implicit if they use a relative path outside of the directory structure, or explicit if they use paths within **Solution Explorer**: +Linked files are specified in the _.pyproj_ file using the `` element. Linked files are implicit if they use a relative path outside of the directory structure, or explicit if they use paths within **Solution Explorer**: ```xml @@ -126,7 +143,7 @@ Extension references typically indicate dependencies between projects and are us ### Extension modules -A reference to a *.pyd* file enables IntelliSense for the generated module. Visual Studio loads the *.pyd* file into the Python interpreter and introspects its types and functions. It also attempts to parse the doc strings for functions to provide signature help. +A reference to a _.pyd_ file enables IntelliSense for the generated module. Visual Studio loads the _.pyd_ file into the Python interpreter and introspects its types and functions. It also attempts to parse the doc strings for functions to provide signature help. If at any time the extension module is updated on disk, Visual Studio reanalyzes the module in the background. This action has no effect on run-time behavior but some completions aren't available until analysis is complete. @@ -136,7 +153,7 @@ You may also need to add a [search path](search-paths.md) to the folder containi When working with IronPython, you can add references to .NET assemblies to enable IntelliSense. For .NET projects in your solution, right-click the **References** node in your Python project, select **Add Reference**, select the **Projects** tab, and browse to the desired project. For DLLs that you've downloaded separately, select the **Browse** tab instead and browse to the desired DLL. -Because references in IronPython are not available until a call to `clr.AddReference('')` is made, you also need to add an appropriate `clr.AddReference` call to the assembly, typically at the beginning of your code. For example, the code created by the **IronPython Windows Forms Application** project template in Visual Studio includes two calls at the top of the file: +Because references in IronPython are not available until a call to `clr.AddReference('')` is made, you also need to add an appropriate `clr.AddReference` call to the assembly, typically at the beginning of your code. For example, the code created by the **IronPython Windows Forms Application** (available in Visual Studio 2019) project template in Visual Studio includes two calls at the top of the file: ```python import clr diff --git a/docs/python/media/projects-extension-references.png b/docs/python/media/projects-extension-references.png index 003e5a0548d..f03321832cf 100644 Binary files a/docs/python/media/projects-extension-references.png and b/docs/python/media/projects-extension-references.png differ diff --git a/docs/python/media/projects-new-project-dialog.png b/docs/python/media/projects-new-project-dialog.png index 457992fe293..f1c6256bc71 100644 Binary files a/docs/python/media/projects-new-project-dialog.png and b/docs/python/media/projects-new-project-dialog.png differ diff --git a/docs/python/media/projects-solution-explorer.png b/docs/python/media/projects-solution-explorer.png index 95c5616cf9a..74782861f29 100644 Binary files a/docs/python/media/projects-solution-explorer.png and b/docs/python/media/projects-solution-explorer.png differ diff --git a/docs/python/media/unit-test-show-files.png b/docs/python/media/unit-test-show-files.png index 8d68b3bdfc1..61bde369e03 100644 Binary files a/docs/python/media/unit-test-show-files.png and b/docs/python/media/unit-test-show-files.png differ diff --git a/docs/python/media/vs-2022/environments-toolbar-2022.png b/docs/python/media/vs-2022/environments-toolbar-2022.png new file mode 100644 index 00000000000..192ebefa812 Binary files /dev/null and b/docs/python/media/vs-2022/environments-toolbar-2022.png differ diff --git a/docs/python/media/vs-2022/projects-activate-environment-2022.png b/docs/python/media/vs-2022/projects-activate-environment-2022.png new file mode 100644 index 00000000000..97d8423cfee Binary files /dev/null and b/docs/python/media/vs-2022/projects-activate-environment-2022.png differ diff --git a/docs/python/unit-testing-python-in-visual-studio.md b/docs/python/unit-testing-python-in-visual-studio.md index 5874565d0f9..5723ff21607 100644 --- a/docs/python/unit-testing-python-in-visual-studio.md +++ b/docs/python/unit-testing-python-in-visual-studio.md @@ -1,7 +1,7 @@ --- title: Unit test Python code description: Setting up unit testing for Python code in Visual Studio takes full advantage of Test Explorer features to discover, run, and debug tests. -ms.date: 04/01/2022 +ms.date: 08/18/2023 ms.topic: how-to author: cwebster-99 ms.author: cowebster @@ -12,9 +12,10 @@ ms.workload: - python - data-science --- + # Set up unit testing for Python code - [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] +[!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)] Unit tests are pieces of code that test other code units in an application, typically isolated functions, classes, and so on. When an application passes all its unit tests, you can at least trust that its low-level functionality is correct. @@ -26,4 +27,4 @@ This article provides a brief outline of unit testing capabilities in Visual Stu [!include[Testing Python code](includes/vs-2019/unit-testing-python.md)] -::: moniker-end \ No newline at end of file +::: moniker-end