Modern template engine for Python 3.14t — AST-native, free-threading ready. Works for static sites (Bengal), dynamic web (Chirp), streaming, and framework integration.
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
)彡 Kida
Modern template engine for Python 3.14t
from kida import Environment
env = Environment()
template = env.from_string("Hello, {{ name }}!")
print(template.render(name="World"))
# Output: Hello, World!
What is Kida?
Kida is a modern template engine for Python 3.14t. It works for static site generation (Bengal), dynamic web apps (Chirp), and anywhere you need templates — same syntax, same engine. It compiles templates to Python AST directly (no string generation), supports streaming and block rendering, and is built for free-threading.
What's good about it:
- AST-native — Compiles to Python AST directly. Structured code manipulation, compile-time optimization, precise error source mapping.
- Free-threading ready — Safe for Python 3.14t concurrent execution (PEP 703). All public APIs are thread-safe.
- Dual-mode rendering —
render()uses StringBuilder for maximum throughput.render_stream()yields chunks for streaming HTTP and SSE. - Modern syntax — Pattern matching, pipeline operator, unified
{% end %}, null coalescing, optional chaining. - Zero dependencies — Pure Python, includes native
Markupimplementation.
Installation
pip install kida-templates
Requires Python 3.14+
Quick Start
| Function | Description |
|---|---|
Environment() |
Create a template environment |
env.from_string(src) |
Compile template from string |
env.get_template(name) |
Load template from filesystem |
template.render(**ctx) |
Full page (StringBuilder, fastest) |
template.render_block(name, **ctx) |
Single block (fragments, HTMX) |
template.render_stream(**ctx) |
Generator (chunked HTTP, SSE) |
template.list_blocks() |
Block names for validation |
RenderedTemplate(template, ctx) |
Lazy iterable wrapper for streaming |
Features
| Feature | Description | Docs |
|---|---|---|
| Template Syntax | Variables, filters, control flow, pattern matching | Syntax → |
| Inheritance | Template extends, blocks, includes | Inheritance → |
| Filters & Tests | 40+ built-in filters, custom filter registration | Filters → |
| Streaming | Statement-level generator rendering via render_stream() |
Streaming → |
| Async Support | Native async for, await in templates |
Async → |
| Caching | Fragment caching with TTL support | Caching → |
| Components & Slots | {% def %}, {% call %}, default + named {% slot %} |
Functions → |
| Block Rendering | render_block(), render_with_blocks() for fragments and layout composition |
Framework Integration → |
| Introspection | template_metadata(), block_metadata(), validate_context() for frameworks |
Analysis → |
| Partial Evaluation | Compile-time evaluation of static expressions | Advanced → |
| Block Recompilation | Recompile only changed blocks in live templates | Advanced → |
| Extensibility | Custom filters, tests, globals, loaders | Extending → |
📚 Full documentation: lbliii.github.io/kida
Usage
File-based Templates — Load from filesystem
from kida import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader("templates/"))
template = env.get_template("page.html")
print(template.render(title="Hello", content="World"))
Template Inheritance — Extend base templates
base.html:
<!DOCTYPE html>
<html>
<body>
{% block content %}{% end %}
</body>
</html>
page.html:
{% extends "base.html" %}
{% block content %}
<h1>{{ title }}</h1>
<p>{{ content }}</p>
{% end %}
Control Flow — Conditionals, loops, pattern matching
{% if user.is_active %}
<p>Welcome, {{ user.name }}!</p>
{% end %}
{% for item in items %}
<li>{{ item.name }}</li>
{% end %}
{% match status %}
{% case "active" %}
Active user
{% case "pending" %}
Pending verification
{% case _ %}
Unknown status
{% end %}
Components & Named Slots — Reusable UI composition
{% def card(title) %}
<article class="card">
<h2>{{ title }}</h2>
<div class="actions">{% slot header_actions %}</div>
<div class="body">{% slot %}</div>
</article>
{% end %}
{% call card("Settings") %}
{% slot header_actions %}<button>Save</button>{% end %}
<p>Body content.</p>
{% end %}
{% slot %} is the default slot. Named slot blocks inside {% call %} map to
matching placeholders in {% def %}.
Filters & Pipelines — Transform values
{# Traditional syntax #}
{{ title | escape | capitalize | truncate(50) }}
{# Pipeline operator #}
{{ title |> escape |> capitalize |> truncate(50) }}
{# Custom filters #}
{{ items | sort(attribute="name") | first }}
Streaming Rendering — Yield chunks as they're ready
from kida import Environment
env = Environment()
template = env.from_string("""
<ul>
{% for item in items %}
<li>{{ item }}</li>
{% end %}
</ul>
""")
# Generator: yields each statement as a string chunk
for chunk in template.render_stream(items=["a", "b", "c"]):
print(chunk, end="")
# RenderedTemplate: lazy iterable wrapper
from kida import RenderedTemplate
rendered = RenderedTemplate(template, {"items": ["a", "b", "c"]})
for chunk in rendered:
send_to_client(chunk)
Works with inheritance ({% extends %}), includes, and all control flow. Blocks like {% capture %} and {% spaceless %} buffer internally and yield the processed result.
Async Templates — Await in templates
{% async for item in fetch_items() %}
{{ item }}
{% end %}
{{ await get_user() }}
Fragment Caching — Cache expensive blocks
{% cache "navigation" %}
{% for item in nav_items %}
<a href="{{ item.url }}">{{ item.title }}</a>
{% end %}
{% end %}
Block Rendering — Fragments and layout composition
# Render a single block (HTMX partials, cached nav)
html = template.render_block("content", title="Hello")
# Compose layout with pre-rendered blocks
layout = env.get_template("_layout.html")
html = layout.render_with_blocks({"content": inner_html}, title="Page")
Use Cases
| Use case | Key APIs | Example |
|---|---|---|
| Static sites | render(), fragment cache, bytecode cache |
Bengal |
| Dynamic web | render_block(), render_stream(), render_with_blocks() |
Chirp |
| Streaming / SSE | render_stream(), render_stream_async() |
Chunked HTTP, LLM streaming |
| Framework integration | template_metadata(), validate_block_exists(), get_structure() |
Build adapters, validate routes |
Architecture
Compilation Pipeline — AST-native
Template Source → Lexer → Parser → Kida AST → Compiler → Python AST → exec()
Kida generates ast.Module objects directly. This enables:
- Structured code manipulation — Transform and optimize AST nodes
- Compile-time optimization — Dead code elimination, constant folding
- Precise error source mapping — Exact line/column in template source
Dual-Mode Rendering — StringBuilder + streaming generator
# render() — StringBuilder (fastest, default)
_out.append(...)
return "".join(_out)
# render_stream() — Generator (streaming, chunked HTTP)
yield ...
The compiler generates both modes from a single template. render() uses StringBuilder for maximum throughput. render_stream() uses Python generators for statement-level streaming — ideal for chunked HTTP responses and Server-Sent Events.
Thread Safety — Free-threading ready
All public APIs are thread-safe by design:
- Template compilation — Idempotent (same input → same output)
- Rendering — Uses only local state (StringBuilder pattern)
- Environment — Copy-on-write for filters/tests/globals
- LRU caches — Atomic operations
Module declares itself GIL-independent via _Py_mod_gil = 0 (PEP 703).
Performance
- Simple render — ~0.12ms
- Complex template — ~2.1ms
- Concurrent (8 threads) — ~0.15ms avg under Python 3.14t free-threading
See benchmarks/README.md and benchmarks/RESULTS.md for full Kida vs Jinja2 comparison.
Documentation
| Section | Description |
|---|---|
| Get Started | Installation and quickstart |
| Syntax | Template language reference |
| Usage | Loading, rendering, escaping |
| Framework Integration | Block rendering, introspection, adapters |
| Extending | Custom filters, tests, loaders |
| Reference | Complete API documentation |
| Tutorials | Jinja2 migration, Flask integration |
Development
git clone https://github.com/lbliii/kida.git
cd kida
# Uses Python 3.14t by default (.python-version)
uv sync --group dev --python 3.14t
PYTHON_GIL=0 uv run --python 3.14t pytest
The Bengal Ecosystem
A structured reactive stack — every layer written in pure Python for 3.14t free-threading.
| ᓚᘏᗢ | Bengal | Static site generator | Docs |
| ∿∿ | Purr | Content runtime | — |
| ⌁⌁ | Chirp | Web framework | Docs |
| =^..^= | Pounce | ASGI server | Docs |
| )彡 | Kida | Template engine ← You are here | Docs |
| ฅᨐฅ | Patitas | Markdown parser | Docs |
| ⌾⌾⌾ | Rosettes | Syntax highlighter | Docs |
Python-native. Free-threading ready. No npm required.
License
MIT License — see LICENSE for details.
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
kida_templates-0.2.4.tar.gz
(352.2 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file kida_templates-0.2.4.tar.gz.
File metadata
- Download URL: kida_templates-0.2.4.tar.gz
- Upload date:
- Size: 352.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7cfe4fa227a1cfe4f2d5d96a45e50553c84c85b7e406ec8b5aba6376872ab1c0
|
|
| MD5 |
c1fd882e3e8a16e59e0f65aa28c1008e
|
|
| BLAKE2b-256 |
a193a9f77f8de1fc146b53bde84d57aff0ec9557d6447a5fd24bb6d4fc854e0f
|
Provenance
The following attestation bundles were made for kida_templates-0.2.4.tar.gz:
Publisher:
python-publish.yml on lbliii/kida
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
kida_templates-0.2.4.tar.gz -
Subject digest:
7cfe4fa227a1cfe4f2d5d96a45e50553c84c85b7e406ec8b5aba6376872ab1c0 - Sigstore transparency entry: 1051587763
- Sigstore integration time:
-
Permalink:
lbliii/kida@a45f3eb17f8c02e1935f2678448998ac040c4e60 -
Branch / Tag:
refs/tags/v0.2.4 - Owner: https://github.com/lbliii
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@a45f3eb17f8c02e1935f2678448998ac040c4e60 -
Trigger Event:
release
-
Statement type:
File details
Details for the file kida_templates-0.2.4-py3-none-any.whl.
File metadata
- Download URL: kida_templates-0.2.4-py3-none-any.whl
- Upload date:
- Size: 243.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
24a89c801e73d89553e1b437bad05167cebecb7267fdb72048061d00f83fe060
|
|
| MD5 |
8003e9439c3795fd0b337d7ca233d316
|
|
| BLAKE2b-256 |
b73f895924e00c7c307f3c6f184cf70d9e2f060a0b4b7b20ca15e00b60a248c4
|
Provenance
The following attestation bundles were made for kida_templates-0.2.4-py3-none-any.whl:
Publisher:
python-publish.yml on lbliii/kida
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
kida_templates-0.2.4-py3-none-any.whl -
Subject digest:
24a89c801e73d89553e1b437bad05167cebecb7267fdb72048061d00f83fe060 - Sigstore transparency entry: 1051587772
- Sigstore integration time:
-
Permalink:
lbliii/kida@a45f3eb17f8c02e1935f2678448998ac040c4e60 -
Branch / Tag:
refs/tags/v0.2.4 - Owner: https://github.com/lbliii
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@a45f3eb17f8c02e1935f2678448998ac040c4e60 -
Trigger Event:
release
-
Statement type:
