tessl/pypi-gprof2dot

Generate a dot graph from the output of several profilers.

—

Pending

Overview

Eval results

Files

Parser System

Name: tessl/pypi-gprof2dot
Author: tessl

Format-specific parsers for converting profiler output into gprof2dot's internal data model. The parser system supports 13+ different profiler formats including Linux perf, Valgrind callgrind, Python pstats, Java HPROF, and many others.

Capabilities

Base Parser Interface

Abstract base classes that define the parsing interface and provide common functionality for format-specific parsers.

class Parser:
    def __init__(self):
        """Initialize parser base class."""
    
    def parse(self):
        """
        Parse profiler output (abstract method).
        
        Returns:
            Profile: Parsed profile data
            
        Raises:
            NotImplementedError: Must be overridden by subclasses
        """

class LineParser(Parser):
    """Base class for line-based format parsers."""
    
    def __init__(self, stream):
        """
        Initialize line parser.
        
        Args:
            stream: File-like object to read from
        """
    
    def readline(self):
        """Read next line from stream and update internal state."""
    
    def lookahead(self):
        """
        Look at current line without consuming it.
        
        Returns:
            str: Current line content
        """
    
    def consume(self):
        """
        Consume and return current line, advancing to next.
        
        Returns:
            str: Current line content
        """
    
    def eof(self):
        """
        Check if end of file reached.
        
        Returns:
            bool: True if at end of file
        """

class XmlParser(Parser):
    """Base class for XML-based format parsers."""
    
    def parse(self, file):
        """Parse XML profiler output."""

class ParseError(Exception):
    """Exception raised when parsing fails."""
    
    def __init__(self, message, filename=None, lineno=None):
        """
        Initialize parse error.
        
        Args:
            message (str): Error description
            filename (str, optional): Source filename
            lineno (int, optional): Line number where error occurred
        """

Python Profiler Support

Parser for Python's built-in profiling tools (cProfile, profile, pstats).

class PstatsParser(Parser):
    """Parser for Python pstats module output."""
    
    def parse(self, file):
        """
        Parse Python pstats data.
        
        Args:
            file: Binary file containing pstats data
            
        Returns:
            Profile: Parsed profile with function call data
        """

Valgrind Callgrind Support

Parser for Valgrind's callgrind tool output, providing detailed instruction-level profiling data.

class CallgrindParser(Parser):
    """Parser for Valgrind's callgrind tool output."""
    
    def parse(self, file):
        """
        Parse callgrind output format.
        
        Args:
            file: Text file containing callgrind data
            
        Returns:
            Profile: Parsed profile with instruction counts and call relationships
        """

Linux Perf Support

Parser for Linux perf callgraph output, supporting both call stacks and call ratios methods.

class PerfParser(LineParser):
    """Parser for Linux perf callgraph output."""
    
    def parse(self, file):
        """
        Parse perf script output.
        
        Args:
            file: Text file containing perf script data
            
        Returns:
            Profile: Parsed profile with sampling data
        """

GNU gprof Support

Parser for traditional GNU gprof profiler output.

class GprofParser(LineParser):
    """Parser for GNU gprof output."""
    
    def parse(self, file):
        """
        Parse gprof flat and call graph output.
        
        Args:
            file: Text file containing gprof data
            
        Returns:
            Profile: Parsed profile with timing and call data
        """

Java HPROF Support

Parser for Java HPROF profiler output format.

class HProfParser(LineParser):
    """Parser for Java HPROF output."""
    
    def parse(self, file):
        """
        Parse HPROF format data.
        
        Args:
            file: Text file containing HPROF data
            
        Returns:
            Profile: Parsed profile with Java method call data
        """

Intel VTune Support

Parser for Intel VTune Amplifier XE gprof-compatible output.

class AXEParser(LineParser):
    """Parser for VTune Amplifier XE gprof-cc output."""
    
    def parse(self, file):
        """
        Parse VTune gprof-cc format.
        
        Args:
            file: Text file containing VTune data
            
        Returns:
            Profile: Parsed profile with performance counter data
        """

OProfile Support

Parser for OProfile callgraph output format.

class OprofileParser(LineParser):
    """Parser for OProfile callgraph output."""
    
    def parse(self, file):
        """
        Parse OProfile data.
        
        Args:
            file: Text file containing OProfile callgraph data
            
        Returns:
            Profile: Parsed profile with sampling data
        """

Sysprof Support

Parser for Sysprof XML output format.

class SysprofParser(XmlParser):
    """Parser for Sysprof XML output."""
    
    def parse(self, file):
        """
        Parse Sysprof XML format.
        
        Args:
            file: XML file containing Sysprof data
            
        Returns:
            Profile: Parsed profile with system-wide profiling data
        """

