Part 2: Breakpoints and Stepping Through Code

Introduction

In Part 1, you learned basic breakpoints—click the gutter, execution stops. But VS Code offers much more: conditional breakpoints that pause only when specific conditions are met, logpoints that output messages without stopping, and step controls that let you navigate code execution precisely.

When debugging a data processing pipeline that handled 10,000 records, I needed to pause only when a specific user ID appeared. A regular breakpoint would have stopped 10,000 times. A conditional breakpoint? Once. This article teaches you the breakpoint types and stepping techniques that make debugging efficient.

Breakpoint Types

Regular Breakpoints - What You Know

def process_payment(amount, user_id):
    balance = get_balance(user_id)  # ← Red dot = always pauses here
    if balance >= amount:
        deduct(user_id, amount)
        return True
    return False

Pauses every time the line executes.

Conditional Breakpoints - Game Changer

Only pause when a condition is true.

Expression Condition

def process_order(order):
    # Only pause for VIP customers
    customer = get_customer(order['customer_id'])  # ← Right-click → "Add Conditional Breakpoint"
    # Condition: customer['tier'] == 'VIP'
    
    total = calculate_total(order)
    apply_discount(customer, total)
    return total

Setting it up:

1. Right-click in gutter (or existing breakpoint)

2. Choose "Add Conditional Breakpoint" → "Expression"

3. Enter: customer['tier'] == 'VIP'

4. Breakpoint shows as red dot with condition icon

Now it only pauses for VIP customers!

Hit Count Condition

Pause after the line has been hit a certain number of times.

def process_batch(items):
    for item in items:  # ← Conditional breakpoint
        # Hit count: = 100
        process_item(item)

Use cases:

• = 50 - Pause on exactly the 50th iteration

• > 100 - Pause after 100 hits

• % 10 == 0 - Pause every 10th hit

Real scenario: I was debugging a loop that processed 1000 database records. The bug appeared around record 500. Instead of clicking "Continue" 500 times, I set hit count = 500 and execution paused right where the bug occurred.

Triggered Breakpoints

Pause when another breakpoint is hit first.

def handle_request(request):
    validate_auth(request)  # ← Breakpoint A
    
    data = parse_data(request)
    
    result = process_data(data)  # ← Breakpoint B (triggered by A)
    
    return result

Setup:

1. Set regular breakpoint at line 2 (Breakpoint A)

2. Right-click line 6 → "Add Triggered Breakpoint"

3. Select which breakpoint triggers it: "Breakpoint A"

Now Breakpoint B only activates after Breakpoint A is hit at least once.

Real scenario: Debugging authentication flow. I only wanted to debug process_data() when authentication succeeded (when it hit the auth breakpoint). Triggered breakpoints let Breakpoint B activate only after successful auth.

Logpoints - Debug Without Stopping

Output messages to Debug Console without pausing execution.

def update_inventory(product_id, quantity):
    # Logpoint: "Updating {product_id} by {quantity}"
    current = get_stock(product_id)
    new_stock = current + quantity
    # Logpoint: "New stock for {product_id}: {new_stock}"
    save_stock(product_id, new_stock)

Setting it up:

1. Right-click in gutter

2. Choose "Add Logpoint"

3. Enter: Updating {product_id} by {quantity}

Output in Debug Console:

Updating SKU-123 by 10
New stock for SKU-123: 45
Updating SKU-456 by -5
New stock for SKU-456: 12

Why use logpoints?

• No code changes needed (no print statements!)

• See output without stopping execution

• Perfect for loops and high-frequency functions

• No cleanup needed after debugging

Real example: I was debugging a webhook handler that received events continuously. Regular breakpoints would pause the server for every event. Logpoints let me see what was happening without disrupting service:

@app.post("/webhook")
def handle_webhook(event: WebhookEvent):
    # Logpoint: "Received event: {event.type} from {event.source}"
    
    if event.type == "payment.completed":
        # Logpoint: "Processing payment: {event.data['amount']}"
        process_payment(event.data)
    
    return {"status": "received"}

Debug Console showed every event without stopping the server.

Inline Breakpoints

Pause at specific expressions within a line—useful for complex one-liners or comprehensions.

# Complex line with multiple expressions
result = [process(item) for item in items if validate(item) and item.active]
#                                                              ↑ Inline breakpoint here

Set inline breakpoint:

1. During debug session

2. Shift+F9 or right-click → "Add Inline Breakpoint"

3. Choose the exact expression

Real scenario:

# Bug in list comprehension
users = [User(id=u['id'], name=u['name'], email=u.get('email', 'unknown'))
         for u in data if u.get('active', False)]
#                         ↑ Inline BP here - check what u.get('active') returns

Without inline breakpoints, I'd need to expand this into a loop to debug it.

Function Breakpoints

