Module

profiling

Rosettes HighlightAccumulator — opt-in profiling for syntax highlighting.

This module provides accumulated metrics during highlighting:

  • Per-call language, lexer time, formatter time, total time
  • Code length per call
  • Aggregate statistics

Zero overhead when disabled (get_accumulator() returns None).

Example:

from rosettes import highlight
from rosettes.profiling import profiled_highlight

# Normal highlight (no overhead)
html = highlight("def foo(): pass", "python")

# Profiled highlight (opt-in)
with profiled_highlight() as metrics:
    html = highlight("def foo(): pass", "python")

print(metrics.summary())
# {
#   "total_ms": 1.2,
#   "calls": [{"language": "python", "lexer_ms": 0.3, "formatter_ms": 0.8, ...}],
#   "by_language": {"python": {"count": 1, "total_ms": 1.1}},
# }
2Classes2Functions

Classes

HighlightTiming 5 ▼
Timing data for a single highlight call.

Timing data for a single highlight call.

Attributes

Name Type Description
language str

Language that was highlighted.
lexer_ms float

Lexer tokenization time in milliseconds.
formatter_ms float

Formatter formatting time in milliseconds.
total_ms float

Total highlight time in milliseconds.
code_length int

Length of the code string in characters.
HighlightAccumulator 6 ▼
Accumulated metrics during syntax highlighting. Opt-in profiling for debugging slow highlighting. …

Accumulated metrics during syntax highlighting.

Opt-in profiling for debugging slow highlighting. Zero overhead when disabled (get_accumulator() returns None).

Attributes

Name Type Description
calls list[HighlightTiming]

List of per-call timing data.
start_time float

Profiling start timestamp.

Methods

total_duration_ms 0 float ▼
Total profiling duration in milliseconds.
property
def total_duration_ms(self) -> float
Returns
float
call_count 0 int ▼
Total number of highlight calls recorded.
property
def call_count(self) -> int
Returns
int
record 5 ▼
Record a highlight call.
def record(self, language: str, lexer_ms: float, formatter_ms: float, total_ms: float, code_length: int) -> None
Parameters
Name Type Description
language —

Language that was highlighted.
lexer_ms —

Lexer tokenization time in milliseconds.
formatter_ms —

Formatter formatting time in milliseconds.
total_ms —

Total highlight time in milliseconds.
code_length —

Length of the code string.
summary 0 dict[str, Any] ▼
Get summary of highlight metrics.
def summary(self) -> dict[str, Any]
Returns
dict[str, Any] Dict with total_ms, call_count, calls, and by_language breakdown.

Functions

get_accumulator 0 HighlightAccumulator | N… ▼
Get current accumulator (None if profiling disabled).
def get_accumulator() -> HighlightAccumulator | None
Returns
HighlightAccumulator | None
profiled_highlight 0 Iterator[HighlightAccumu… ▼
Context manager for profiled highlighting. Creates a HighlightAccumulator and …
def profiled_highlight() -> Iterator[HighlightAccumulator]

Context manager for profiled highlighting.

Creates a HighlightAccumulator and makes it available via get_accumulator() for the duration of the with block. The highlight() function checks for the accumulator and records metrics automatically.

Returns
Iterator[HighlightAccumulator]