Windows XPerf Support

Parser for Windows XPerf CSV output format.

class XPerfParser(LineParser):
    """Parser for XPerf CSV output."""
    
    def parse(self, file):
        """
        Parse XPerf CSV format.
        
        Args:
            file: CSV file containing XPerf data
            
        Returns:
            Profile: Parsed profile with Windows performance data
        """

Very Sleepy Support

Parser for Very Sleepy profiler output format.

class SleepyParser(LineParser):
    """Parser for Very Sleepy output."""
    
    def parse(self, file):
        """
        Parse Very Sleepy format.
        
        Args:
            file: Text file containing Very Sleepy data
            
        Returns:
            Profile: Parsed profile with function timing data
        """

DTrace Support

Parser for DTrace profiler output format.

class DtraceParser(LineParser):
    """Parser for DTrace output."""
    
    def parse(self, file):
        """
        Parse DTrace format.
        
        Args:
            file: Text file containing DTrace data
            
        Returns:
            Profile: Parsed profile with system call tracing data
        """

FlameGraph Support

Parser for FlameGraph stackcollapse format.

class CollapseParser(LineParser):
    """Parser for FlameGraph stackcollapse output."""
    
    def parse(self, file):
        """
        Parse stackcollapse format.
        
        Args:
            file: Text file containing collapsed stack traces
            
        Returns:
            Profile: Parsed profile optimized for flame graph visualization
        """

JSON Format Support

Parser for gprof2dot's custom JSON profile format.

class JsonParser(Parser):
    """Parser for custom JSON profile format."""
    
    def parse(self, file):
        """
        Parse JSON profile format.
        
        Args:
            file: JSON file containing profile data
            
        Returns:
            Profile: Parsed profile from JSON representation
        """

XML Processing Support

Low-level XML processing utilities used by XML-based parsers.

class XmlTokenizer:
    """Expat-based XML tokenizer for streaming XML parsing."""
    
    def __init__(self, fp):
        """
        Initialize XML tokenizer.
        
        Args:
            fp: File-like object containing XML data
        """
    
    def get(self):
        """
        Get the next XML token.
        
        Returns:
            XmlToken: Next token or XML_EOF
        """

class XmlToken:
    """Represents an XML token (element, text, etc.)."""
    
    def __init__(self, type, name_or_data, attrs=None):
        """
        Initialize XML token.
        
        Args:
            type: Token type (XML_ELEMENT_START, XML_ELEMENT_END, etc.)
            name_or_data: Element name or character data
            attrs (dict, optional): Element attributes
        """

class XmlTokenMismatch(Exception):
    """Exception for XML parsing mismatches."""

Format Selection

The parser system uses a format registry to map format names to parser classes:

formats = {
    'axe': AXEParser,
    'callgrind': CallgrindParser,
    'collapse': CollapseParser,
    'dtrace': DtraceParser,
    'hprof': HProfParser,
    'json': JsonParser,
    'oprofile': OprofileParser,
    'perf': PerfParser,
    'prof': GprofParser,
    'pstats': PstatsParser,
    'sleepy': SleepyParser,
    'sysprof': SysprofParser,
    'xperf': XPerfParser
}

Usage Examples

Parsing Different Formats

import gprof2dot

# Parse Python pstats file
parser = gprof2dot.PstatsParser()
with open('profile.stats', 'rb') as f:
    profile = parser.parse(f)

# Parse Valgrind callgrind output
parser = gprof2dot.CallgrindParser()
with open('callgrind.out.1234', 'r') as f:
    profile = parser.parse(f)

# Parse Linux perf output
parser = gprof2dot.PerfParser()
with open('perf.out', 'r') as f:
    profile = parser.parse(f)

Dynamic Parser Selection

import gprof2dot

def parse_profile(filename, format_name):
    """Parse a profile file using the specified format."""
    parser_class = gprof2dot.formats[format_name]
    parser = parser_class()
    
    mode = 'rb' if format_name == 'pstats' else 'r'
    with open(filename, mode) as f:
        return parser.parse(f)

# Usage
profile = parse_profile('callgrind.out.1234', 'callgrind')
profile = parse_profile('profile.stats', 'pstats')

Error Handling

import gprof2dot

try:
    parser = gprof2dot.PstatsParser()
    with open('corrupted.stats', 'rb') as f:
        profile = parser.parse(f)
except gprof2dot.ParseError as e:
    print(f"Parse error: {e}")
    if e.filename:
        print(f"File: {e.filename}")
    if e.lineno:
        print(f"Line: {e.lineno}")

Install with Tessl CLI