Module

rendering.template_profiler

Template profiling infrastructure for Bengal SSG.

Provides timing instrumentation for template rendering to identify performance bottlenecks and optimize template code.

Usage:

# Enable via CLI
bengal build --profile-templates

# Access report
report = template_engine.get_template_profile()

Architecture:

TemplateProfiler collects timing data for:

  • Individual template renders (base.html, partials/*.html)

  • Template function calls (get_menu_lang, get_auto_nav, etc.)

  • Include/extends resolution

    Data is thread-safe and aggregated across parallel renders.

See Also:

  • plan/active/rfc-template-performance-optimization.md
  • bengal/rendering/template_engine/core.py
View source
4 Classes 5 Functions

Classes

TemplateTimings dataclass
Timing statistics for a single template.
5

Timing statistics for a single template.

Attributes

Name Type Description
name str
render_times list[float]

Methods 5

count property
Number of times template was rendered.
int 
def count(self) -> int

Number of times template was rendered.

Returns

int

total_ms property
Total render time in milliseconds.
float 
def total_ms(self) -> float

Total render time in milliseconds.

Returns

float

avg_ms property
Average render time in milliseconds.
float 
def avg_ms(self) -> float

Average render time in milliseconds.

Returns

float

min_ms property
Minimum render time in milliseconds.
float 
def min_ms(self) -> float

Minimum render time in milliseconds.

Returns

float

max_ms property
Maximum render time in milliseconds.
float 
def max_ms(self) -> float

Maximum render time in milliseconds.

Returns

float

FunctionTimings dataclass
Timing statistics for a template function.
3

Timing statistics for a template function.

Attributes

Name Type Description
name str
call_times list[float]

Methods 3

count property
Number of times function was called.
int 
def count(self) -> int

Number of times function was called.

Returns

int

total_ms property
Total execution time in milliseconds.
float 
def total_ms(self) -> float

Total execution time in milliseconds.

Returns

float

avg_ms property
Average execution time in milliseconds.
float 
def avg_ms(self) -> float

Average execution time in milliseconds.

Returns

float

TemplateProfiler
Collects and reports template rendering performance data. Thread-safe implementation supports para…
9

Collects and reports template rendering performance data.

Thread-safe implementation supports parallel builds.

Methods 8

enable
Enable profiling.
0 None 
def enable(self) -> None

Enable profiling.

disable
Disable profiling.
0 None 
def disable(self) -> None

Disable profiling.

is_enabled
Check if profiling is enabled.
0 bool 
def is_enabled(self) -> bool

Check if profiling is enabled.

Returns

bool

start_template
Mark start of template render.
1 None 
def start_template(self, template_name: str) -> None

Mark start of template render.

Parameters 1
template_name str

Name of template being rendered
end_template
Mark end of template render and record timing.
1 None 
def end_template(self, template_name: str) -> None

Mark end of template render and record timing.

Parameters 1
template_name str

Name of template that finished rendering
record_function_call
Record a template function call timing.
2 None 
def record_function_call(self, func_name: str, duration: float) -> None

Record a template function call timing.

Parameters 2
func_name str

Name of the function
duration float

Execution time in seconds
get_report
Generate profiling report.
0 dict[str, Any] 
def get_report(self) -> dict[str, Any]

Generate profiling report.

Returns

dict[str, Any] —

Dictionary with template and function timing statistics

reset
Clear all collected timing data.
0 None 
def reset(self) -> None

Clear all collected timing data.

Internal Methods 1
__init__
Initialize the profiler.
0 None 
def __init__(self) -> None

Initialize the profiler.

ProfiledTemplate
Wrapper around Jinja2 Template that adds render timing. Delegates all attribute access to the wrap…
3

Wrapper around Jinja2 Template that adds render timing.

Delegates all attribute access to the wrapped template while intercepting render() calls for profiling.

Methods 1

render
Render template with timing instrumentation.
0 str 
def render(self, *args: Any, **kwargs: Any) -> str

Render template with timing instrumentation.

Returns

str —

Rendered template string

Internal Methods 2
__init__
Initialize the profiled template.
2 None 
def __init__(self, template: Template, profiler: TemplateProfiler) -> None

Initialize the profiled template.

Parameters 2
template Template

Jinja2 Template to wrap
profiler TemplateProfiler

TemplateProfiler for recording timings
__getattr__
Delegate attribute access to wrapped template.
1 Any 
def __getattr__(self, name: str) -> Any

Delegate attribute access to wrapped template.

Parameters 1
name str
Returns

Any

Functions

profile_function
Decorator factory for profiling template functions.
2 Callable[[Callable[… 
def profile_function(profiler: TemplateProfiler, func_name: str) -> Callable[[Callable[P, R]], Callable[P, R]]

Decorator factory for profiling template functions.

Parameters 2

Name Type Default Description
profiler TemplateProfiler —

TemplateProfiler instance
func_name str —

Name to record for this function

Returns

Callable[[Callable[P, R]], Callable[P, R]] —

Decorator that wraps function with timing

format_profile_report
Format profiling report for CLI output.
2 str 
def format_profile_report(report: dict[str, Any], top_n: int = 20) -> str

Format profiling report for CLI output.

Parameters 2

Name Type Default Description
report dict[str, Any] —

Profiling report from TemplateProfiler.get_report()
top_n int 20

Number of top items to show per category

Returns

str —

Formatted report string for display

get_profiler
Get the global template profiler instance.
0 TemplateProfiler | None 
def get_profiler() -> TemplateProfiler | None

Get the global template profiler instance.

Returns

TemplateProfiler | None

enable_profiling
Enable template profiling globally.
0 TemplateProfiler 
def enable_profiling() -> TemplateProfiler

Enable template profiling globally.

Returns

TemplateProfiler —

The global TemplateProfiler instance

disable_profiling
Disable template profiling globally.
0 None 
def disable_profiling() -> None

Disable template profiling globally.