# formatter

URL: /kida/api/formatter/
Section: api
Description: Opinionated template formatter for Kida.

Auto-formats Kida templates with consistent whitespace, indentation,
and tag spacing. No other Python template engine has a formatter.

Rules:
- Consistent spacing inside tags: ``{% if x %}`` not ``{%if x%}``
- Consistent spacing in output: ``{{ expr }}`` not ``{{expr}}``
- Indent block bodies by configured amount (default 2 spaces)
- Normalize blank lines (max 1 consecutive)
- Trim trailing whitespace
- Ensure final newline

Usage::

    from kida.formatter import format_template
    formatted = format_template(source)

CLI::

    kida fmt templates/

---

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

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

Share with AI

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

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

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

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

Module

#
`formatter`

Opinionated template formatter for Kida.

Auto-formats Kida templates with consistent whitespace, indentation,
and tag spacing. No other Python template engine has a formatter.

Rules:

- Consistent spacing inside tags:`{% if x %}` not `{%if x%}`

- Consistent spacing in output:`{{ expr }}` not `{{expr}}`

- Indent block bodies by configured amount (default 2 spaces)

- Normalize blank lines (max 1 consecutive)

- Trim trailing whitespace

- Ensure final newline

Usage::

```
from kida.formatter import format_template
formatted = format_template(source)
```

CLI::

```
kida fmt templates/
```

5Functions

## Functions

`format_template`

4

`str`

▼

Format a Kida template source string.

`def format_template(source: str, *, indent: int = 2, max_blank_lines: int = 1, normalize_tag_spacing: bool = True) -> str`

##### Parameters

Name
Type
Description

`source`
`str`

Template source text.

`indent`
`int`

Number of spaces per indentation level.

Default:`2`

`max_blank_lines`
`int`

Maximum consecutive blank lines to allow.

Default:`1`

`normalize_tag_spacing`
`bool`

If True, normalize spacing inside tags.

Default:`True`

##### Returns

`str`

`_normalize_tag_spacing`

1

`str`

▼

Normalize spacing inside template tags.

`def _normalize_tag_spacing(source: str) -> str`

##### Parameters

Name
Type
Description

`source`
`str`

##### Returns

`str`

`_get_block_keyword`

1

`str | None`

▼

Extract the block keyword from a line containing a block tag.

`def _get_block_keyword(line: str) -> str | None`

##### Parameters

Name
Type
Description

`line`
`str`

##### Returns

`str | None`

`_should_dedent_before`

1

`bool`

▼

Check if this line should be dedented (closing/continuation tags).

`def _should_dedent_before(stripped: str) -> bool`

##### Parameters

Name
Type
Description

`stripped`
`str`

##### Returns

`bool`

`_count_indent_change`

1

`int`

▼

Count net indent change for this line.

Returns +1 for block openers, -1 for cl…

`def _count_indent_change(stripped: str) -> int`

Count net indent change for this line.

Returns +1 for block openers, -1 for closers that also re-indent
(like else which dedents then indents).

##### Parameters

Name
Type
Description

`stripped`
`str`

##### Returns

`int`