Venv Aware Python — VS Code Extension

A VS Code extension with a bundled Python indexer that provides version‑accurate code completions and diagnostics based on your currently active Python virtual environment (venv). No additional setup required!

🎉 New in v0.2.0: Bundled Edition

Zero setup complexity - The extension now includes a complete bundled indexer:

• ✅ No external dependencies - Everything included in the extension
• ✅ No manual installation - Just install the extension and use it
• ✅ Enhanced stability - Crash protection and subprocess isolation
• ✅ Fixed issues - Resolved introspection and memory management problems

Features

🎯 Version-Accurate Completions

• Only suggests symbols that exist in your installed package versions
• Automatically adapts to different virtual environments
• Prioritizes symbols from your actual installed packages

⚠️ Smart Diagnostics

• Warns when you use symbols not available in your current environment
• Suggests similar symbols when you make typos
• Provides quick fixes for common issues

🔄 Automatic Environment Detection

• Integrates with the official Python extension when present
• Works without a hard dependency by using configured/system Python
• Automatically detects interpreter changes and can rebuild the index

🚀 Fast Symbol Indexing

• Safe AST-based parsing with subprocess isolation
• Enhanced introspection with memory protection
• Incremental caching for faster rebuilds

Installation (dev)

1. Install the Python indexer locally (optional when using published extension):

cd ../indexer
pip install -e .

2. Build the extension:

npm install
npm run compile

3. Launch Extension Development Host:

• Press F5 in VS Code or “Debug: Start Debugging”

Usage

Initial Setup

1. Open a Python project with a virtual environment
2. The extension will automatically detect your Python interpreter
3. Choose "Build Index" when prompted to create the symbol index
4. Start coding with version-accurate completions!

Commands

Access these commands via Command Palette (Ctrl+Shift+P):

• Venv Aware: Rebuild Index - Manually rebuild the symbol index
• Venv Aware: Show Installed Package Symbols - Browse available symbols
• Venv Aware: Show Index Statistics - View index information
• Venv Aware: Switch Interpreter... - Change Python interpreter

Configuration

Configure the extension in VS Code settings:

{
  "venvAware.indexOnActivate": true,
  "venvAware.hideUnknownSymbols": false,
  "venvAware.maxDocLength": 200,
  "venvAware.enableDiagnostics": true,
  "venvAware.indexingMethod": "both",
  "venvAware.logLevel": "info"
}

Settings Reference

How It Works

Environment Detection

The extension prefers the official Python extension to detect:

• Current Python interpreter path
• Virtual environment activation/changes

If the Python extension is not present, it falls back to:

• python.defaultInterpreterPath / python.interpreterPath
• Probing system python3/python

Symbol Indexing

When you switch environments or rebuild the index:

1. Package Discovery: Scans site-packages directories
2. Symbol Extraction: Uses safe AST parsing and optional isolated introspection
3. Index Creation: Generates .venv-index/venv_symbols.index.json at the workspace root
4. File Watching: Monitors the index file and reloads on change

Completion Enhancement

The extension enhances VS Code's built-in Python completions by:

• Filtering symbols based on your installed versions
• Prioritizing symbols from your environment
• Adding detailed documentation from your packages

Diagnostics

Real-time analysis provides:

• Warnings for unavailable symbols
• Suggestions for similar symbols
• Quick fixes for common mistakes

Example Scenarios

Scenario 1: Version-Specific APIs

import numpy as np

# With numpy 1.21.0 installed:
np.typing.NDArray  # ✅ Available, shows completion

# With numpy 1.20.0 installed:
np.typing.NDArray  # ❌ Warning: not available in this version

Scenario 2: Environment Switching

1. Environment A (pandas 1.5.0):

   df.to_markdown()  # ✅ Available
   

2. Switch to Environment B (pandas 1.3.0):

   df.to_markdown()  # ❌ Warning: requires pandas >= 1.4.0
   

Scenario 3: Typo Detection

import requests

response = requests.gest('https://api.example.com')  # Typo
# 💡 Quick fix: Did you mean 'get'?

Development

Project Structure

src/
├── extension.ts          # Main extension entry point
├── activation/
│   └── pyEnv.ts         # Python environment detection
├── index/
│   ├── loader.ts        # Index loading and management
│   └── schema.ts        # Type definitions
├── features/
│   ├── completions.ts   # Completion provider
│   ├── diagnostics.ts   # Diagnostic provider
│   └── commands.ts      # Extension commands
└── utils/
    └── log.ts           # Logging utilities

Building

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

# Run tests
npm test

# Package extension
npm run package

Testing

1. Launch Extension Development Host (F5)
2. Open a Python project
3. Test completions and diagnostics
4. Check output logs for debugging

Debugging

Enable debug logging in settings:

{
  "venvAware.logLevel": "debug"
}

View logs in VS Code Output panel: "Venv Aware Python"

Troubleshooting

Index Not Building

1. Check that venv-indexer is installed:

   venv-indexer --help
   

2. Verify Python interpreter is detected:

   • Run "Venv Aware: Show Index Statistics"
   • Check the interpreter path

3. Check extension logs for errors

Completions Not Working

1. Ensure index is built and loaded
2. Check that you're in a Python file (.py)
3. Verify the symbol exists in your environment:

   venv-indexer show package_name
   

Performance Issues

1. Use AST-only indexing for faster builds:

   {
     "venvAware.indexingMethod": "ast-only"
   }
   

2. Clear the package cache:

   venv-indexer clear
   

Requirements

• VS Code 1.74.0 or higher
• Python 3.8 or higher
• Official Python extension (ms-python.python)
• VenvIndexer package installed

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE for details.