# render_accumulator

URL: /kida/api/render_accumulator/
Section: api
Description: Kida RenderAccumulator — opt-in profiling for template rendering.

This module provides accumulated metrics during template rendering:
- Block render times
- Macro call counts
- Include/embed counts
- Filter usage

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

RFC: kida-contextvar-patterns

Example:
    from kida import Environment
    from kida.render_accumulator import profiled_render

    env = Environment(loader=FileSystemLoader("templates/"))
    template = env.get_template("page.html")

    # Normal render (no overhead)
    html = template.render(page=page)

    # Profiled render (opt-in)
    with profiled_render() as metrics:
        html = template.render(page=page)

    print(metrics.summary())
    # {
    #   "total_ms": 12.5,
    #   "blocks": {
    #     "content": {"ms": 8.2, "calls": 1},
    #     "nav": {"ms": 2.1, "calls": 1},
    #   },
    #   "macros": {"render_card": 15, "format_date": 8},
    #   "includes": {"partials/sidebar.html": 1},
    #   "filters": {"escape": 45, "truncate": 12},
    # }

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/render_accumulator/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Frender_accumulator%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Frender_accumulator%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Frender_accumulator%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Frender_accumulator%2Findex.txt)

Module

#
`render_accumulator`

Kida RenderAccumulator — opt-in profiling for template rendering.

This module provides accumulated metrics during template rendering:

- Block render times

- Macro call counts

- Include/embed counts

- Filter usage

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

RFC: kida-contextvar-patterns

Example:

```
from kida import Environment
from kida.render_accumulator import profiled_render

env = Environment(loader=FileSystemLoader("templates/"))
template = env.get_template("page.html")

# Normal render (no overhead)
html = template.render(page=page)

# Profiled render (opt-in)
with profiled_render() as metrics:
    html = template.render(page=page)

print(metrics.summary())
# {
#   "total_ms": 12.5,
#   "blocks": {
#     "content": {"ms": 8.2, "calls": 1},
#     "nav": {"ms": 2.1, "calls": 1},
#   },
#   "macros": {"render_card": 15, "format_date": 8},
#   "includes": {"partials/sidebar.html": 1},
#   "filters": {"escape": 45, "truncate": 12},
# }
```

4Classes3Functions

## Classes

`BlockTimingSummary`

2

▼

Per-block timing in `summary`() output.

Per-block timing in`summary`() output.

#### Attributes

Name
Type
Description

`ms`

`float`

—

`calls`

`int`

—

`RenderSummary`

5

▼

Structured output of `summary`().

Structured output of`summary`().

#### Attributes

Name
Type
Description

`total_ms`

`float`

—

`blocks`

`dict[str, BlockTimingSummary]`

—

`macros`

`dict[str, int]`

—

`includes`

`dict[str, int]`

—

`filters`

`dict[str, int]`

—

`BlockTiming`

3

▼

Timing data for a single block render.

Timing data for a single block render.

#### Attributes

Name
Type
Description

`name`

`str`

Block name

`duration_ms`

`float`

Total render time in milliseconds

`call_count`

`int`

Number of times the block was rendered

`RenderAccumulator`

11

▼

Accumulated metrics during template rendering.

Opt-in profiling for debugging slow templates.
Zero…

Accumulated metrics during template rendering.

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

#### Attributes

Name
Type
Description

`block_timings`

`dict[str, BlockTiming]`

Block name → timing data

`macro_calls`

`dict[str, int]`

Macro name → call count

`include_counts`

`dict[str, int]`

Template name → include count

`filter_calls`

`dict[str, int]`

Filter name → call count

`start_time`

`float`

Render start timestamp

#### Methods

`total_duration_ms`

0

`float`

▼

Total render duration in milliseconds.

property

`def total_duration_ms(self) -> float`

##### Returns

`float`

`record_block`

2

▼

Record a block render.

If block was already recorded, adds to existing duratio…

`def record_block(self, name: str, duration_ms: float) -> None`

Record a block render.

If block was already recorded, adds to existing duration and
increments call count.

##### Parameters

Name
Type
Description

`name`
`—`

Block name

`duration_ms`
`—`

Render duration in milliseconds

`record_macro`

1

▼

Record a macro invocation.

`def record_macro(self, name: str) -> None`

##### Parameters

Name
Type
Description

`name`
`—`

Macro name (may include template prefix for imports)

`record_include`

1

▼

Record an include/embed.

`def record_include(self, template_name: str) -> None`

##### Parameters

Name
Type
Description

`template_name`
`—`

Name of included template

`record_filter`

1

▼

Record a filter usage.

`def record_filter(self, name: str) -> None`

##### Parameters

Name
Type
Description

`name`
`—`

Filter name

`summary`

0

`RenderSummary`

▼

Get summary of render metrics.

`def summary(self) -> RenderSummary`

##### Returns

`RenderSummary`

## Functions

`get_accumulator`

0

`RenderAccumulator | None`

▼

Get current accumulator (None if profiling disabled).

`def get_accumulator() -> RenderAccumulator | None`

##### Returns

`RenderAccumulator | None`

`profiled_render`

0

`Iterator[RenderAccumulat…`

▼

Context manager for profiled rendering.

Creates a RenderAccumulator and makes …

`def profiled_render() -> Iterator[RenderAccumulator]`

Context manager for profiled rendering.

Creates a RenderAccumulator and makes it available via get_accumulator()
for the duration of the with block. Template code can check for the
accumulator and record metrics.

##### Returns

`Iterator[RenderAccumulator]`

`timed_block`

1

`Iterator[None]`

▼

Time a block render (no-op if profiling disabled).

Use this to wrap block rend…

`def timed_block(name: str) -> Iterator[None]`

Time a block render (no-op if profiling disabled).

Use this to wrap block rendering code. If profiling is not enabled,
this is a no-op with minimal overhead.

##### Parameters

Name
Type
Description

`name`
`str`

Block name for recording

##### Returns

`Iterator[None]`