Uncategorized

A comprehensive guide to profiling and optimizing Python packages for real-world performance. Learn how to measure, analyze, and improve your package’s startup time, import overhead, and runtime performance.

Why Profile Your Python Package?

Performance matters. Users notice when your CLI takes 3 seconds to start or when your library adds 500ms to import time. This guide covers practical techniques to identify and fix performance bottlenecks.

Measuring Import Time

Python’s import system can be surprisingly slow. Here’s how to measure it:

Using time.perf_counter()

import time

t0 = time.perf_counter()
import your_module
import_time = (time.perf_counter() - t0) * 1000
print(f'Import time: {import_time:.0f}ms')

Using Python’s -X importtime

python -X importtime -c "import your_module" 2>&1 | head -20

This shows cumulative and self time for each import, helping identify slow dependencies.

Using cProfile for Function-Level Analysis

cProfile is Python’s built-in profiler. Use it to find hot functions:

import cProfile
import pstats

profiler = cProfile.Profile()
profiler.enable()

# Your code here
result = your_function()

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(20)  # Top 20 functions

Key Metrics

• cumulative: Total time in function including subcalls
• tottime: Time in function excluding subcalls
• calls: Number of times function was called

Separating Network from Compute

For packages that make API calls, separate network latency from local computation:

import time
import json

t0 = time.perf_counter()
# Import phase
import openai
t_import = time.perf_counter()

# Init phase
client = openai.OpenAI()
t_init = time.perf_counter()

# Network phase
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}]
)
t_network = time.perf_counter()

print(f'Import:  {(t_import - t0) * 1000:.0f}ms')
print(f'Init:    {(t_init - t_import) * 1000:.0f}ms')
print(f'Network: {(t_network - t_init) * 1000:.0f}ms')
print(f'Total:   {(t_network - t0) * 1000:.0f}ms')

Cold vs Warm Runs

Always measure both cold (first run) and warm (subsequent) performance:

import subprocess
import statistics

def measure_cold_start(command, runs=3):
    times = []
    for _ in range(runs):
        t0 = time.perf_counter()
        subprocess.run(command, capture_output=True)
        times.append((time.perf_counter() - t0) * 1000)
    return statistics.mean(times), statistics.stdev(times)

avg, std = measure_cold_start(['python', '-c', 'import your_module'])
print(f'Cold start: {avg:.0f}ms (±{std:.0f}ms)')

Identifying Eager Imports

Eager imports at module level are the #1 cause of slow startup. Look for:

# BAD: Eager import at module level
from heavy_dependency import HeavyClass

# GOOD: Lazy import when needed
def get_heavy_class():
    from heavy_dependency import HeavyClass
    return HeavyClass

Using importlib.util.find_spec

Check if a module is available without importing it:

import importlib.util

# Fast availability check (no import)
HEAVY_AVAILABLE = importlib.util.find_spec("heavy_module") is not None

# Lazy import helper
def _get_heavy_module():
    if HEAVY_AVAILABLE:
        import heavy_module
        return heavy_module
    return None

Lazy Loading with __getattr__

Python 3.7+ supports module-level __getattr__ for lazy loading:

# In your_package/__init__.py
_lazy_cache = {}

def __getattr__(name):
    if name in _lazy_cache:
        return _lazy_cache[name]
    
    if name == "HeavyClass":
        from .heavy_module import HeavyClass
        _lazy_cache[name] = HeavyClass
        return HeavyClass
    
    raise AttributeError(f"module has no attribute {name}")

Creating Timeline Diagrams

Visualize execution phases with ASCII timeline diagrams:

def create_timeline(phases):
    """
    phases: list of (name, duration_ms) tuples
    """
    total = sum(d for _, d in phases)
    scale = 50.0 / total
    
    # Top line
    line = "ENTER "
    for name, ms in phases:
        width = max(8, int(ms * scale))
        line += "─" * width
    line += "► END"
    print(line)
    
    # Phase names
    line = "      "
    for name, ms in phases:
        width = max(8, int(ms * scale))
        line += "│" + name.center(width - 1)
    line += "│"
    print(line)
    
    print(f"{'':>50} TOTAL: {total:.0f}ms")

Comparing SDK vs Wrapper Performance

When building wrappers around SDKs, measure the overhead:

# Baseline: Raw SDK
sdk_time = measure_sdk_call()

# Your wrapper
wrapper_time = measure_wrapper_call()

overhead = wrapper_time - sdk_time
print(f'Wrapper overhead: {overhead:.0f}ms ({overhead/sdk_time*100:.1f}%)')

Target: Keep wrapper overhead under 5% of SDK time.

CLI vs Python API Performance

CLI tools have additional overhead from subprocess spawning:

# Python API (faster)
from your_package import YourClass
result = YourClass().run()

# CLI (slower due to subprocess)
subprocess.run(['your-cli', 'command'])

Typical CLI overhead: 100-300ms for subprocess spawn + Python startup.

Caching Strategies

Module-Level Caching

class MyClass:
    _cached_client = None
    
    @classmethod
    def get_client(cls):
        if cls._cached_client is None:
            cls._cached_client = ExpensiveClient()
        return cls._cached_client

Configuration Caching

_config_applied = False

def apply_config():
    global _config_applied
    if _config_applied:
        return
    # Expensive configuration
    _config_applied = True

Profiling Pitfalls

1. Measuring in Development Mode

Debug mode, assertions, and development dependencies add overhead. Profile in production-like conditions.

2. Ignoring Variance

Always run multiple iterations and report standard deviation:

times = [measure() for _ in range(10)]
print(f'{statistics.mean(times):.0f}ms (±{statistics.stdev(times):.0f}ms)')

3. Profiler Overhead

cProfile adds ~10-20% overhead. For accurate timing, use time.perf_counter() for wall-clock measurements.

4. Network Variance

API calls have high variance. Separate network timing from local computation.

Performance Targets

Reasonable targets for Python packages:

Metric	Target
CLI –help	< 500ms
Package import	< 100ms
Wrapper overhead vs SDK	< 5%
Profiling overhead	< 5%

Summary

Key techniques for Python package performance:

1. Measure first: Use time.perf_counter() and cProfile
2. Separate phases: Import, init, network, execution
3. Lazy load: Use __getattr__ and importlib.util.find_spec
4. Cache wisely: Module-level caching for expensive operations
5. Multiple runs: Report mean and standard deviation
6. Timeline diagrams: Visualize where time is spent

Performance optimization is iterative. Measure, identify bottlenecks, fix, and measure again.