TPI: API Switch

[eleanorjboyd]

Refs: #835

• macOS @ulugbekna
• linux @rzhao271
• windows @benvillalobos

Complexity: 5

Author: @eleanorjboyd

Create Issue

Create Issue

---

Overview

This testing guide is for validating the migration from the legacy Python extension API to the new Python Environments extension API. This change affects how the Python Debugger extension resolves Python interpreters and executables for debugging sessions.

Sorry this TPI is long, I thought it would be helpful to be explicit about how to create and test things but if you are confident using python and python debugging then feel free to explore on your own to cover more edge cases I haven't thought of.

Prerequisites

Extension Versions

Before starting, ensure you have the latest versions of these extensions installed Python, Python Environments, Python Debugger

Test Setup

Step 1: Create a Test Project Structure

Create a new workspace with the following structure:

python-debug-test/
├── .venv/                        # Virtual environment for root project
├── root_script.py
└── subfolder_project/
    ├── .venv/                    # Virtual environment for subfolder project
    └── subfolder_script.py

Step 2: Create Python Environments

You can use any environment manager (conda, venv, uv, pyenv). Below are examples for the most common tools:

1. Create environment for root (from python-debug-test directory)
2. Create environment for subfolder_project

Step 3: Create Test Scripts

Create simple Python scripts that print the executable path:

root_script.py (at the root of python-debug-test):

import sys

print("=" * 60)
print("ROOT PROJECT SCRIPT")
print(f"Python Executable: {sys.executable}")
print("=" * 60)

subfolder_project/subfolder_script.py:

import sys

print("=" * 60)
print("SUBFOLDER PROJECT SCRIPT")
print(f"Python Executable: {sys.executable}")
print("=" * 60)

Step 4: Configure Python Environments in VS Code

1. Open the Python Environments view:

   • Click on the Python icon in the Activity Bar (left sidebar)

2. Set up multi-root workspace (if not automatic):

   • For each folder, right click on the explorer and in the submenu select "Add as Python Project" (root should already be shown)
   • This ensures VS Code treats each folder as a separate Python project

3. Select environments for each project:

   • Open root_script.py
   • Look at the status bar (bottom right) for the Python version
   • Click it and select the root .venv environment
   • Open subfolder_project/subfolder_script.py
   • Click the Python version in status bar
   • Select the subfolder_project's .venv environment

4. Verify environment selection:

   • In the Python Environments view, you should see both environments listed
   • Each script should show its associated environment when opened

---

Testing Scenarios

Test Section 1: Basic Debugging with New API (Default Behavior)

Ensure python.useEnvironmentsExtension is NOT set to false (it should use the new API by default).

Test 1.1: Debug with "Run and Debug" Button

1. Open root_script.py

2. Click the "Run and Debug" button in the left sidebar

3. Select "Python File" when prompted

4. Verify:

   • The debug session starts successfully
   • The output shows the correct executable path for the root .venv
   • The breakpoint is hit
   • Variables show correct values in the Debug view

5. Stop the debugger

6. Open subfolder_project/subfolder_script.py

7. Click "Run and Debug" again

8. Select "Python File"

9. Verify:

   • The debug session uses the subfolder_project/.venv executable
   • The output reflects the different environment

Test Section 2: launch.json Configuration Testing

Test 2.1: Create Basic launch.json

1. Click "Run and Debug" → "create a launch.json file"
2. Select "Python" → "Python File"
3. This creates .vscode/launch.json in your workspace

Basic configuration to test:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

4. Open root_script.py
5. Press F5 or use the Run and Debug view
6. Verify:
   • Uses the correct environment for the root project
7. Open subfolder_project/subfolder_script.py
8. Press F5
9. Verify:
   • Uses the correct environment for subfolder_project

Test 2.2: Test with ${workspaceFolder} Variable

Add this configuration to launch.json:

{
    "name": "Python: Root Project (workspaceFolder)",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/root_script.py",
    "console": "integratedTerminal",
    "cwd": "${workspaceFolder}"
}

1. Select this configuration from the debug dropdown
2. Press F5
3. Verify:
   • Correct environment is used for the root project
   • Working directory is set correctly

Test 2.3: Test with Explicit Python Path

Add this configuration to launch.json:

{
    "name": "Python: Explicit Python Path",
    "type": "debugpy",
    "request": "launch",
    "program": "${file}",
    "python": "${workspaceFolder}/.venv/bin/python",
    "console": "integratedTerminal"
}

1. Open subfolder_project/subfolder_script.py
2. Select "Python: Explicit Python Path" configuration
3. Press F5
4. Verify:
   • Even though you're debugging the subfolder script, it uses the root's Python
   • Output shows the root's executable path
   • This tests the explicit python path override

Test 2.4: Test Environment Variables and .env Files

1. Create .env file in the root of python-debug-test/:

   MY_CUSTOM_VAR=HelloFromRoot
   DEBUG_MODE=true
   

1.5. Add python.useEnvFile: true to your settings

2. Update root_script.py:

   import sys
   import os
   
   print("=" * 60)
   print("ROOT PROJECT SCRIPT")
   print("=" * 60)
   print(f"Python Executable: {sys.executable}")
   print(f"MY_CUSTOM_VAR: {os.getenv('MY_CUSTOM_VAR', 'NOT SET')}")
   print(f"DEBUG_MODE: {os.getenv('DEBUG_MODE', 'NOT SET')}")
   print("=" * 60)

3. Debug the script

4. Verify:

   • Custom environment variables are loaded correctly
   • Output shows the values from .env

Test 2.5: Notebooks

1. Create a notebook, debug a cell in that notebook, make sure the executable is as expected (feel free to use code from the script earlier in your notebook)

Test Section 3: Legacy API Testing (Backward Compatibility)

Now test with the legacy Python extension API to ensure backward compatibility.

Step 1: Enable Legacy API Mode

1. Open VS Code Settings (Cmd+, on macOS)

2. Search for python.useEnvironmentsExtension

3. Uncheck the box (set to false)

   • Or add to settings.json: "python.useEnvironmentsExtension": false

4. Reload VS Code window to ensure the setting takes effect

   • Command Palette → "Developer: Reload Window"

Step 2: Test Basic Debugging

1. Open root_script.py

2. Press F5 or use "Run and Debug"

3. Verify:

   • Debugging still works
   • IMPORTANT: In legacy mode, only ONE environment (typically the workspace/root-level environment) is used
   • The output should show the root's Python executable

4. Open subfolder_project/subfolder_script.py

5. Press F5

6. Verify:

   • The script runs but uses the same root-level Python environment
   • Output shows the root project's executable (NOT the subfolder's .venv)
   • This is expected behavior in legacy mode - it doesn't support per-folder environments as well

Step 3: Test launch.json in Legacy Mode

1. Use the same launch.json configurations from Test Group 2
2. Run each configuration
3. Verify:
   • Explicit python paths still work
   • ${workspaceFolder} variables work
   • Basic debugging functionality is preserved

[ulugbekna]

thank you for very detailed TPI!

The description mentioned python.useEnvFile setting but it's unknown in vscode. Did you mean python.terminal.useEnvFile?

[eleanorjboyd]

oops yes, that is the correct one!

[benvillalobos]

converted original comment to issues

#860
#861