tessl/pypi-pyinstrument

Call stack profiler for Python that shows you why your code is slow

—

Pending

Overview

Eval results

Files

Output Rendering

Name: tessl/pypi-pyinstrument
Author: tessl

Multiple output formats for displaying profiling results with various renderers supporting different use cases from interactive HTML visualizations to console text output and integration formats for external tools.

Capabilities

Console Renderer

Text-based console output with support for Unicode, colors, different view modes, and customizable formatting options.

class ConsoleRenderer:
    """
    Renders profiling results as formatted console text.
    """
    
    def __init__(
        self,
        unicode: bool = False,
        color: bool = False,
        show_all: bool = False,
        timeline: bool = False,
        time: Literal["seconds", "percent_of_total"] = "seconds",
        flat: bool = False,
        flat_time: FlatTimeMode = "self",
        short_mode: bool = False,
        processor_options: dict[str, Any] | None = None
    ):
        """
        Initialize console renderer with display options.
        
        Args:
            unicode: Use Unicode box-drawing characters
            color: Use ANSI color codes for highlighting
            show_all: Show all frames including library code
            timeline: Show chronological timeline view
            time: Display format - "seconds" or "percent_of_total"
            flat: Show flat profile instead of call tree
            flat_time: For flat mode - "self" or "cumulative" time
            short_mode: Use compact output format
            processor_options: Frame processing configuration
        """
    
    def render(self, session: Session) -> str:
        """
        Render session data as formatted console text.
        
        Args:
            session: Profiling session to render
            
        Returns:
            Formatted text representation of profiling data
        """

HTML Renderer

Interactive HTML output with timeline visualization, expandable call trees, and browser-based interface for exploring profiling results.

class HTMLRenderer:
    """
    Renders profiling results as interactive HTML with timeline view.
    """
    
    def __init__(
        self,
        timeline: bool = False,
        show_all: bool = False
    ):
        """
        Initialize HTML renderer.
        
        Args:
            timeline: Include interactive timeline visualization
            show_all: Show all frames including library code
        """
    
    def render(self, session: Session) -> str:
        """
        Render session data as interactive HTML.
        
        Args:
            session: Profiling session to render
            
        Returns:
            Complete HTML document with embedded JavaScript
        """
    
    def open_in_browser(self, session: Session) -> None:
        """
        Render session and open results in web browser.
        
        Args:
            session: Profiling session to display
        """

JSON Renderer

Structured JSON output for programmatic analysis and integration with external tools.

class JSONRenderer:
    """
    Renders profiling results as structured JSON data.
    """
    
    def render(self, session: Session) -> str:
        """
        Render session data as JSON.
        
        Args:
            session: Profiling session to render
            
        Returns:
            JSON string containing structured profiling data
        """

Speedscope Renderer

Output format compatible with speedscope.app for advanced timeline visualization and flame graph analysis.

class SpeedscopeRenderer:
    """
    Renders profiling results in speedscope.app compatible format.
    """
    
    def render(self, session: Session) -> str:
        """
        Render session data in speedscope format.
        
        Args:
            session: Profiling session to render
            
        Returns:
            JSON string compatible with speedscope.app
        """

Pstats Renderer

Python cProfile/pstats compatible output for integration with existing Python profiling tools.

class PstatsRenderer:
    """
    Renders profiling results in Python pstats compatible format.
    """
    
    def render(self, session: Session) -> str:
        """
        Render session data in pstats format.
        
        Args:
            session: Profiling session to render
            
        Returns:
            pstats compatible data representation
        """

Session Renderer

Internal renderer for session data serialization, typically used for saving session state.

class SessionRenderer:
    """
    Renders profiling results as session data for storage and loading.
    """
    
    def __init__(self, tree_format: bool = False):
        """
        Initialize session renderer.
        
        Args:
            tree_format: Whether to use tree format for output
        """
    
    def render(self, session: Session) -> str:
        """
        Render session data as JSON.
        
        Args:
            session: Profiling session to render
            
        Returns:
            JSON string of session data
        """

Base Renderer Classes

Abstract base classes for implementing custom renderers.

class Renderer:
    """Base class for all renderers."""
    
    def render(self, session: Session) -> str:
        """
        Render session data to string output.
        
        Args:
            session: Profiling session to render
            
        Returns:
            Rendered output as string
        """

class FrameRenderer(Renderer):
    """Base class for frame-based renderers with tree processing."""

Usage Examples

Console Output with Options

from pyinstrument import Profiler
from pyinstrument.renderers import ConsoleRenderer

with Profiler() as profiler:
    do_work()

# Custom console rendering
renderer = ConsoleRenderer(
    color=True,
    unicode=True,
    show_all=True,
    timeline=False
)
output = renderer.render(profiler.last_session)
print(output)

HTML Output for Web Viewing

from pyinstrument import Profiler
from pyinstrument.renderers import HTMLRenderer

with Profiler() as profiler:
    process_data()

# Generate HTML with timeline
html_renderer = HTMLRenderer(timeline=True, show_all=False)
html_content = html_renderer.render(profiler.last_session)

# Save to file
with open('profile.html', 'w') as f:
    f.write(html_content)

# Or open directly in browser
html_renderer.open_in_browser(profiler.last_session)

JSON Export for Analysis

from pyinstrument import Profiler
from pyinstrument.renderers import JSONRenderer
import json

with Profiler() as profiler:
    analyze_data()

# Export as JSON
json_renderer = JSONRenderer()
json_output = json_renderer.render(profiler.last_session)
data = json.loads(json_output)

# Save for external analysis
with open('profile.json', 'w') as f:
    json.dump(data, f, indent=2)

Speedscope Integration

from pyinstrument import Profiler
from pyinstrument.renderers import SpeedscopeRenderer

with Profiler() as profiler:
    complex_computation()

# Generate speedscope format
speedscope_renderer = SpeedscopeRenderer()
speedscope_data = speedscope_renderer.render(profiler.last_session)

# Save for speedscope.app
with open('profile.speedscope.json', 'w') as f:
    f.write(speedscope_data)

Types

FlatTimeMode = Literal["self", "cumulative"]

class ProcessorOptions:
    """Configuration options for frame processing."""
    filter_threshold: float
    hide_regex: str | None
    show_regex: str | None

Install with Tessl CLI