pyinstrument.py

The markata.plugins.pyinstrument plugin adds performance profiling capabilities using pyinstrument. It generates detailed HTML reports showing where your build spends time.

Installation

This plugin is built-in but not enabled by default. Add it to your plugins list:








        

hooks = [
    "markata.plugins.pyinstrument",
]

You must also install pyinstrument:








        

pip install pyinstrument

Uninstallation

Remove the plugin from your hooks list in markata.toml:








        

hooks = [
    # Remove or comment out the line below
    # "markata.plugins.pyinstrument",
]

Configuration

Configure profiling in markata.toml:








        

[markata.profiler]
# Enable/disable profiling
should_profile = true

# Output location (relative to output_dir)
output_file = "_profile/index.html"

# Profile options
interval = 0.001
async_mode = "enabled"
show_all = false
timeline = false

Functionality

Profiling Features

The plugin:

  1. Profiles the entire build process
  2. Generates HTML reports
  3. Shows time distribution
  4. Identifies bottlenecks

Report Generation

Creates reports with:

  • Call tree visualization
  • Time percentages
  • Function details
  • Stack traces

Configuration Options

Supports:

  • Custom output paths
  • Sampling intervals
  • Async mode settings
  • Display options
  • Timeline view

Performance Impact

Note:

  • Minimal overhead
  • Configurable precision
  • Optional async profiling
  • Selective profiling

Dependencies

This plugin depends on:

  • pyinstrument for profiling
  • pydantic for configuration

Function

save function

stop the profiler and save as late as possible

save source








        

def save(markata: Markata) -> None:
    "stop the profiler and save as late as possible"
    if markata.config.profiler.should_profile:
        if markata.config.profiler.profiler is not None:
            if markata.config.profiler.profiler.is_running:
                try:
                    markata.config.profiler.profiler.stop()
                    html = markata.config.profiler.profiler.output_html()
                    markata.config.profiler.output_file.write_text(html)
                    markata.console.print(
                        markata.config.profiler.profiler.output_text()
                    )

                except AttributeError:
                    markata.console.log(
                        "profiler not available, skipping save pyinstrument save",
                    )
                    markata.console.log(
                        "[red]to enable profiler [wheat1][itallic]pip install 'markata\[pyinstrument]'",
                    )

Function

teardown function

stop the profiler on exit

teardown source








        

def teardown(markata: Markata) -> None:
    "stop the profiler on exit"
    # import logging

    # logger = logging.getLogger()
    # logger.handlers.clear()
    if markata.config.profiler.should_profile:
        if markata.config.profiler.profiler is not None:
            if markata.config.profiler.profiler.is_running:
                markata.config.profiler.profiler.stop()

Method

ensure_output_dir_exists method

Ensure output directory exists, creating it if necessary.

ensure_output_dir_exists source








        

def ensure_output_dir_exists(cls, v: Union[str, Path]) -> Path:
        """Ensure output directory exists, creating it if necessary."""
        if isinstance(v, str):
            v = Path(v)
        v.mkdir(parents=True, exist_ok=True)
        return v