# extensions

URL: /kida/api/extensions/
Section: api
Description: Extension/plugin architecture for Kida template engine.

Allows third-party packages to register custom tags, filters, tests,
and globals without modifying core code.

Usage::

    import ast
    from dataclasses import dataclass
    from kida import Environment
    from kida.extensions import Extension
    from kida.nodes.base import Node

    @dataclass(frozen=True, slots=True)
    class DebugNode(Node):
        expr: object  # Expr node

    class DebugExtension(Extension):
        tags = {"debug"}

        def parse(self, parser, tag_name):
            token = parser._advance()  # consume "debug"
            expr = parser._parse_expression()
            parser._expect(parser.TokenType.BLOCK_END)
            return DebugNode(lineno=token.lineno, col_offset=token.col_offset, expr=expr)

        def compile(self, compiler, node):
            expr = compiler._compile_expr(node.expr)
            return [ast.Expr(value=ast.Call(
                func=ast.Name(id="print", ctx=ast.Load()),
                args=[expr], keywords=[],
            ))]

    env = Environment(extensions=[DebugExtension])

---

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

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

Share with AI

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

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

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

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

Module

#
`extensions`

Extension/plugin architecture for Kida template engine.

Allows third-party packages to register custom tags, filters, tests,
and globals without modifying core code.

Usage::

```
import ast
from dataclasses import dataclass
from kida import Environment
from kida.extensions import Extension
from kida.nodes.base import Node

@dataclass(frozen=True, slots=True)
class DebugNode(Node):
    expr: object  # Expr node

class DebugExtension(Extension):
    tags = {"debug"}

    def parse(self, parser, tag_name):
        token = parser._advance()  # consume "debug"
        expr = parser._parse_expression()
        parser._expect(parser.TokenType.BLOCK_END)
        return DebugNode(lineno=token.lineno, col_offset=token.col_offset, expr=expr)

    def compile(self, compiler, node):
        expr = compiler._compile_expr(node.expr)
        return [ast.Expr(value=ast.Call(
            func=ast.Name(id="print", ctx=ast.Load()),
            args=[expr], keywords=[],
        ))]

env = Environment(extensions=[DebugExtension])
```

1Class

## Classes

`Extension`

9

▼

Base class for Kida template extensions.

Subclass this to add custom tags, filters, tests, or glob…

Base class for Kida template extensions.

Subclass this to add custom tags, filters, tests, or globals.

#### Attributes

Name
Type
Description

`tags`

`ClassVar[set[str]]`

Set of block keyword strings this extension handles. When the parser encounters`{% tagname ... %}`, it calls this extension's `parse()`method.

`end_keywords`

`ClassVar[set[str]]`

Set of end keywords for tags with bodies. E.g.,`{"enddebug"}` for a `{% debug %}...{% enddebug %}`tag.

`node_types`

`ClassVar[set[str]]`

—

#### Methods

`get_filters`

0

`dict[str, Callable[..., …`

▼

Return filters provided by this extension.

`def get_filters(self) -> dict[str, Callable[..., Any]]`

##### Returns

`dict[str, Callable[..., Any]]`

`get_tests`

0

`dict[str, Callable[..., …`

▼

Return tests provided by this extension.

`def get_tests(self) -> dict[str, Callable[..., Any]]`

##### Returns

`dict[str, Callable[..., Any]]`

`get_globals`

0

`dict[str, Any]`

▼

Return global variables provided by this extension.

`def get_globals(self) -> dict[str, Any]`

##### Returns

`dict[str, Any]`

`parse`

2

`Node`

▼

Parse a tag handled by this extension.

Called when the parser encounters a blo…

`def parse(self, parser: Any, tag_name: str) -> Node`

Parse a tag handled by this extension.

Called when the parser encounters a block keyword in`self.tags`.
The parser's current token is the tag name token.

##### Parameters

Name
Type
Description

`parser`
`—`

The Parser instance (provides _advance, _expect, _parse_expression, _parse_body, etc.)

`tag_name`
`—`

The keyword that triggered this call.

##### Returns

`Node`

An AST Node (typically a custom frozen dataclass).

`compile`

2

`list[ast.stmt]`

▼

Compile a node produced by this extension's parse().

Called when the compiler …

`def compile(self, compiler: Any, node: Node) -> list[ast.stmt]`

Compile a node produced by this extension's parse().

Called when the compiler encounters a node whose type name
matches a registration from this extension.

##### Parameters

Name
Type
Description

`compiler`
`—`

The Compiler instance (provides _compile_expr, _compile_node, _emit_output, etc.)

`node`
`—`

The AST node to compile.

##### Returns

`list[ast.stmt]`

List of Python AST statements.

Internal Methods
1

▼

`__init__`

1

▼

`def __init__(self, environment: Any) -> None`

##### Parameters

Name
Type
Description

`environment`
`—`