Python Live Evaluator

A VSCode extension that provides live evaluation for Python with advanced features including explicit evaluation mode, syntax validation, rate limiting for APIs, and free-threaded Python support.

✨ Features

🚀 Live Evaluation - See Python code results as you type, inline with your code
🎯 Explicit Mode - Control exactly where results appear with comment markers
✅ Syntax Validation - Visual gutter indicators show code validity before evaluation
⏱️ Rate Limiting - Protect API quotas with configurable evaluation delays
🧵 Free-threaded Python Support - Full support for Python 3.13+ no-GIL builds
🔍 Smart Block Detection - Correctly handles functions, classes, loops, and indentation
📊 Rich Output Display - Shows variables, expressions, print outputs, and errors inline
🎨 Customizable Markers - Define your own comment markers for explicit mode
🐛 Debug Mode - Detailed logging for troubleshooting

📦 Installation

Prerequisites

VSCode 1.74.0 or higher
Python 3.6 or higher
Microsoft Python extension (ms-python.python)

Install from VSIX

code --install-extension python-live-evaluator-*.vsix

Build from Source

git clone <repository>
cd python-live-evaluator
npm install
# Press F5 in VSCode to run

🚀 Quick Start

Open any Python file - The extension activates automatically
Start typing - See results appear inline as you code
Watch the gutter - Colored dots show code validation status
Use markers in explicit mode - Add # ? to any line to see its result

Basic Example

x = 10          # x: 10
y = 20          # x: 10, y: 20
z = x + y       # x: 10, y: 20, z: 30
z               # → 30
print("Hello")  # ▶ Hello

⚙️ Configuration Settings

All settings are prefixed with pythonLiveEvaluator. in your VSCode settings.

Core Settings

Setting	Type	Default	Description
`evaluationMode`	`"auto" \\| "explicit"`	`"explicit"`	Evaluation display mode • `auto`: Show results on all lines • `explicit`: Only show on marked lines
`evaluationMarkers`	`string[]`	`["# ?", "# /"]`	Comment markers that trigger display in explicit mode
`syntaxValidation`	`boolean`	`true`	Enable syntax validation with gutter indicators (prevents indent errors)
`autoStart`	`boolean`	`true`	Automatically start evaluation when opening Python files
`debug`	`boolean`	`false`	Enable detailed debug output in the Output panel

Performance Settings

Setting	Type	Default	Range	Description
`debounceDelay`	`number`	`300`	0-5000	Milliseconds to wait after typing stops before evaluating
`evaluationDelay`	`number`	`0`	0-10000	Milliseconds to wait between evaluating each code block (for rate-limited APIs)
`showWaitingIndicator`	`boolean`	`true`	-	Show "⏳ waiting..." when evaluation delay ≥ 1000ms

Display Settings

Setting	Type	Default	Range	Description
`maxOutputLength`	`number`	`200`	50-1000	Maximum characters for inline output display
`showThreadingMetrics`	`boolean`	`true`	-	Show special decorations for threading/performance metrics

✅ Syntax Validation

The extension provides real-time syntax validation to prevent evaluation errors while typing.

Gutter Indicators

Indicator	Meaning	Description
🟢	Valid	Code is syntactically correct and has been evaluated
🔴	Invalid	Syntax error detected - see inline error message
🟠	Incomplete	Incomplete block (e.g., `for` loop without body)

How It Works

When enabled (default), the extension:

Validates syntax before evaluation using Python's AST parser
Shows gutter dots indicating block status
Only evaluates valid, complete blocks
Prevents indentation errors while typing

Configuration

{
  "pythonLiveEvaluator.syntaxValidation": true // or false to disable
}

When disabled, all blocks are evaluated immediately (may cause errors while typing).

Example

# While typing:
for i in range(5):    # 🟠 Shows: ⏳ waiting for block completion...

# After completing:
for i in range(5):    # 🟢
    print(i)  # ?     # Shows: ▶ 0, 1, 2, 3, 4

🎯 Evaluation Modes

Auto Mode

Shows results on all lines automatically:

{
  "pythonLiveEvaluator.evaluationMode": "auto"
}

x = 10      # // x: 10
y = 20      # // x: 10, y: 20
z = x + y   # // x: 10, y: 20, z: 30

Explicit Mode (Default)

Only shows results on lines with markers:

{
  "pythonLiveEvaluator.evaluationMode": "explicit",
  "pythonLiveEvaluator.evaluationMarkers": ["# ?", "# /"]
}

x = 10      # No output
y = 20      # No output
z = x + y   # ?  Shows: // z: 30
print(z)    # /  Shows: ▶ 30

🔧 Custom Evaluation Markers

Create your own marker convention:

{
  "pythonLiveEvaluator.evaluationMarkers": [
    "# check",
    "# show",
    "# debug",
    "# !"
  ]
}

result = calculate()  # check
api_response = fetch()  # debug
final_value = process()  # show

⏱️ Rate Limiting for APIs

Protect your API quotas with evaluation delays:

{
  "pythonLiveEvaluator.evaluationDelay": 1000, // 1 second between blocks
  "pythonLiveEvaluator.showWaitingIndicator": true
}

Recommended Delays by Service

API Service	Recommended Delay	Notes
OpenAI GPT	1000-2000ms	Varies by tier
Anthropic Claude	500-1000ms	Moderate limits
Google Cloud	100-500ms	Higher limits
Twitter/X API	3000-5000ms	Very strict
Local/Database	0-100ms	Prevent exhaustion

🧵 Free-threaded Python Support

The extension automatically detects and supports Python 3.13+ free-threaded (no-GIL) builds:

Check GIL Status

Command: Python Live: Show GIL Status

Threading Demo