Pause when a function is called, even if you don't have the source code.

# Set breakpoint on function name "calculate_tax"
# Even in third-party libraries!

Setting it up:

1. Open Breakpoints panel

2. Click "+" → "Function Breakpoint"

3. Enter function name: calculate_tax

Real scenario: I was debugging an issue in third-party library code. I couldn't easily find the source file, but I knew the function name parse_jwt. Function breakpoint paused execution right when it was called.

Data Breakpoints (Python Limited Support)

Pause when a variable's value changes. Note: Python's debugger has limited support compared to languages like C++.

Stepping Through Code

Once paused at a breakpoint, step controls let you navigate execution precisely.

Step Over (F10)

Execute current line, don't enter function calls.

def checkout(cart, user):
    total = calculate_total(cart)  # ← Currently here, press F10
    # Next line: apply_discount (doesn't enter calculate_total)
    discount = apply_discount(user, total)
    return total - discount

Use when: You trust the function being called and want to see the result without entering it.

Step Into (F11)

Enter the function on the current line.

def checkout(cart, user):
    total = calculate_total(cart)  # ← Currently here, press F11
    
# Jumps into calculate_total():
def calculate_total(cart):  # ← Now here
    total = sum(item['price'] * item['qty'] for item in cart)
    return total

Use when: You need to see what's happening inside a function.

Step Out (Shift+F11)

Exit the current function and return to the caller.

def calculate_total(cart):
    total = sum(item['price'] * item['qty'] for item in cart)
    return total  # ← Press Shift+F11 to return to caller

def checkout(cart, user):
    total = calculate_total(cart)  # ← Back here
    discount = apply_discount(user, total)

Use when: You stepped into a function but realized you don't need to debug it further.

Continue (F5)

Resume execution until next breakpoint or program ends.

def process_all_orders():
    for order_id in range(1, 1000):
        order = get_order(order_id)
        if order['status'] == 'pending':  # ← Breakpoint here
            process_order(order)          # Press F5 to continue to next match

Use when: You've seen what you needed and want to reach the next breakpoint.

Restart (Shift+Cmd+F5)

Stop current debug session and restart from the beginning.

Use when: You modified code or need to debug from the start again.

Stop (Shift+F5)

End the debug session.

Real-World Example: Debugging an API Data Transformation

I built an API endpoint that transformed database records into API responses. The output was incorrect for certain records.

The Code

from typing import List, Dict
from fastapi import FastAPI

app = FastAPI()

def transform_user(user_data: Dict) -> Dict:
    """Transform database user record to API response"""
    return {
        "id": user_data["user_id"],
        "name": f"{user_data['first_name']} {user_data['last_name']}",
        "email": user_data.get("email", "").lower(),
        "status": "active" if user_data.get("is_active", 0) else "inactive",
        "created": user_data["created_at"].isoformat()
    }

@app.get("/users")
def get_users() -> List[Dict]:
    # Simulated DB query
    db_users = [
        {"user_id": 1, "first_name": "Alice", "last_name": "Smith", 
         "email": "[email protected]", "is_active": 1, "created_at": "2024-01-15"},
        {"user_id": 2, "first_name": "Bob", "last_name": "Jones", 
         "email": None, "is_active": 0, "created_at": "2024-02-20"},
        {"user_id": 3, "first_name": "Charlie", "last_name": None, 
         "email": "[email protected]", "is_active": 1, "created_at": "2024-03-10"}
    ]
    
    return [transform_user(user) for user in db_users]

Problem: API crashes for user_id 3 (Charlie) with AttributeError.

Debugging Strategy

Step 1: Conditional Breakpoint

Don't want to pause for all users, just user_id 3.

