# compiler

URL: /kida/api/compiler/
Section: compiler
Description: Kida Compiler — transforms Kida AST into executable Python code.

The compiler takes an immutable Kida AST (Template node) and generates a
Python `ast.Module` containing a `render(ctx, _blocks=None)` function.
This is then compiled to a code object via `compile()`.

Architecture:
Kida AST → Python AST → Code Object

Unlike Jinja2 which generates Python source strings, Kida generates
`ast.Module` objects directly. This enables:
- Structured manipulation (no regex, no string parsing)
- Compile-time optimizations (constant folding, dead code elimination)
- Precise source mapping for error messages
- No eval() security concerns

Generated Code Pattern:
    ```python
    def render(ctx, _blocks=None):
        if _blocks is None: _blocks = {}
        _e = _escape          # Cache for LOAD_FAST
        _s = _str
        buf = []
        _append = buf.append  # Cached method lookup

        # Template body...
        _append("Hello, ")
        _append(_e(_s(ctx.get("name", ""))))

        return ''.join(buf)
    ```

Mixin Architecture:
- `ExpressionCompilationMixin`: Expressions, filters, tests, function calls
- `StatementCompilationMixin`: Control flow, blocks, macros, includes
- `kida.compiler.utils`: module-level operator → AST helpers (no mixin)

Thread-Safety:
Compiler instances are single-use and not thread-safe. Create one per
compilation. The resulting code object is immutable and thread-safe.

Public API:
Compiler: Main compiler class combining all compilation mixins

---

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

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

Share with AI

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

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

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

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

Module

#
`compiler`

Kida Compiler — transforms Kida AST into executable Python code.

The compiler takes an immutable Kida AST (Template node) and generates a
Python`ast.Module` containing a `render(ctx, _blocks=None)`function.
This is then compiled to a code object via`compile()`.

Architecture:

Kida AST → Python AST → Code Object

Unlike Jinja2 which generates Python source strings, Kida generates
`ast.Module`objects directly. This enables:

- Structured manipulation (no regex, no string parsing)

- Compile-time optimizations (constant folding, dead code elimination)

- Precise source mapping for error messages

- No eval() security concerns

Generated Code Pattern:

```
```python
def render(ctx, _blocks=None):
    if _blocks is None: _blocks = {}
    _e = _escape          # Cache for LOAD_FAST
    _s = _str
    buf = []
    _append = buf.append  # Cached method lookup

    # Template body...
    _append("Hello, ")
    _append(_e(_s(ctx.get("name", ""))))

    return ''.join(buf)
```
```

Mixin Architecture:



- `ExpressionCompilationMixin`: Expressions, filters, tests, function calls

- `StatementCompilationMixin`: Control flow, blocks, macros, includes

- `kida.compiler.utils`: module-level operator → AST helpers (no mixin)


Thread-Safety:
Compiler instances are single-use and not thread-safe. Create one per
compilation. The resulting code object is immutable and thread-safe.

Public API:

Compiler: Main compiler class combining all compilation mixins