or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-profiling.mdframework-integration.mdindex.mdoutput-rendering.mdsession-management.md
tile.json

tessl/pypi-pyinstrument

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyinstrument@5.1.x

To install, run

npx @tessl/cli install tessl/pypi-pyinstrument@5.1.0

index.mddocs/

Pyinstrument

A statistical Python profiler that provides detailed call stack analysis to help developers identify performance bottlenecks in their code. Pyinstrument uses low-overhead statistical sampling to capture execution data without significant performance impact, making it suitable for production environments.

Package Information

  • Package Name: pyinstrument
  • Language: Python
  • Installation: pip install pyinstrument
  • Repository: https://github.com/joerick/pyinstrument
  • Documentation: https://pyinstrument.readthedocs.io/

Core Imports

import pyinstrument
from pyinstrument import Profiler, __version__

For context manager/decorator usage:

from pyinstrument import profile

Basic Usage

Simple Profiling with Context Manager

from pyinstrument import Profiler

# Profile a block of code
profiler = Profiler()
profiler.start()

# Your code here
do_some_work()

profiler.stop()
profiler.print()

Using as Context Manager

from pyinstrument import Profiler

with Profiler() as profiler:
    # Your code here
    do_some_work()

# Results automatically printed to stderr

Using as Decorator

from pyinstrument import profile

@profile
def my_function():
    # Your code here
    do_some_work()

my_function()  # Results automatically printed

Architecture

Pyinstrument uses a statistical sampling approach to profiling:

  • Profiler: Main interface for controlling profiling sessions
  • StackSampler: Low-level component that periodically samples the call stack
  • Session: Container for collected profiling data with metadata
  • Frame: Represents individual stack frames in the call hierarchy
  • Renderers: Output formatters for different display needs (console, HTML, JSON)
  • Processors: Frame tree manipulation for filtering and aggregation

The profiler operates by setting up a signal handler or timing thread that periodically interrupts execution to capture the current call stack, building a statistical picture of where time is spent without the overhead of instrumenting every function call.

Capabilities

Core Profiling

Primary profiling functionality including session control, configuration options, and basic output generation. The main Profiler class provides the essential interface for capturing performance data.

class Profiler:
    def __init__(self, interval: float = 0.001, async_mode: str = "enabled", use_timing_thread: bool | None = None): ...
    def start(self, caller_frame=None, target_description: str | None = None): ...
    def stop(self) -> Session: ...
    def reset(self): ...
    def print(self, **kwargs): ...
    def output_text(self, **kwargs) -> str: ...
    def output_html(self) -> str: ...

Core Profiling

Output Rendering

Multiple output formats for displaying profiling results, including interactive HTML with timeline view, console text output with various formatting options, and export formats for integration with other tools.

class ConsoleRenderer:
    def __init__(self, unicode: bool = False, color: bool = False, show_all: bool = False, timeline: bool = False, **kwargs): ...
    def render(self, session: Session) -> str: ...

class HTMLRenderer:
    def __init__(self, timeline: bool = False, show_all: bool = False): ...
    def render(self, session: Session) -> str: ...
    def open_in_browser(self, session: Session): ...

Output Rendering

Session Management

Profiling session data structures and persistence functionality for saving and loading profile results, combining multiple sessions, and accessing detailed timing information.

class Session:
    def save(self, filename: str): ...
    def load(filename: str) -> Session: ...
    def to_json(self, include_frame_records: bool = True) -> dict: ...
    def from_json(json_dict: dict) -> Session: ...
    def combine(session1: Session, session2: Session) -> Session: ...

Session Management

Framework Integration

Built-in integration capabilities for popular Python frameworks and development environments including Jupyter notebooks, Django, FastAPI, and command-line usage.

def load_ipython_extension(ipython): ...

# Context manager and decorator
def profile(**kwargs): ...

Framework Integration

Types

from typing import IO, Any, Literal
import sys
import os
import types

__version__: str  # Package version string (e.g., "5.1.1")

AsyncMode = Literal["enabled", "disabled", "strict"]
FlatTimeMode = Literal["self", "cumulative"]
PathOrStr = str | os.PathLike[str]
FrameRecordType = tuple[list[str], float]

class Session:
    frame_records: list[FrameRecordType]
    start_time: float
    duration: float
    min_interval: float
    max_interval: float
    sample_count: int
    start_call_stack: list[str]
    target_description: str
    cpu_time: float
    sys_path: list[str]
    sys_prefixes: list[str]

class Frame:
    identifier: str
    time: float
    children: list[Frame]
    parent: Frame | None
    file_path: str | None
    function: str | None
    line_no: int | None
    absorbed_time: float
    attributes: dict[str, float]