Breakpoint location: Line 7 (return {) Condition: user_data["user_id"] == 3

Step 2: Start Debugging

# Send request
curl http://localhost:8000/users

Execution pauses when processing user_id 3.

Step 3: Inspect Variables

>>> user_data
{'user_id': 3, 'first_name': 'Charlie', 'last_name': None, 
 'email': '[email protected]', 'is_active': 1, 'created_at': '2024-03-10'}

>>> user_data['last_name']
None

>>> f"{user_data['first_name']} {user_data['last_name']}"
'Charlie None'  # ← Bug! Shows "None" as string

Step 4: Test Fix in Debug Console

>>> last = user_data['last_name'] or ""
>>> f"{user_data['first_name']} {last}".strip()
'Charlie'  # ← Perfect!

Step 5: Update Code

def transform_user(user_data: Dict) -> Dict:
    first = user_data.get('first_name', '')
    last = user_data.get('last_name', '')
    
    return {
        "id": user_data["user_id"],
        "name": f"{first} {last}".strip(),  # ← Fixed
        "email": user_data.get("email", "").lower() if user_data.get("email") else "",
        "status": "active" if user_data.get("is_active", 0) else "inactive",
        "created": user_data["created_at"]
    }

Total debugging time: 2 minutes using conditional breakpoint + debug console.

Without debugger: Would have added prints, tested each user, removed prints, restarted server multiple times. 15-20 minutes easily.

Advanced Stepping Techniques

Smart Stepping

VS Code can skip stepping into certain code like libraries or getters/setters.

Configure in settings:

{
    "debugpy.debugStdLib": false  // Don't step into Python standard library
}

Run to Cursor

Right-click any line → "Run to Cursor" - Execution runs until it hits that line (like a temporary breakpoint).

def complex_function():
    step1()
    step2()
    step3()
    step4()  # ← Right-click → "Run to Cursor"
    step5()

Press F5, execution runs straight to step4() without stepping through everything above.

Jump to Cursor (Set Next Statement)

Caution: Advanced feature. Right-click → "Jump to Cursor" moves execution pointer without running code between.

def test_payment():
    validate_card()  # ← Currently here
    charge_card()
    send_receipt()   # ← Jump here (skips charge_card())

Use carefully: Only when you need to skip code or re-run code.

Debugging Loops Efficiently

Problem: Inspecting Loop Iterations

def process_batch(items):
    results = []
    for i, item in enumerate(items):  # ← Breakpoint here
        if item.needs_processing():
            result = process_item(item)
            results.append(result)
    return results

Strategies:

1. Conditional breakpoint: item.id == 'problem-id'

2. Hit count breakpoint: i == 50 (pause on 50th item)

3. Logpoint: Item {i}: {item.id} - {item.status}

Real Example: Finding Bad Data

def import_users(csv_data):
    for line_num, row in enumerate(csv_data, start=1):  # ← Breakpoint
        # Condition: not row.get('email')
        user = create_user(
            name=row['name'],
            email=row['email'],
            age=int(row['age'])
        )
        save_user(user)

Conditional breakpoint condition: not row.get('email')

Only pauses on rows missing email addresses, skipping thousands of valid rows.

Exception Breakpoints

Pause when exceptions are raised.

Enable in VS Code

1. Open Run and Debug view

2. Breakpoints panel → Check "Raised Exceptions"

Now execution pauses the moment an exception occurs, even if it's caught!

def parse_config(filename):
    try:
        with open(filename) as f:  # ← If FileNotFoundError, pauses HERE
            return json.load(f)    # ← Not here in the except block
    except FileNotFoundError:
        return {}

Incredibly useful for seeing exception state before it's caught.

Uncaught Exceptions Only

Check "Uncaught Exceptions" instead to only pause on exceptions that aren't caught.

Keyboard Shortcuts Mastery

Action	Shortcut	When to Use
Toggle Breakpoint	F9	Add/remove breakpoint on current line
Conditional Breakpoint	Right-click gutter	Only pause when condition met
Continue	F5	Resume to next breakpoint
Step Over	F10	Execute line, don't enter functions
Step Into	F11	Enter function calls
Step Out	⇧F11	Exit current function
Restart	⇧⌘F5	Restart debug session
Stop	⇧F5	End debugging
Run to Cursor	Right-click + select	Quick temporary breakpoint

Best Practices

1. Use Conditional Breakpoints for Loops

Instead of:

for item in items:  # ← Regular breakpoint (pauses 1000 times!)
    if item.id == target_id:  # Want to debug this specific item
        process(item)

Use:

for item in items:  # ← Conditional: item.id == target_id (pauses once!)
    process(item)

2. Logpoints for High-Frequency Code

Instead of:

@app.middleware("http")
async def log_requests(request, call_next):
    print(f"Request: {request.method} {request.url}")  # ← Prints to code
    response = await call_next(request)
    return response

Use:

@app.middleware("http")
async def log_requests(request, call_next):
    # Logpoint: "Request: {request.method} {request.url}"
    response = await call_next(request)
    return response

3. Step Over Trusted Functions

result = complex_calculation()  # ← Step Over (F10) if you trust this
validate_result(result)         # ← Step Into (F11) to see validation logic

Don't waste time stepping through functions you know work correctly.

4. Use Run to Cursor for Quick Navigation

When you know exactly where you want to pause, right-click → "Run to Cursor" is faster than setting a temporary breakpoint.

What's Next

You now know:

• Conditional, logpoint, triggered, inline, and function breakpoints

• Stepping controls: over, into, out, continue

• Debugging loops efficiently

• Exception breakpoints

In Part 3: Variables, Watch, and Data Inspection, you'll master inspecting complex data structures, using the watch panel, exploring call stacks, and leveraging the debug console REPL for advanced debugging.

---

Based on debugging thousands of functions in production Python applications, from simple scripts to complex async microservices.