FAQ

Frequently asked questions about Kida.

General

Why Kida instead of Jinja2?

Kida offers:

• Performance: 25-40% faster rendering (StringBuilder vs generators)
• Free-threading: Native PEP 703 support for Python 3.14t
• Zero dependencies: No external packages required
• Modern syntax: Unified{% end %}, pattern matching, pipelines
• Built-in caching:{% cache %}directive for fragment caching

Is Kida production-ready?

Kida is in beta. It's suitable for:

• ✅ Personal projects
• ✅ Internal tools
• ⚠️ Production (test thoroughly first)

What Python versions are supported?

Required: Python 3.14+

Kida uses modern Python features and is designed for the free-threaded future.

Dependencies

Do I need markupsafe?

No. Kida includes a nativeMarkupclass:

from kida import Markup  # Built-in, not markupsafe

Syntax

Why unified{% end %}?

Unified endings are:

• Simpler: One syntax to remember
• Cleaner: Less visual noise
• Consistent: Same pattern for all blocks

{% if condition %}
    {% for item in items %}
        {{ item }}
    {% end %}
{% end %}

What's the pipeline operator?

|>is a more readable way to chain filters:

{# Traditional pipe #}
{{ title | escape | upper | truncate(50) }}

{# Pipeline (same result) #}
{{ title |> escape |> upper |> truncate(50) }}

How does pattern matching work?

{% match %}provides cleaner branching than if/elif chains:

{% match status %}
{% case "active" %}
    ✓ Active
{% case "pending" %}
    ⏳ Pending
{% case _ %}
    Unknown
{% end %}

Performance

How fast is Kida?

Single-threaded: 3.4x faster on minimal templates, ~1.1x on large templates.

Concurrent (8 workers): 1.81x faster due to thread-safe design.

Single-threaded benchmarks undersell Kida. The real advantage emerges under concurrent workloads—Jinja2 actually slows down at 8 workers (negative scaling), while Kida maintains gains.

Why is Kida faster?

• StringBuilder pattern: O(n) vs generator overhead
• AST-native compilation: No string manipulation
• Local variable caching: Fewer attribute lookups
• Compiled regex lexer: 49x faster delimiter detection
• Thread-safe design: No locks, copy-on-write updates

How do I optimize templates?

1. Disableauto_reloadin production
2. Use bytecode cache for cold starts
3. Cache expensive fragments with{% cache %}
4. Precompute complex logic in Python
5. Use concurrent rendering on Python 3.14t for maximum throughput

See Performance.

Threading

Is Kida thread-safe?

Yes. All public APIs are thread-safe:

• Configuration is immutable after creation
• Rendering uses only local variables (no shared mutable state)
• Filter/test additions use copy-on-write (no locks)
• Caches use atomic operations

What's free-threading support?

Kida declares GIL-independence (PEP 703):

_Py_mod_gil = 0  # Safe for free-threading

On Python 3.14t withPYTHON_GIL=0, templates render with true parallelism—no GIL contention.

Can I render concurrently?

Yes, and it's 1.81x faster than Jinja2 at 8 workers:

from concurrent.futures import ThreadPoolExecutor

template = env.get_template("page.html")
contexts = [{"user": f"User {i}"} for i in range(100)]

# On Python 3.14t, this runs with true parallelism
with ThreadPoolExecutor(max_workers=8) as executor:
    results = list(executor.map(lambda ctx: template.render(**ctx), contexts))

Jinja2 has internal contention that causes negative scaling at high concurrency. Kida's thread-safe design avoids this.

Development

How do I debug templates?

Use thedebugfilter:

{{ posts | debug }}
{{ posts | debug("my posts") }}

Output goes to stderr with type info and values.

How do I report bugs?

Open an issue: https://github.com/lbliii/kida/issues

Include:

• Kida version
• Python version
• Minimal reproduction
• Error message

How do I contribute?

See CONTRIBUTING.md in the repository.

See Also

• Comparison — Kida vs Jinja2
• [Troubleshooting] — Common issues