claude-home/reference/python/debugging.md

Python Debugging Reference

Common Error Patterns

ImportError / ModuleNotFoundError

# Check Python path
python -c "import sys; print('\n'.join(sys.path))"

# Check installed packages
pip list
pip show <package_name>

# Install missing packages
pip install -r requirements.txt
pip install <package_name>

Virtual Environment Issues

# Check current environment
which python
which pip

# Recreate virtual environment
rm -rf venv/
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows
pip install -r requirements.txt

Memory Issues

import tracemalloc
import psutil
import os

# Memory profiling
tracemalloc.start()
# ... your code ...
current, peak = tracemalloc.get_traced_memory()
print(f"Current memory usage: {current / 1024 / 1024:.1f} MB")
print(f"Peak memory usage: {peak / 1024 / 1024:.1f} MB")

# System memory
process = psutil.Process(os.getpid())
print(f"RSS memory: {process.memory_info().rss / 1024 / 1024:.1f} MB")

Debugging Tools

Using pdb debugger

import pdb

def problematic_function():
    x = 10
    pdb.set_trace()  # Execution will pause here
    y = x * 2
    return y

# Or use breakpoint() in Python 3.7+
def modern_debug():
    x = 10
    breakpoint()  # Same as pdb.set_trace()
    return x

Logging setup

import logging

# Configure logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('debug.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)

def example_function():
    logger.debug("Starting function")
    try:
        result = risky_operation()
        logger.info(f"Operation successful: {result}")
        return result
    except Exception as e:
        logger.error(f"Operation failed: {e}", exc_info=True)
        raise

Performance Debugging

Profile code execution

import cProfile
import pstats

# Profile a function
cProfile.run('your_function()', 'profile_output.prof')

# Analyze results
stats = pstats.Stats('profile_output.prof')
stats.sort_stats('cumulative').print_stats(10)

Line-by-line profiling

# Install line_profiler
pip install line_profiler

# Add @profile decorator to functions
# Run with:
kernprof -l -v your_script.py

Check for memory leaks

import gc
import objgraph

# Show most common types
objgraph.show_most_common_types()

# Track object growth
objgraph.show_growth()

Database Debugging

SQLAlchemy query debugging

import logging

# Enable SQL query logging
logging.basicConfig()
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
logging.getLogger('sqlalchemy.dialects').setLevel(logging.DEBUG)
logging.getLogger('sqlalchemy.pool').setLevel(logging.DEBUG)

Connection issues

# Test database connection
try:
    engine.connect()
    print("Database connection successful")
except Exception as e:
    print(f"Database connection failed: {e}")