Command: Python Live: Insert Threading Demo

Visual Indicators

🟢 Green: Threading information
🟠 Orange: Performance metrics
🚀 Status bar: Shows "Free-threaded mode" when detected

📝 Commands

Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description	Keyboard Shortcut
`Python Live: Start Evaluation`	Start live evaluation	`Ctrl+Shift+P Ctrl+Shift+S`
`Python Live: Stop Evaluation`	Stop live evaluation	`Ctrl+Shift+P Ctrl+Shift+X`
`Python Live: Clear Results`	Clear all inline decorations	-
`Python Live: Show GIL Status`	Check if using free-threaded Python	`Ctrl+Shift+P Ctrl+Shift+G`
`Python Live: Insert Threading Demo`	Insert example threading code	-

🎨 Visual Indicators

Inline Decorations

Indicator	Meaning	Example
`// var: value`	Variable values	`// x: 10, y: 20`
`→ result`	Expression result	`→ 30`
`▶ output`	Print output	`▶ Hello World`
`⚠ error`	Error message	`⚠ NameError: undefined`
`🧵 threads`	Threading info	`🧵 Active threads: 5`
`⚡ metric`	Performance metric	`⚡ Time: 0.5s`
`⏳ waiting`	Evaluation delay	`⏳ waiting 1000ms...`

Gutter Indicators (Syntax Validation)

Dot	Status	Description
🟢	Valid	Code block is syntactically correct
🔴	Invalid	Syntax error in block
🟠	Incomplete	Block needs completion (e.g., loop without body)

🐛 Debug Mode

Enable detailed logging for troubleshooting:

{
  "pythonLiveEvaluator.debug": true
}

View output: View → Output → Select "Python Live Evaluator"

Debug output shows:

Evaluation mode and settings
Syntax validation results
Marked line detection (explicit mode)
Block parsing details
Decoration decisions
Timing information
Error details

💡 Usage Examples

Example 1: API Development with Rate Limiting

{
  "pythonLiveEvaluator.evaluationMode": "explicit",
  "pythonLiveEvaluator.evaluationDelay": 1000,
  "pythonLiveEvaluator.syntaxValidation": true
}

import openai

# Setup - no decoration
client = openai.Client(api_key="...")

# Only check specific calls
response = client.chat.completions.create(...)  # ?
print(response.choices[0].message)  # ?

Example 2: Teaching with Explicit Markers

# Students work through the code
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

# Check understanding at key points
factorial(5)  # ?  → 120
factorial(10)  # ?  → 3628800

Example 3: Data Science Exploration

{
  "pythonLiveEvaluator.evaluationMode": "auto",
  "pythonLiveEvaluator.syntaxValidation": true
}

import pandas as pd
df = pd.read_csv('data.csv')  # // df: <DataFrame>
df.shape  # → (1000, 5)
df.columns.tolist()  # → ['id', 'name', 'value', ...]
df.describe()  # → <statistics>

🔍 Troubleshooting

No decorations appearing

Check evaluation mode in settings
In explicit mode, ensure you have markers (# ?)
Check Output panel for errors
Verify Python interpreter is selected
Check gutter indicators - red dots indicate syntax errors

Decorations on wrong lines

Enable debug mode to see block parsing
Check indentation is consistent
Ensure markers are properly formatted
Look for orange gutter dots (incomplete blocks)

Indentation errors while typing

Ensure syntaxValidation is enabled (default)
Wait for orange dot to turn green before expecting results
Complete code blocks before evaluation occurs

Performance issues

Increase debounceDelay (try 1000ms)
Add evaluationDelay for API calls
Use explicit mode to reduce decorations
Check for infinite loops in code
Consider disabling syntaxValidation if validation is slow

API rate limits

Increase evaluationDelay (start with 2000ms)
Use explicit mode to evaluate less frequently
Watch for rate limit warnings in output

🏗️ Project Structure

python-live-evaluator/
├── extension.js        # Main extension code
├── package.json        # Extension manifest
├── README.md          # This file
├── CHANGELOG.md       # Version history
├── LICENSE            # MIT License
└── .vscode/
    └── launch.json    # Debug configuration

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - See LICENSE file for details

📧 Support

Issues: GitHub Issues

🌟 Tips

Start with explicit mode for cleaner display
Keep syntax validation enabled to avoid errors while typing
Use rate limiting when working with APIs
Enable debug mode when troubleshooting
Customize markers to match your workflow
Check GIL status for threading performance
Watch the gutter dots for immediate syntax feedback

Enjoy live Python evaluation! 🐍✨

Python Live Evaluator

Venture Casserole

Python Live Evaluator

✨ Features

📦 Installation

Prerequisites

Install from VSIX

Build from Source

🚀 Quick Start

Basic Example

⚙️ Configuration Settings

Core Settings

Performance Settings

Display Settings

✅ Syntax Validation

Gutter Indicators

How It Works

Configuration

Example

🎯 Evaluation Modes

Auto Mode

Explicit Mode (Default)

🔧 Custom Evaluation Markers

⏱️ Rate Limiting for APIs

Recommended Delays by Service

🧵 Free-threaded Python Support

Check GIL Status

Threading Demo

Visual Indicators

📝 Commands

🎨 Visual Indicators

Inline Decorations

Gutter Indicators (Syntax Validation)

🐛 Debug Mode

💡 Usage Examples

Example 1: API Development with Rate Limiting

Example 2: Teaching with Explicit Markers

Example 3: Data Science Exploration

🔍 Troubleshooting

No decorations appearing

Decorations on wrong lines

Indentation errors while typing

Performance issues

API rate limits

🏗️ Project Structure

🤝 Contributing

📄 License

📧 Support

🌟 Tips